SCSetScanEnt(3)

NAME
     SCSetScanEnt, SCGetScanEnt, SCEndScanEnt - Getting information about
     installed scanners

SYNOPSIS
     #include <stdio.h>
     #include <scanner.h>

     FILE *SCSetScanEnt(void);

     SCANENT *SCGetScanEnt(FILE *fp);

     int SCEndScanEnt(FILE *fp);

DESCRIPTION
     These routines provide a programmatic interface for reading the file
     /usr/lib/scan/scanners, which contains a one line entry specifying the
     name, driver, device, and options program for each scanner installed on
     the system.

     SCSetScanEnt opens /usr/lib/scan/scanners, returning a pointer to a FILE
     structure.  SCGetScanEnt parses the next line of fp into a SCANENT
     structure, which is declared in <scanner.h> as follows:

          typedef struct tag_scanent {
              char *name;
              char *driver;
              char *device;
              char *options;
          } SCANENT;


     In this structure, name is the name of the scanner assigned by the system
     administrator using scanners(1M) at the time the scanner was installed.
     driver is the name of the scanner driver for this scanner.  device is the
     device parameter passed to the driver, and options is the scanner
     specific options program for this scanner.

     From a scanner application's point of view, name is the only significant
     field.  name is the string to be passed to SCOpen(3) to open a scanner.

RETURN VALUE
     SCSetScanEnt returns a pointer to a FILE structure if successful, or NULL
     if an error occurs.

     SCGetScanEnt returns a pointer to a SCANENT structure, or NULL if there
     are no more scanners left to parse in /usr/lib/scan/scanners.

     SCEndScanEnt returns 0 if successful, -1 if error.
     In the event of an error, SCSetScanEnt and SCEndScanEnt will set SCerrno
     to indicate the cause of the error.

EXECUTION ERROR CODES
     SCENOSCANNERS            No scanners are installed

     In addition, these functions may fail as the result of a failed system
     call, in which case SCerrno will be set to a value from
     /usr/include/sys/errno.h.

EXAMPLE
     The following example prints out the names of all installed scanners.  A
     scanner application can use these functions to present a list of
     installed scanners to the user, so the user can select which one to open.

          #include <stdio.h>
          #include <scanner.h>

          int
          main(void)
          {
              FILE *fp;
              SCANENT *ent;

              if ((fp = SCSetScanEnt()) == NULL) {
                  SCPerror("SCSetScanEnt");
                  exit(1);
              }

              printf("Installed scanners:\n");
              while ((ent = SCGetScanEnt(fp)) != NULL) {
                  printf("%s\n", ent->name);
              }

              SCEndScanEnt(fp);
              exit(0);
          }


WARNING
     The return value of SCGetScanEnt points to memory owned by libscan(3).
     The calling program should not modify the memory pointed to by the return
     value of SCGetScanEnt, nor should any assumptions be made about its value
     after subsequent calls to SCGetScanEnt.  Any needed information should be
     copied into program memory before calling SCGetScanEnt again.

SEE ALSO
     libscan(3), SCOpen(3), scanners(1M).