LIBPOD(3) Impressario LIBPOD(3)LIBRARY DESCRIPTIONlibpod 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.
Page 1
LIBPOD(3) Impressario LIBPOD(3)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
Page 2
LIBPOD(3) Impressario LIBPOD(3)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 ALSOpod(4), libspool(3), podd(1M)
Page 3
