pod(4)
pod - Printer Object Database (POD) file formats
As shipped in IRIX 6.5.7. Unchanged since IRIX 6.5.
NAME pod - Printer Object Database (POD) file formats DESCRIPTION This manual page details the formats for the Printer Object Database (POD) files. The POD contains information on the current configuration, status and job history of a single printer. Each printer physically installed on a system maintains its own POD. An initial set of POD files is created by the printer driver developer and installed on the system. This initial set of POD files must include a config file representing the capabilities of the printer, a status file indicating a typical printing state and an empty log file. All subsequent interaction with the POD is done through the libpod(3) API. The API provides network transparent, mediated access to the POD files. A Printer Object Database consists of three separate ASCII text files. There is one set of these files for each printer physically installed on a system. The name of each POD file is formed from the printer name and the suffix .config, .status and .log, respectively. All POD files are located in the directory /var/spool/lp/pod. The information contained in each file is summarized below and explained in detail in subsequent sections. <printer name>.config This file contains detailed information on the printer's capabilities. The file is created by the driver developer to characterize the printer's capabilities. For example, the possible paper sizes, printer location and available fonts are all specified in this file. Typically the information in the config file does not change over time. Printer filters and drivers treat the config file as read-only. The printer install tools may modify the config file at printer installation time to enter site specific information (e.g. printer location) or note the presence of optional equipment (e.g. duplex option or envelope feeder). <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. While the driver developer provides an initial copy of the status file, it is the job of the driver to update the file. Typically, printer filter programs treat the status file as read- only. <printer name>.log This file contains the print job history for the printer. Information for old jobs as well as the current print job is maintained. Typically, printer filters and drivers append information to the log file while general applications treat the file as read-only. GENERAL SYNTAX Character Set <space>: 0x09, 0x20 (<sp>, <ht>) <null>: 0x00-0x08, 0x0B, 0x0C, 0x0E-0x1F, 0x7F-0xFF <endline>: 0x0A, 0x0D (<nl>, <cr>) <separator>: 0x7C ('|') <plainchar>: 0x21-0x7B, 0x7D, 0x7E <ddigit>: 0x30-0x39 ('0'-'9') <hdigit>: <ddigit>, 0x41-0x46, 0x61-0x66 ('0'-'9', 'A'-'F', 'a'-'f') <sign>: 0x2B, 0x2D ('+', '-') <point>: 0x2E ('.') Field Format <white>: <space> [<space>...] <word>: <plainchar> [<plainchar>...] <keyword>: <word> with a specific sequence of <plainchar> <keyfield>: [<white>] <keyword> [[<white> <keyword>]...] [<white>] <string>: [<white>] <word> [[<white> <word>]...] [<white>] <int>: <ddigit> [<ddigit>...] <hbyte>: ["0x" | "0X"] [<hdigit>] <hdigit> <float>: [<sign>] <int> [<point> [<int>]] or [<sign>] <point> <int> <array>: <string> [[<separator> <string>]...] INPUT PARSING RULES The following rules apply when a POD file is parsed by the libpod API. o All <null> characters are ignored; their use is not recommended. This provision is intended to avoid errors caused by non-printing characters appearing in the POD files. o All input lines are truncated to PD_STR_MAX-1, not counting <null> characters and <endline>, which are removed on input. The value of PD_STR_MAX is defined in the header file /usr/include/pod.h. o All occurrences of <white> sequences are reduced to a single <sp> character. In addition, <white> appearing at the beginning or end of a field is removed. o There are no quoted strings. Quotation marks are treated like any other character, and cannot be used to force additional <white> into a field. o All fields are checked for correct syntax based on entry type. Failure to provide information in the correct format will result in improper parsing. o When scanning for <int> or <float> numbers within a field, all characters that are not valid within an <int> or <float> are treated as <white> (in the case of an <int>, <sign> and <point> are treated as <white>). This allows characters to be inserted to improve readability. For example, the following are equivalent if two <int> items are expected: 300 300 300 x 300 300 by 300 300,300 o Entries containing no characters other than <white> prior to the first <separator> or <endline> are treated as null entries and discarded without error. These lines may be used as comments simply by placing a <separator> prior to any other information. o Blank lines are ignored and may be inserted to improve readability. o <keyfield> matching is done in a case independent manner. o Fields designed to be human readable are not modified, except to remove <null> and excess <white>. Case and all <plainchar> sequences are preserved. o A <keyfield> may require a long list of items (e.g. Available Fonts). To improve readability and avoid the risk of input line buffer overflow, these <keyfield> may be repeated. For example, a list of fifty Available Fonts items may be broken into two Available Fonts entries with 25 items each. The overall number of items that can be specified in a list is limited only by available system memory resources. o There is no required entry order. The <keyfield> entries may appear in any order within a POD file. o Default values are assumed for certain fields if values have not been specified. The values of these defaults should not be relied upon and may change in future releases. CONFIG FILE FORMAT This section describes the printer configuration file format. The configuration file is installed in /var/spool/lp/pod with the name <printer name>.config. The general format for config file entries is: <keyfield> <separator> [<infofield>] <endline> where <infofield> is specified in the table below. The Size Table Entry <infofield> has the format <sizeentry> defined as: <sizeentry>: <keyword> <int> <int> <float> <float> <float> <float> [<hbyte> [<hbyte>]] All entries in the config file are optional. Entries that are not provided or that have no <infofield> specified will be assigned default values. However, since printer capabilities differ, it is recommended that entries be omitted and defaults be used only for entries that are truly inapplicable (e.g. manual feed or quality modes). Key Field <infofield> Default _______________________________________________________________ Printer Class <keyword> Dumb Printer Model <string> Unknown Printer Options <string> (empty string) Technology <string> Unknown Location Code <keyword> NONE Physical Location <string> Unknown Driver Path <word> (see description) Port Path <word> /dev/null Active Status Path <word> (see description) Error Retry Wait <int> 10 Status Update Wait <int> 300 Media Wait <int> 300 Resolution <int> <int> 300 300 Minimum Print Area <float> <float> (see description) Maximum Print Area <float> <float> (see description) Minimum Addr <int> <int> (see description) Maximum Addr <int> <int> (see description) Cost per Page <float> 0.0 Time per Page <int> [<int>] 0 0 Number of Colors <int> [<int>] 1 1 Quality Modes <array> (0 elements) Default QM <int> 0 Manual Capable <keyword> No Black Substitute <keyword> No Media Standard <keyword> American Available Fonts <array> (0 elements) Input Source <array> (0 elements) Default IS <int> [,gamma=<float>] 0, gamma=-1.0 Color Adjustment <array> (0 elements) Default CA <int> 0 Media Type <array> (0 elements) Default MT <int> 0 Size Table Entry <sizeentry> (see description) Printer Class Keyword specifying the class of printer. Available values are: Dumb Raster ColorRaster ColorPostScript MonoPostScript Plotter Obsolete values are: DumbColor Color PostScript Printer Model Manufacturer's description of the printer. For example, Tektronix Phaser II SX or Apple LaserWriter II NTX. Printer Options Installed printer options. For example, 8 Mbytes RAM. Technology Printing technology. For example, ink jet, wax transfer, dye sublimation, color laser. Location Code Site specific keyword identifying the printers physical location. For example, 3U-924. Physical Location Human-readable description of printer's physical location. For example, Bldg. 3 Upper, Room 924. Driver Path Full pathname of printer driver. The default value for this entry is the full pathname of the POD config file with the suffix .config removed. Port Path Full pathname of the I/O port to which the printer is physically connected. For example, /dev/plp for a parallel printer, /dev/ttyd2 for a serial printer and /dev/scsi/sc0d6l0 for a SCSI printer. Active Status Path Full pathname of the POD status file. The value of this entry is not used by the libpod API. The value of this entry is always set by the API to PDpod_path/<printer name>.status. Refer to the libpod(3) man page for additional information. Error Retry Wait Number of seconds to wait after an before attempting to resume printing after an error has occurred. Status Update Wait Number of seconds to between updates of the POD status file when no error has occurred. Media Wait Number of seconds to wait for manual feed or print media changes before default media source is used. Resolution Maximum horizontal and vertical printer resolution in dots per inch (dpi). For printers that allow multiple resolutions, the status file Printer Options entry should be parsed for the CurrentRes keyword. This keyword indicates the current printer resolution. If the keyword is not found, the config file Resolution entry should be used. Minimum Print Area, Maximum Print Area Minimum and maximum printable area dimensions expressed in inches. The default values for these entries assume an A size page (8.5 by 11.0 inches) in portrait orientation with 0.5 inch margins. This gives a printable area of 7.5 by 10.0 inches (i.e. 7.5 10.0). The minimum and maximum values are identical in the default case. If a Page Size Table has been specified, the values for this entry are derived from it. Minimum Addr, Maximum Addr Minimum and maximum printable area dimensions expressed in dots. The default values for these entries assume an A size page (8.5 by 11.0 inches) in portrait orientation with 0.5 inch margins. At 300 dpi this gives a printable area of 2250 by 3000 dots. The minimum and maximum values are identical in the default case. If a Page Size Table has been specified, the values for this entry are derived from it. Cost per Page Cost per printed page in local currency. For example, 0.50 for 50 cents per page. Time per Page The average and, optionally, maximum time to print a page, in seconds. If the maximum time is not provided, it is assumed to be the same as the average time. Number of Colors The minimum and, optionally, maximum number of colors that are available on the printer. If the maximum number of colors is not provided, it is assumed to be the same as the minimum. A monochrome printer or printer ribbon would provide one color. A CMY printer or ribbon would provide three colors. Note that this field should contain only the number of colors available on the printer. The colorspace, depth and data format are provided in the Number of Colors entry in the status file. Quality Modes A list of output quality modes available on the printer. For example, draft, and letter. Default QM The index into the Quality Modes list indicating the default quality mode. This index is based at one rather than zero. Thus, the first quality mode in the list is at position 1, the second at 2, and so on. If there are no quality modes specified, this entry should either be left empty or set to 0. Manual Capable Keyword yes indicating that the printer is capable of being manually fed or no indicating that it is not. Note that for a printer to be considered manual capable its driver must support manual feeding (the -m driver option in the Impressario Filter/Driver Specification) in addition to the printer hardware allowing manual feed. Black Substitute Keyword yes indicating that the printer should substitute true black for composite black or no indicating that it should not. Media Standard Keyword indicating the paper measurement standard. Keywords are American or Metric. Available Fonts This entry contains a list of font names representing the fonts available on the printer. For printers with built-in PostScript interpreters this list should include only those fonts built into the printer (typically a set of 35 standard fonts). For raster printers the PostScript interpretation is performed on the printer host machine. Thus, the fonts listed for these printers should correspond to the names of the font outline files installed on the printer host. There are two methods for specifying the font names. The names can be listed individually or a full path to the directory where the outline fonts are stored can be specified. The two methods can be mixed. When a directory is specified, the names of the files in that directory are assumed to be the names of the fonts. To exclude filenames from the directory, specify the name of the file to be excluded with a leading '!'. The filenames to exclude must appear on the same line as the directory containing the filename to be excluded. The following is a valid Available Fonts list: NewYearRoman | /usr/fonts | !fonts.dir This entry indicates that the fonts available on the printer are NewYearRoman and all filenames in the directory /usr/fonts with the exception of fonts.dir. Note that font names must not contain any whitespace. To logically AND a list of font names, specify the name of the file or directory (to AND with) using a leading '&'. This is useful when supporting a printer with built-in PostScript. In this case, you would list the fonts supported by the printer and then logically AND that list against the fonts installed on the system. The result is a list of valid fonts that can be used with utilities like text2ps(1) which are also supported by the printer (text2ps(1) requires the font metric be installed on the system so it can generate page and line breaks correctly). The following is a valid Available Fonts list: NewYearRoman | &/usr/lib/DPS/AFM This simple example indicates that the font available on the printer is NewYearRoman and it should be used if the corresponding font is found in /usr/lib/DPS/AFM. Input Source A list of printer input sources. The primary use of this entry is to list the image source devices that have been characterized for printer color correction. A common input device would be the monitor. An Example entry is Sony 16" Monitor. Default IS The index into the Input Source list indicating the default input source. This index is based at one rather than zero. Thus, the first source in the list is at position 1, the second at 2, and so on. If there are no input sources specified, this entry should either be left empty or set to 0. When used for printer color correction, this entry can also be used to specify the default device's gamma correction value. The gamma value is specified after the default input source index as in the following example: 1, gamma = 1.000 Color Adjustment A list of color adjustment methods available for the printer. The color adjustment methods perform color correction between the current input source and the printer. An example entry is: None | Fix Blue | Gamma Correct Default CA The index into the Color Adjustment list indicating the default adjustment method. This index is based at one rather than zero. Thus, the first method in the list is at position 1, the second at 2, and so on. If there are no adjustment methods specified, this entry should either be left empty or set to 0. Media Type A list of the output media types supported by the printer. Typical items would be Bond Paper and Transparency Film. Default MT The index into the Media Type list indicating the default media. This index is based at one rather than zero. Thus, the first media in the list is at position 1, the second at 2, and so on. If there are no media types listed, this entry should either be left empty or set to 0. Size Table Entry This entry describes a particular media size that is supported by the printer. Typically these is one Size Table Entry per supported media size (e.g. an entry for A size and B size). The media size entry has seven required fields and two optional fields. All fields are separated by whitespace. The first field contains the media size name keyword (e.g. A). The list of possible media sizes can be found in the file /usr/include/pod.h. The media size keyword is simply the media size name listed in pod.h with the PD_SIZE_ prefix removed. The size names listed in pod.h with the suffix _LAND indicate landscape orientation and should not not be used as a media size keyword. Media with landscape orientation is indicated by the width and height fields of the size table entry. The next two fields are the media imageable width and height expressed in dots. Typically the imageable dimensions are derived by subtracting the margins from the total media size and converting the result to dots. The next two fields are the overall media width and height expressed in inches. The last two required fields are the left and top margins expressed in inches. The first optional field specifies the printing raster direction. Refer to pod.h for the values that may be specified in this field. The second optional field is the media validation mask. This mask can be used to differentiate among media entries that have the same media name but differ in other respects (e.g. resolution). The field is a bit mask and so to fully differentiate among similar entries the values must be powers of two. Refer to the PDReadInfo(3) man page for more information on the use of this field. A default Size Table Entry is always add to the end of the table when it is read by libpod. This default entry is: A 2250 3000 8.500 11.000 0.500 0.500 0x00 0xFF STATUS FILE FORMAT This section describes the printer status file format. The status file is installed in /var/spool/lp/pod with the name <printer name>.status. The general format for config file entries is: <keyfield> <separator> [<infofield>] <endline> where <infofield> is specified by the table below. The Number of Colors <infofield> has the format <dataentry> defined as: <dataentry>: <int> [<keyword> <int> <keyword>] The Error, Warning and Information message <infofield> has the format <msgentry> defined as: <msgentry>: <hbyte> [<hbyte> [<hbyte>]] <separator> <string> All entries in the status file are optional. Entries that are not provided or that have no <infofield> will be assigned default values. However, since the status file is the only means to indicate printer status to the user, it is strongly suggested that a complete status file be provided by the developer and that the printer driver update the status file to reflect the printer's current status. Key Field <infofield> Default ______________________________________________________ Operational Status <keyword> Idle Media Size <keyword> [Land] A Media Type <keyword> Paper Number of Colors <dataentry> 1 k 1 chunky Printer Options <string> (empty string) Validation Mask <hbyte> 0 Error <msgentry> (no message) Warning <msgentry> (no message) Information <msgentry> (no message) Operational Status Keyword specifying the current operational status of the printer. The possible values are: Idle Busy Faulted Unavailable The status Faulted indicates that there is a problem with the printer or with communication to the printer. The Unavailable designation is similar to the Faulted state and is intended to provide an additional problem description state. Media Size Keyword indicating the currently loaded media size. The media size keywords are listed in the file pod.h. The keyword is the size name listed with the PD_SIZE_ prefix removed. The size names listed in pod.h with the suffix _LAND indicate landscape orientation and are specified in the entry by the keyword Land. Media Type This keyword indicates the currently loaded media type. The value is Paper, Transparency, Other or Unknown. Number of Colors This field specifies not only the number of output colors but the colorspace, depth and organization of the output data. There are one required and three optional fields. For proper operation of printing filters it is strongly recommended that the optional fields be specified. The first field is required and specifies the number of output colors that the printer can currently print. If only this field is present the following defaults will apply: # Colors Color Depth Org. _________________________________ 1 k 1 chunky 3 cmy 1 chunky 4 cmyk 1 chunky The optional (but recommended) three fields explicitly specify the output colorspace, depth and organization of the output data. The colorspace field is one of: k cmy cmyk w rgb ymc ymck kcmy The depth field specifies the number of bits per color component and may be one of 1, 4, 8. The data organization field is one of: chunky planar An example output specification is: 3 rgb 4 planar This specifies a three color RGB output with four bits per component (12 bits total) and a planar data organization. Refer to the libstiff(3) man page for additional information on raster data output formats. Printer Options This field can be used to describe currently installed optional equipment or configurations. This field is also used to indicate the current printer resolution for printers that allow multiple output resolutions. To indicate the current resolution the string: CurrentRes = <int> x <int> is specified. The first integer is the horizontal resolution in dots per inch and the second integer is the vertical resolution in the same units. The current resolution values are used by printing filters such as the PostScript interpreter psrip(1). Validation Mask The validation mask can be used to select among media size entries in the config file that have the same media name but differ in other respects (e.g. resolution). The field is a bit mask and so to fully differentiate among similar entries the values must be powers of two. The default value, 0, will select the first media entry whose name matches the specified media name. Refer to the PDReadStatus(3) man page for more information on the use of this field. Error, Warning, Information These three entries indicate messages written by the printer driver to provide information to the printer user regarding the state of the printer. The three hex bytes provide a message code. The available message codes are listed in pod.h (PD_ERROR_*). The low order three bytes of the codes listed in pod.h are the codes specified in this field. The high order byte of the code is implied by the first field (i.e. Information = 00, Warning == 01, Error = 02). The last field is a string providing the text for the message. There can be up to PD_MESSAGE_MAX (see pod.h) message entries in a status file. An example of a complete message entry is: Information | 01 00 00 | version: driver = 00.00 LOG FILE FORMAT The log file is not currently implemented. Developer's should supply an empty file in /var/spool/lp/pod with the name <printer name>.log. FILES /var/spool/lp/pod/<printer name>.config Configuration file /var/spool/lp/pod/<printer name>.status Status file /var/spool/lp/pod/<printer name>.log Log file SEE ALSO libpod(3), podd(1M), libstiff(3), psrip(1)