PDReadInfo(3)
PDReadInfo, PDLocalReadInfo, PDLocalWriteInfo - read/write the printer configuration and status information
As shipped in IRIX 6.5.15. Unchanged since IRIX 6.5.
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. */ /* "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 */ 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). 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. 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. 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 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. 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. 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 ALSO PDReadStatus(3), libpod(3), time(2), ctime(3), podd(1M)