libspool(3)

LIBRARY DESCRIPTION
     libspool provides a C Language application programming interface (API) to
     the UNIX printer spooling system. There are two common UNIX printer
     spooling systems, System V and BSD.  While both of these spooling systems
     provide essentially the same capabilities, each has its own command set
     and neither provides a C API.  libspool provides a single API to both
     spooling systems. Spooling functions provided by libspool include print
     job submittal and cancel, print queue reading and control.

LIBRARY ACCESS
     A program that calls libspool functions must include the spool.h header
     file located in the /usr/include directory. In addition, the program must
     link with the libspool.a library located in /usr/lib. The link line would
     look like:

      ... -lspool ...

FUNCTIONS
     Spooling System Selection
                    SLSetSpooler
                    SLGetSpooler

     Printer Information
                    SLGetPrinterList
                    SLGetPrinterInfo
                    SLGetDefPrinterName

     Option Management
                    SLGetPrinterSettings
                    SLSysVGetSpoolerOptions
                    SLSysVGetPrinterOptions
                    SLSysVSaveSpoolerOptions
                    SLSysVSavePrinterOptions

     Print Job Handling
                    SLSubmitJob
                    SLSubmitJobFd
                    SLSubmitJobBuf
                    SLSubmitJobSimple
                    SLCancelJob

     Printer Queue Information
                    SLGetQueue

     Printer Queue Control
                    SLSetSpoolerState
                    SLGetSpoolerState

     Execution Error Handling
                    SLPerror
                    SLGetSpoolerError
ARCHITECTURE
     Many of the libspool functions rely on the System V or BSD spooling
     system shell-level commands to accomplish the actual spooling system
     work. The architecture of the library is depicted below.

                                   User Program
                                         |
                                     libspool
                                         |
                         System V       ___         BSD
                     Spooling Commands       Spooling Commands

DEBUGGING
     If the global variable SLdebug is set to a non-zero value, libspool will
     print debugging information to standard error during execution. The
     global SLdebug is declared in the header file spool.h.

SIGNAL HANDLING (SIGCLD)
     A number of libspool functions spawn child processes to accomplish their
     tasks. The child processes are executed in a blocking fashion whereby the
     parent waits for the child to complete its processing. During the
     execution of a child process, libspool explicitly ignores the SIGCLD
     signal.  Following execution of the child, the library restores the
     original SIGCLD handling. The library uses the POSIX signal handling
     function sigaction(2) to set the state of signal handling. Code that
     links with libspool that must catch the SIGCLD signal should use the
     POSIX signal handling functions to avoid conflicts between signal
     handling mechanisms.

NETWORK OPERATIONS
     Certain libspool functions obtain information about network printers by
     executing remote commands. It may be impossible for libspool to obtain a
     connection to the remote machine (remote machine is down, network is not
     reachable, etc.). In this case the libspool function will timeout and
     return an error code. The timeout period, in seconds, is specified by the
     global variable SLnet_timeout. The default timeout period is specified by
     the value of SL_NET_TIMEOUT in spool.h.

SEE ALSO
     lp(1), lpr(1), sigaction(2)