libpod(3)

LIBRARY DESCRIPTION
     libpod provides a C language application programming interface (API) to
     the Printer Object Database (POD). The libpod library provides printer
     driver developers with an API to create and maintain a POD and provides
     application developers with the means to acquire detailed information
     about a printer. A POD contains information on the current configuration,
     state and job history of a single printer. Each printer physically
     installed on a system maintains its own POD. All interaction with a
     printer's POD should be done through libpod. Direct modification of the
     POD files is strongly discouraged. For detailed information on the
     creation and format of the POD files refer to the pod(4) man page.

POD FILES
     A Printer Object Database consists of three separate ASCII text files.
     The name of each POD file is formed from the printer name and the suffix
     .config, .status and .log, respectively.  The information contained in
     each file is summarized below.

     [printer name].config
                    This file contains detailed information on the printer's
                    capabilities.  Examples include the possible paper sizes,
                    printer location and available fonts. Initially, this file
                    is created by the printer driver developer and a copy is
                    installed when the printer is added to the system. The
                    contents of this file are typically maintained by the
                    system administrator and are not normally changed.

     [printer name].status
                    This file contains information about the current
                    operational status of the printer. The information in the
                    file indicates whether the printer is busy, what type of
                    printing media is installed, and so on. The contents of
                    this file change during every print job.

     [printer name].log
                    This file contains the print job history for the printer,
                    information for old as well as current print jobs.

     The default location for POD files is /var/spool/lp/pod. The global
     variable PDpod_path indicates the location of the POD files and is set to
     the default path by libpod. Note that PDpod_path is set to
     /usr/spool/lp/pod which is linked to /var/spool/lp/pod. This is for
     compatilibty with printer hosts running older versions of the IRIX
     operating system. If POD files are to be located in a directory other
     than the default, PDpod_path should be set to the pathname of the new
     location. PDpod_path is declared in the header file pod.h. Note that the
     maximum string length for PDpod_path is PD_STR_MAX. This includes the
     terminating NULL character.
FUNCTIONS
     Many libpod functions come in two forms, a standard form and a local
     form.  The POD files reside only on the system to which the printer is
     physically connected, referred to as the printer host. Therefore, to
     provide information about a printer located on another system, libpod
     must be able to communicate across the network. The standard form of the
     libpod functions (i.e. functions whose names do not contain the word
     "local") automatically determine whether the specified printer is located
     on the user's system (a local printer), or whether the printer is on a
     remote system (a remote printer). After determining where the printer is
     located, the standard functions access the POD files on the appropriate
     system. Since network communication carries a certain amount of
     performance overhead, libpod provides the local functions (i.e. the names
     with the word "local"). These functions are provided for use by programs
     that are guaranteed to be run on the printer host machine. A printer
     driver is an example of such a program.  Typically, user application
     programs such as printer status tools use the standard form of the libpod
     functions, since it is likely that these programs will need to work with
     remote printers.

     Note that the functions that write to POD files (e.g. PDLocalWriteLog)
     are available only in local form. Since only printer drivers should have
     a need to write to the POD files, there is no need to provide for writing
     to the files from anywhere except from the system to which the printer is
     physically connected.

     Detailed Information Manipulation
               PDReadInfo        PDLocalReadInfo
                                 PDLocalWriteInfo

     Status File Manipulation
               PDReadStatus      PDLocalReadStatus
                                 PDLocalWriteStatus
               PDReadOpStatus    PDLocalReadOpStatus

     Log File Manipulation
               PDReadLog         PDLocalReadLog
                                 PDLocalWriteLog

     Convenience Functions
               PDMakeMessage
               PDFindPageSize
               PDGetCurrentResolution
               PDGetSizeCodeByName
               PDGetNameBySizeCode

     Execution Error Handling
               PDPerror
LIBRARY ACCESS
     Programs that call libpod functions must include the pod.h header file
     located in the /usr/include directory. In addition, the programs must
     link with the libpod.a library located in /usr/lib. Programs that use the
     standard functions must also link with libspool.a. Programs that use only
     the local functions need not link with this additional library. The link
     lines for each case would be:

     When using standard functions:    ... -lpod -lspool ...
     When using only local functions:  ... -lpod ...

NETWORK COMMUNICATION
     To provide remote printer POD information, libpod communicates over the
     network with the podd(1M) daemon on the remote machine. Since the network
     or remote machine may be down when a libpod function is executed, a
     timeout may occur and the function will return the appropriate error
     code. The timeout period can be specified by setting the global variable
     PDnet_timeout to a value in seconds. The default timeout period is shown
     in the header file pod.h. While a large timeout period is appropriate
     when reading printer status, a much smaller timeout may be appropriate
     for browsing printer configurations.

     For more information on the daemon refer to the podd(1M) man page.

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

WARNING
     The standard form of the libpod functions call the libspool function
     SLGetPrinterInfo. This libspool function is not reentrant. This means
     that any pointer returned by a previous call to SLGetPrinterInfo will be
     invalid after a call to the standard form of the libpod functions.

SEE ALSO
     pod(4), libspool(3), podd(1M)