PDReadStatus(3)
PDReadStatus, PDReadOpStatus, PDLocalReadStatus, PDLocalReadOpStatus, PDLocalWriteStatus - reads/writes the printer status
As shipped in IRIX 6.5.30. Unchanged since IRIX 6.5.
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 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. 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; 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. 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. 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 ALSO PDMakeMessage(3), PDReadInfo(3), libpod(3), time(2), ctime(3)