PDReadStatus(3) Impressario PDReadStatus(3)NAME
PDReadStatus, PDReadOpStatus, PDLocalReadStatus, PDLocalReadOpStatus,
PDLocalWriteStatus - reads/writes the printer status
SYNOPSIS
#include <pod.h>
int PDReadStatus(const char *printer_name,
PDStatusStruct **statusp,
PDMessageStruct **messagesp,
time_t *mod_timep);
int PDLocalReadStatus(const char *printer_name,
PDStatusStruct **statusp,
PDMessageStruct **messagesp,
time_t *mod_timep);
int PDReadOpStatus(const char *printer_name,
int *op_statusp,
time_t *mod_timep);
int PDLocalReadOpStatus(const char *printer_name,
int *op_statusp,
time_t *mod_timep);
int PDLocalWriteStatus(const char *printer_name,
PDStatusStruct *status,
PDMessageStruct *messages);
DESCRIPTION
PDReadStatus and PDLocalReadStatus provide detailed information on the
operational status of the specified printer, printer_name. The functions
fill and return a PDStatusStruct with status information and return an
array of PDMessageStruct messages. The message list consists of errors,
warnings and general information related to the current operational
condition of the printer. The number of messages in the list is given by
the error_count field of the PDStatusStruct. There will be a maximum of
PD_MESSAGE_MAX messages in the list. If error_count is 0, the value of
messagesp is undefined.
PDReadOpStatus and PDLocalReadOpStatus also provide printer status
information. However, only the operational_status field of the
PDStatusStruct is returned.
The status reading functions all set mod_timep to the time the printer
status information was last modified (see time(2)).
PDLocalWriteStatus writes the specified PDStatusStruct and
PDMessageStruct information to the specified printer's status file.
messages is expected to be an array of message structures. The number of
messages in the array must be the same as the number in the error_count
field of the PDStatusStruct and must not exceed PD_MESSAGE_MAX. If there
Page 1
PDReadStatus(3) Impressario PDReadStatus(3)
are no messages to write, messages may be specified as NULL. libpod
provides the PDMakeMessage convenience function to assist in filling a
PDMessageStruct.
Refer to the libpod(3) man page for information about the "Local"
functions.
The PDStatusStruct structure is defined as follows.
typedef struct _pdStatusStruct {
int operational_status; /* Printer status */
int error_count; /* Number of messages */
/* error, warning & info */
int media_type; /* Media type */
int number_of_colors; /* Number of colors */
int media_size; /* Media size */
char printer_options[PD_STR_MAX]; /* Option info */
/* (e.g. "8 MB RAM") */
char validation_mask; /* Size validation mask */
} PDStatusStruct;
operational_status Code indicating the operational status of the printer
(see pod.h).
error_count Total number of error, warning and information
messages available in the err_status field of the
PDInfoStruct and in the messagesp array returned by
PDReadStatus and PDLocalReadStatus. When calling
PDLocalWriteStatus the number of message specified by
this field must match the number of messages in the
messagesp array and must not exceed PD_MESSAGE_MAX.
media_type Code indicating the media type installed in the
printer (see pod.h).
number_of_colors This field is a bitmask in which the number of
colors, colorspace, pixel depth and data format are
specified. The value for this field is constructed by
bitwise OR'ing the values for each of these
attributes. The bitmasks used in this field are all
prefixed PD_DATA_ and can be found in pod.h. Refer to
this file for a list of all possible bitmasks. For
example, to specify an RGB colorspace with eight bits
per pixel and a planar data format set this field to
PD_DATA_PLANAR | PD_DATA_DEPTH8 | PD_DATA_RGB. The
default values for these fields are PD_DATA_K,
PD_DATA_DEPTH1 and PD_DATA_CHUNKY. Macros are
provided to decompose this field into its component
codes. For example, to determine the data depth the
macro PD_GET_DEPTH_CODE(number_of_colors) would be
used. Refer to pod.h for a list of these macros.
Page 2
PDReadStatus(3) Impressario PDReadStatus(3)
media_size Media size code (see pod.h).
printer_options Installed printer options (e.g. "8 MByte RAM"). This
string is also used to indicate the current printer
resolution for printers that support multiple output
resolutions. While the PDInfoStruct contains a
resolution field, typically the nominal resolution is
stated. To specify the current resolution place
"CurrentRes = <xres> x <yres>" in this string. <xres>
and <yres> should be replaced with the current output
resolution. Note that the 'x' can be specified as 'X'
or ',' and whitespace before and after the character
is optional. Printer drivers should update this
string and filter programs that require the current
output resolution should parse for this string before
falling back to using the resolutions in the
PDInfoStruct. If a resolution string is not specified
in this field, the resolution is assumed to be that
specified in the PDInfoStruct. The convenience
function PDGetCurrentResolution(3) performs the above
procedure and returns the current output resolution.
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
media_size field of the PDStatusStruct is used as the
size code to search the page table in the
PDInfoStruct. This table contains size information
for each page size the printer supports. Each page
table entry has a validation mask as well as a size
code. 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.
The PDMessageStruct is defined as follows.
typedef struct _pdMessageStruct {
int message_code;
char message_text[PD_STR_MAX];
} PDMessageStruct;
Page 3
PDReadStatus(3) Impressario PDReadStatus(3)
message_code Error, warning or information message code ID (see
pod.h).
message_text Text for the message truncated to a length of
PD_STR_MAX-1.
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
PDLocalReadStatus, PDLocalReadOpStatus, PDReadStatus and PDReadOpStatus
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.
In addition, PDReadStatus and PDReadOpStatus 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.
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.
Page 4
PDReadStatus(3) Impressario PDReadStatus(3)
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.
PDLocalWriteStatus 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_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.
WARNINGS
1. Upon successful execution, the PDReadStatus and PDLocalReadStatus
functions sets statusp and messagesp to point to internal copies of
the PDStatusStruct and PDMessagesStruct list respectively. The
contents of these structures can change after each libpod function
call. To preserve the contents of the structures across subsequent
libpod calls, they should be copied into user-allocated storage.
2. The functions PDReadStatus and PDReadOpStatus 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 either PDReadStatus
or PDReadOpStatus.
NOTES
1. Since the POD files are owned by the lp account, super-user or lp
account privilege is required to successfully call the
PDLocalWriteStatus function.
Page 5
PDReadStatus(3) Impressario PDReadStatus(3)
2. The PDLocalWriteStatus function writes to the status file only if
the status information and messages in the file differ from those
specified as parameters to the function. The modification time of
the status file is updated only if a write takes place.
FILES
/var/spool/lp/pod/[printer name].status
SEE ALSOPDMakeMessage(3), PDReadInfo(3), libpod(3), time(2), ctime(3)
Page 6
