PDReadInfo(3) Impressario PDReadInfo(3)NAME
PDReadInfo, PDLocalReadInfo, PDLocalWriteInfo - read/write the printer
configuration and status information
SYNOPSIS
#include <pod.h>
int PDReadInfo(const char *printer_name, PDInfoStruct **infop,
time_t *mod_timep);
int PDLocalReadInfo(const char *printer_name,
PDInfoStruct **infop, time_t *mod_timep);
int PDLocalWriteInfo(const char *printer_name,
PDInfoStruct *info);
DESCRIPTION
PDReadInfo and PDLocalReadInfo fill a PDInfoStruct structure with the
current configuration and status information for the specified printer,
printer_name. infop is set to point to the newly filled structure.
mod_timep is set to the time the printer information was last modified
(see time(2)). PDReadInfo will read information from local and remote
printers.
PDLocalWriteInfo writes the specified PDInfoStruct structure to the
specified printer's configuration and status files. info should point to
a filled in PDInfoStruct structure. If the active_status field of the
PDInfoStruct is NULL, only the configuration file information will be
modified. In this case the error_status field will be ignored. This
function should only be used by administrative applications that need to
modify a local printer's configuration information (e.g. a printer
installation program). Printer drivers and application programs should
not modify the printer configuration information.
Refer to the libpod(3) man page for more information about the "Local"
functions.
The PDInfoStruct contains detailed information about a printer's
capabilities as well as its current operational status. The structure
does not contain log file information. The PDInfoStruct structure is
defined as follows.
typedef struct _pdInfoStruct {
char printer_class[PD_STR_MAX]; /* e.g. "PostScript", */
/* "Color Raster", */
/* "Plotter" */
char printer_model[PD_STR_MAX]; /* e.g. "Phaser II SX" */
char printer_options[PD_STR_MAX]; /* Option info */
/* (e.g. "8 MB RAM") */
char location_code[PD_STR_MAX]; /* Machine parsable, no */
/* blanks, e.g. "3U-924" */
char physical_location[PD_STR_MAX]; /* Human readable, e.g. */
Page 1
PDReadInfo(3) Impressario PDReadInfo(3)
/* "Bldg. 3U, Room 924" */
char technology[PD_STR_MAX]; /* e.g. "Ink Jet", */
/* "Wax Transfer" */
char config_path[PD_STR_MAX]; /* Path to config file */
char driver_path[PD_STR_MAX}; /* Driver pathname */
char port_path[PD_STR_MAX]; /* Device port pathname */
char active_path[PD_STR_MAX]; /* Path to status file */
int error_retry_wait; /* Driver error retry */
/* interval, seconds */
int status_update_wait; /* Status polling */
/* interval, seconds */
int media_wait; /* Manual feed wait */
/* time, seconds */
int horizontal_resolution; /* Resolutions, dpi */
int vertical_resolution;
float cost_per_page; /* Cost in local */
/* currency e.g. 0.50 */
int avg_time_per_page; /* Times in seconds */
int max_time_per_page;
int min_number_of_colors; /* No. of colors available*/
int max_number_of_colors;
float min_area_horizontal; /* Printable areas, in. */
float min_area_vertical;
float max_area_horizontal;
float max_area_vertical;
int min_addr_horizontal; /* Printable areas, dots */
int min_addr_vertical;
int max_addr_horizontal;
int max_addr_vertical;
int quality_modes; /* No. of quality modes */
char **quality_mode_names; /* Mode names */
int default_quality_mode; /* Default mode index */
int manual_capable; /* Manual feed capable, */
/* 0 = no, 1 = yes */
int black_substitute; /* Substitute true black */
/* for composite black, */
/* 0 = no, 1 = yes */
int media_standard; /* Media measurement */
/* standard, e.g. Metric */
int avail_fonts; /* Number of fonts */
char **avail_fonts_names; /* Font names */
int input_sources; /* No. of input sources */
char **input_sources_names; /* Input source names */
int default_input_source; /* Default input index */
float input_source_gamma; /* Source gamma value */
int color_adjustment; /* Number of color */
/* adjustment schemes */
char **color_adj_names; /* Color adj scheme names */
int default_color_adj; /* Default adj scheme */
/* index */
int media_types; /* Number of media types */
char **media_types_names; /* Media type names */
Page 2
PDReadInfo(3) Impressario PDReadInfo(3)
int default_media_type; /* Default media type */
int size_table_entries; /* Number of media size */
/* table entries */
PDSizeTableStruct *size_table; /* Media size table */
PDStatusStruct *active_status; /* Status information */
PDMessageStruct *error_status; /* Error, warning and */
/* info messages */
} PDInfoStruct;
printer_class Printer class string (e.g. "ColorPostScript",
"Plotter").
printer_model Printer model name (e.g. "LaserWriter II NTX").
printer_options Installed printer options (e.g. "8 MByte RAM",
"PostScript Cartridge").
location_code Physical location of the printer in machine parsable
format (e.g. "3U-924").
physical_location Physical location of the printer in human readable
format (e.g. "Bldg. 3U, Room 924").
technology Printing technology (e.g. "Wax transfer", "Dye
sublimation").
config_path Complete pathname of configuration file. This is set
to PDpod_path/[printer_name].config by libpod.
driver_path Complete pathname of printer driver program (e.g.
"/usr/lib/print/phandler").
port_path Complete pathname of printer port device driver (e.g.
"/dev/plp").
active_path Complete pathname of status file. This is set by
libpod to be PDpod_path/[printer_name].status.
error_retry_wait Number of seconds to wait before attempting to resume
printing following an error.
status_update_wait Number of seconds between updates of the printer
status file.
media_wait Number of seconds to wait for manual or print media
changes.
horizontal_resolution, vertical_resolution
Horizontal and vertical printer resolution in dots
per inch (dpi).
Page 3
PDReadInfo(3) Impressario PDReadInfo(3)
cost_per_page Cost per page in local currency (e.g. "0.50" for 50
cents per page).
avg_time_per_page, max_time_per_page
Average and maximum time to print a page in seconds.
min_number_of_colors, max_number_of_colors
Minimum and maximum number of colors available. A
monochrome printer or printer ribbon would provide
one available color. A CMY printer or ribbon would
provide three colors. A CMYK printer or ribbon would
provide four colors. Note that these fields should
only contain the number of colors as opposed to the
number_of_colors field in the PDStatusStruct which is
used as a bitmask to specify the current number of
colors as well as the colorspace, pixel depth and
data format.
min_area_horizontal, min_area_vertical
Minimum printable horizontal and vertical dimensions
in inches.
max_area_horizontal, max_area_vertical
Maximum printable horizontal and vertical dimensions
in inches.
min_addr_horizontal, min_addr_vertical
Minimum printable horizontal and vertical dimensions
in dots.
max_addr_horizontal, max_addr_vertical
Maximum printable horizontal and vertical dimensions
in dots.
quality_modes Number of printer quality modes.
quality_mode_names Names of quality modes (e.g. "draft", "letter").
default_quality_mode
The default quality mode expressed as an index into
the list of quality mode names. Note that this value
is based at one rather than zero. To use this value
as an array index, subtract one from the value.
manual_capable Boolean indicating whether the printer is (1) or is
not (0) capable of manual feed.
black_substitute Boolean indicating whether true black should (1) or
should not (0) be substituted for composite black.
Page 4
PDReadInfo(3) Impressario PDReadInfo(3)
media_standard Code indicating paper measurement standard in use
(see pod.h). The measurement standard is typically
American or Metric.
avail_fonts Number of available fonts.
avail_fonts_names Names of available fonts (e.g. "Courier",
"Helvetica").
input_sources Number of printer input sources.
input_sources_names Names of possible printer input sources (e.g. "Sony
16 inch Monitor").
default_input_source
Default input source expressed as an index into the
list of input source names. The input source is
typically used for determining printer color
correction. Note that this value is based at one
rather than zero. To use this value as an array
index, subtract one from the value.
input_source_gamma Gamma value of the input source. This value is
typically used in determining printer color
correction.
color_adjustment Number of printer color correction schemes.
color_adj_names Names of available color correction schemes (e.g.
"Improve Blue").
default_color_adj Default color correction scheme expressed as an index
into the list of color correction names. Note that
this value is based at one rather than zero. To use
this value as an array index, subtract one from the
value.
media_types Number of possible media types.
media_types_names Names of possible media types (e.g. "Paper",
"Transparency").
default_media_type Default media type expressed as an index into the
list of media type names. Note that this value is
based at one rather than zero. To use this value as
an array index one must be subtracted.
size_table_entries Number of entries in the print media size table.
size_table An array of printer media size table entries. Each
entry describes a single print medium in detail. See
below for detailed information on this structure.
Page 5
PDReadInfo(3) Impressario PDReadInfo(3)
active_status Pointer to the printer status information structure.
Refer to PDReadStatus(3) for detailed information on
this structure.
error_status Pointer to the printer message list. This is an array
of printer error, warning and information messages.
The number of messages in the array is given by the
error_count field of the active_status structure.
The PDSizeTableStruct is defined as follows.
typedef struct _pdSizeTableStruct {
int media_size; /* Generic media name token */
int horizontal_addr; /* Horizontal dots */
int vertical_addr; /* Vertical dots */
float width; /* Width in inches */
float length; /* Length in inches */
float left_margin; /* Left margin in inches */
float top_margin; /* Top margin in inches */
char raster_definition; /* Raster direction and */
/* orientation bits */
char validation_mask; /* Entry validation */
char variable_page_size; /* Reserved */
} PDSizeTableStruct;
media_size Media size code (see pod.h).
horizontal_addr, vertical_addr
Number of horizontal and vertical dots. This is also
the length of each raster line and the number of
raster lines, respectively.
width Width of the medium in inches along the raster line.
length Length of the medium in inches perpendicular to the
raster line.
left_margin Non-printable distance in inches to the left of each
raster line.
top_margin Non-printable distance in inches before the first
raster line.
raster_definition Code describing the direction and orientation of the
printer raster (see pod.h).
validation_mask Size table entry validation mask. If PDFindPageSize
is called with a size code of PD_SIZE_CURRENT,
dimensional information for the currently loaded
paper size will be returned. The mechanics of
determining this information is as follows. The
Page 6
PDReadInfo(3) Impressario PDReadInfo(3)
media_size field of the PDStatusStruct is used as the
size code to search the page table in the
PDInfoStruct. Dimensional information is returned
for the page size entry that matches the media_size
value and whose validation masks satisfy the
relationship (status mask & table mask) == status
mask. The validation mask can be helpful in
specifying page dimensions for printers that support
multiple resolutions. The page table can contain a
number of page names that are identical but with
dimensions appropriate to different resolutions. Each
entry would have a unique validation mask. This way
the status validation mask could be used to select
the proper page size for the current output
resolution.
variable_page_size Reserved for future use. When writing the size table
always set this field to 0.
RETURN VALUE
0 is returned if execution was successful. -1 is returned and PDerrno is
set if an execution error has occurred.
EXECUTION ERROR CODES
PDReadInfo and PDLocalReadInfo will fail under the following
circumstances.
PD_LIBERR_BAD_PNAME A NULL or empty printer name string has been
specified.
PD_LIBERR_STATUS_READ The status file could not be opened for reading
or an error occurred while reading the file.
PD_LIBERR_CONFIG_READ The config file could not be opened for reading
or an error occurred while reading the file.
In addition, PDReadInfo will fail under the following circumstances.
PD_LIBERR_NO_PRINTER The specified printer has not been registered
with the printer spooling system and is,
therefore, inaccessible.
PD_LIBERR_BAD_HOSTNAME The network address of the specified hostname
could not be found.
PD_LIBERR_NETWORK For an unknown reason, a network connection
could not be made with the remote printer host.
PD_LIBERR_NET_TIMEOUT A timeout occurred while attempting to
communicate with the remote printer host.
Page 7
PDReadInfo(3) Impressario PDReadInfo(3)
PD_LIBERR_NET_INTR The program has been interrupted while
attempting to communicate with the remote
printer host.
PD_LIBERR_NET_NOTREG The podd daemon is not registered on the remote
printer host.
PD_LIBERR_NET_PMAP The port mapper daemon failed on the remote
printer host.
PD_LIBERR_NET_NOPROC The client has called a libpod function that is
not supported by the podd daemon on the remote
printer host.
PD_LIBERR_NET_CLNTXDR The libpod library XDR routines and the kernel's
XDR routines are incompatible.
PD_LIBERR_NET_SVCXDR The podd daemon XDR routines and the remote
printer host's kernel XDR routines are
incompatible.
PD_LIBERR_NET_RPCMATCH The version of RPC software on the client is
incompatible with the version on the remote
printer host.
PD_LIBERR_NET_PROCMATCH The version of the specified libpod function on
the client is incompatible with the version on
the remote printer host.
PDWriteInfo will fail under the following circumstances.
PD_LIBERR_BAD_STRUCT A NULL structure pointer has been specified.
PD_LIBERR_BAD_PNAME A NULL or empty printer name string has been
specified.
PD_LIBERR_CONFIG_WRITE The config file could not be opened for writing
or an error occurred while writing the file.
PD_LIBERR_STATUS_WRITE The status file could not be opened for writing
or an error occurred while writing the file.
PD_LIBERR_MAX_MESSAGE A request has been made to write more than
PD_MESSAGE_MAX messages to the status file.
PD_LIBERR_BAD_MSGCNT An invalid value has been specified for the
number of messages to write to the status file.
Page 8
PDReadInfo(3) Impressario PDReadInfo(3)WARNINGS
1. Upon successful execution, the function sets infop to point to an
internal copy of the PDInfoStruct. The contents of this structure
can change after each libpod function call. To preserve the contents
of the structure across libpod calls, it should be copied into
user-allocated storage.
2. The function PDReadInfo calls 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 PDReadInfo.
NOTES
1. PDReadInfo and PDLocalReadInfo obtain printer information from the
config and status POD files. mod_timep is set to the modification
time of the file that has been most recently modified.
2. The PDWriteInfo function ignores the config_path and active_path
fields of the PDInfoStruct. The function automatically provides
pathname values for these fields.
FILES
/var/spool/lp/pod/[printer name].config
/var/spool/lp/pod/[printer name].status
SEE ALSOPDReadStatus(3), libpod(3), time(2), ctime(3), podd(1M)
Page 9
