Appendix C. Printer Object Database (POD) File Formats
Prev |  | Next

## Appendix C. Printer Object Database (POD) File Formats

This appendix describes the file formats of the ASCII text files that compose the printer object database (POD).

The following major topics are discussed:

- “General Syntax”

- “Input Parsing Rules for libpod Files”

- “Printer Configuration File Format”

- “Printer Status File Format”

- “Printer Log File Format”

## Overview

The printer object database (POD) contains information on the current configuration, status, and job history of a single printer. Each printer that is physically installed on a system must maintain its own POD. To maintain network-transparent, mediated access to the POD files, all interaction between the printer driver and POD files must be through the `libpod` API. For additional information, see “The libpod Library” in Chapter 5 and the `libpod(3)` reference page.

The initial set of POD files created by the printer driver developer and installed on the host server system must include the following:

- `<printer name>.config`: a configuration file representing the printer's capabilities

- `<printer name>.stats`: a status file indicating a typical printing state

- `<printer name>.log`: an empty log file

The name of each POD file is formed from the printer name and the suffix .config, .status, or .log, respectively. Note that the printer name must be the same as the name of the printer model file. All POD files are copied from the template POD files and installed in the appropriate directory.

The information contained in each POD file is summarized below and explained in detail in subsequent sections.

### Printer Configuration File

The printer configuration file (`<printer name>.config`) contains detailed information on the printer's capabilities. The file is created by the printer driver developer to characterize the printer's capabilities. 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 it as a read-only file. The printer install tools may modify the file at printer installation time to enter site-specific data, such as printer location, or note the presence of optional equipment, such as a duplex option or an envelope feeder.

### Printer Status File

The printer status file (`<printer name>.status`) 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. The driver developer provides an initial copy of the status file, but it is the job of the printer driver to update the file. Printer filter programs normally treat this file as if it were a read-only file.

### Printer Log File

The printer log file (`<printer name>.log`) 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 if it were a read-only file.

## 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 for libpod Files

The following rules apply when a POD file is parsed by the `libpod` API:

- All `<null>` characters are ignored. Their use is discouraged to avoid errors caused by nonprinting characters appearing in the POD files.

- 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`.

- All occurrences of `<white>` sequences are reduced to a single `<sp>` character. Any `<white>` at the beginning or end of a field is removed.

- There are no quoted strings. Quotation marks are treated like any other characters and cannot be used to force additional `<white>` into a field.

- All fields are checked for correct syntax based on entry type. Failure to provide information in the correct format results in improper parsing.

- 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

- Entries containing no characters other than `<white>` before the first `<separator>` or `<endline>` are treated as null entries and discarded without error. These lines may be used as comments by placing a `<separator>` before any other information.

- Blank lines are ignored and may be inserted to improve readability.

- `<keyfield>` matching is done in a case-independent manner.

- Fields designed to be human-readable are not modified, except to remove `<null>` and excess `<white>`. Case and all `<plainchar>` sequences are preserved.

- A `<keyfield>` may require a long list of items (for example, Available Fonts). To improve readability and avoid the risk of input line buffer overflow (see the second bullet item above), a `<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.

- There is no required entry order. The `<keyfield>` entries may appear in any order within a POD file.

- Default values are assumed for certain fields if values are not specified. The values of these defaults should not be relied upon and may change in future releases.

## Printer Configuration File Format

This section describes the format of the printer configuration file. The configuration file is installed by the printer install tools with the name `<printer name>.config`.

### General Format

The format for an entry in the configuration file is

    <keyfield> <separator> [<infofield>] <endline>

where

`<keyfield>` |  | is one of the reserved fields described in the “Key Field” column of Table C-1.
`<separator>` |  | is the “separator” character defined in “Character Set”.
`<infofield>` |  | is one or more of the options specified in the “Info Field Type” column of Table C-1.
`<endline>` |  | is one of the “endline” characters defined in “Character Set”.

### Config File Options

All entries in the config file are optional. Entries that are not provided or that have no `<infofield>` specified are assigned default values. However, since printer capabilities differ, it is strongly recommended that no entries be omitted. The defaults should not be relied on, as they may change in future releases. Table C-1 lists the config file options in alphabetical order. A detailed explanation of each option follows the table.

Table C-1. Config File Options

Key Field | Info Field Type | Default
--- | --- | ---
Active Status Path | <word> | See “Active Status Path”.
Available Fonts | <array> | (0 elements)
Black Substitute | <keyword> | No
Color Adjustment | <array> | (0 elements)
Cost per Page | <float> | 0.00
Default CA | <int> | 0
Default IS | <int> [,gamma=<float>] | 0, gamma=-1.0
Default MT | <int> | 0
Default QM | <int> | 0
Driver Path | <word> | See “Driver Path”.
Error Retry Wait | <int> | 10 seconds
Input Source | <array> | (0 elements)
Location Code | <keyword> | None
Manual Capable | <keyword> | No
Maximum Addr | <Maximum Addrint> <int> | See “Minimum Addr”.
Maximum Print Area | <float> <float> | See “Maximum Print Area”.
Media Standard | <keyword> | American
Media Type | <array> | (0 elements)
Media Wait | <int> | 300 seconds
Minimum Addr | <int> <int> | See “Minimum Print Area”.
Minimum Print Area | <float> <float> | See “Minimum Print Area”.
Number of Colors | <int> [<int>] | 1 1
Physical Location | <string> | Unknown
Port Path | <word> | /dev/null
Printer Class | <keyword> | Dumb
Printer Model | <string> | Unknown
Printer Options | <string> | (empty string)
Quality Modes | <array> | (0 elements)
Resolution | <int> <int> | 300 dpi 300 dpi
Size Table Entry | <sizeentry> | See “Size Table Entry”.
Status Update Wait | <int> | 300 seconds
Technology | <string> | Unknown
Time per Page | <int> [<int>] | 0 0

#### Active Status Path

Active Status Path is the 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)` reference page for additional information.

#### Available Fonts

The Available Fonts option 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). The default value is 0 elements.

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 path 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 names of the files to be excluded with a leading “!”. The filenames to be excluded 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/lib/DPS/outline/base | !fonts.dir

This entry indicates that the only font available on the printer is NewYearRoman, and all file names are in the directory `/usr/lib/DPS/outline/base` with the exception of `fonts.dir`. Note that font names must not contain any white space.

Starting with Impressario 2.0, a new logical AND operator, &, is available for font lists. It allows the list of fonts on the printer to be logically AND'ed with the list of fonts on the print server, generating a list of fonts that are common to both. The common list is needed for the `text2ps(1)` filter, which uses the font metric information from the print server fonts to determine where line and page breaks should be made. The AND operator is intended for use by printer drivers that send PostScript directly to the printer.

The entry below says that NewYearRoman is available on the printer, and if it is also available in `/usr/lib/DPS/outline/base`, it should be on the list of available fonts when a printer driver is installed:

    | NewYearRoman | &/usr/lib/DPS/outline/base

For another example, see the file

`/usr/lib/print/data/lexmarkoptra_model.config`

#### Black Substitute

The Black Substitute option is either yes, indicating that the printer should by default substitute true black for composite black, or no, indicating that it should not. The default value is no.

#### Color Adjustment

The Color Adjustment option is 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

The default value is 0 elements.

Starting with Impressario 2.0, International Color Consortium (ICC) color profiles and various filters, such as `cocostiff`, are used to perform color management. Color correction is applied as a filter before the driver is invoked (FTR rules have been added so `fileconvert` will invoke the correct filters based on the file type). The Color Adjustment entry in the POD file is currently not used. See Appendix G for more information on color management in Impressario.

#### Cost per Page

The Cost per Page option is the cost per printed page in local currency. For example, 0.50 for 50 cents per page. The default value is 0.00.

#### Default CA

The Default CA option is the index to 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. The default value is 0.

#### Default IS

Default IS is the index to 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.0

#### Default MT

Default MT is the index to 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. The default value is 0.

#### Default QM

Default QM is the index to 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. The default value is 0.

#### Driver Path

Driver Path is the full pathname of the installed printer driver. The default is the full pathname of the POD config file, with the suffix `.config` removed.

#### Error Retry Wait

Error Retry Wait refers to the number of seconds to wait after an error has occurred before attempting to resume printing. The default is 10 seconds.

#### Input Source

Input Source is 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 is the monitor. An example entry is Sony 16” Monitor.

#### Location Code

The Location Code option is used to supply a site-specific keyword that identifies the printer's physical location. For example, 3U-924. There is no default value. This code should be machine-readable and -sortable for use by a location-querying browser.

#### Manual Capable

Manual Capable is either yes, indicating that the printer is capable of being manually fed, or no, indicating that it is not. The default value is no. This value should be set to yes only if the printer supports the `-m` option (see “The Filter/Driver Specification and psrip” in Chapter 2).

#### Maximum Addr

Maximum Addr is the maximum printable area dimensions expressed in dots. The default values for this entry 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. Also see “Minimum Addr.”

#### Maximum Print Area

Maximum Print Area is the maximum printable area dimensions expressed in inches. The default values for this entry 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. 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. Also see “Minimum Print Area.”

#### Media Standard

Media Standard indicates the paper measurement standard. Keywords are American and Metric. The default value is American.

#### Media Type

Media Type is an array that contains the output media types supported by the printer. Typical items are Bond Paper and Transparency Film. The default array has 0 elements.

#### Media Wait

Media Wait is the number of seconds to wait for manual feed or print media changes before the default media source is used. The default is 300 seconds.

#### Minimum Addr

Minimum Addr is the minimum printable area dimensions expressed in dots. The default values for this entry assumes 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. Also see “Maximum Addr.”

#### Minimum Print Area

Minimum Print Area is the minimum printable area dimensions expressed in inches. The default values for this entry 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. 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. Also see “Maximum Print Area.”

#### Number of Colors

Number of Colors is the minimum or, 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 provides one color. A CMY printer or ribbon provides 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. The default value is 1.

#### Physical Location

Physical Location is the human-readable description of the printer's physical location. For example, Bldg. 3 Upper, Room 924. The default value is Unknown.

#### Port Path

Port Path is the 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. The default value is `/dev/null`.

#### Printer Class

The Printer Class entry is used to specify the class of printer being used. Available values are Dumb, Raster, ColorRaster, MonoPostScript, ColorPostScript, and Plotter. The following printer classes are obsolete and should not be used for new development: DumbColor, PostScript, and Color. The default value is Dumb.

#### Printer Model

The Printer Model entry is a keyword that is the manufacturer's description of the printer. For example, Tektronix Phaser II SX or Apple LaserWriter II NTX. The default value is Unknown.

#### Printer Options

Printer Options describe the standard installed printer optional equipment. For example, 8 megabytes RAM. The default is an empty string.

#### Quality Modes

Quality Modes is a list of output quality modes available on the printer. For example, draft and letter. The default value is 0 elements.

#### Resolution

Resolution is the horizontal or 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. The default values are both 300 dots per inch.

#### Size Table Entry

The Size Table Entry `<infofield>` has the format `<sizeentry>` defined as

    <sizeentry>: <keyword> <int> <int> <float> <float> <float>
                 <float> [<hbyte> [<hbyte>]]

Size Table Entry describes a particular media size that is supported by the printer. Typically, there is one Size Table Entry per supported media size (for example, an entry each for A size and B size), although it is acceptable to have multiple entries for a paper size if multiple resolutions or ribbons are supported. The media size entry has seven required fields and two optional fields. All fields are separated by white space.

The first required field contains the Media Size (for example, 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 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 be used as media size keywords. 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 (for example, 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)` reference page for more information on the use of this field.

A default Size Table Entry is always added 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 Update Wait

Status Update Wait is the number of seconds to wait between updates of the POD status file when no error has occurred. The default is 300 seconds.

#### Technology

The Technology option indicates the type of printing technology used in the printer. For example, ink jet, wax transfer, dye sublimation, and color laser. The default value is Unknown.

#### Time per Page

Time per Page is 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. The default values are both 0.

## Printer Status File Format

This section describes the format of the printer status file. The status file is installed by the printer install tools with the name `<printer name>.status`.

### General Format

The format for an entry in the printer status file is

    <keyfield> <separator> [<infofield>] <endline>

where

`<infofield>` |  | is the parameter is specified by Table C-2.
`<separator>` |  | is the separator defined in “Character Set”.
`<endline>` |  | is one of the endline characters defined in “Character Set”.

### Printer Status File Entries

All entries in the status file are optional. Entries that are not provided or that have no <infofield> are 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.

Table C-2 lists the printer status file entries.

Table C-2. Printer Status File Entries

Key Field | Info Field Type | 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

Operational Status is the keyword specifying the current operational status of the printer. The possible values are Idle, Busy, Faulted, and Unavailable.

The status Faulted indicates that there is a problem with the printer but not with communication to the printer. The Unavailable designation is similar to the Faulted state but indicates that communication could not be established with the printer. The default value is Idle.

#### Media Size

Media Size is the 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

Media Type is the keyword indicating the currently loaded media type. The value is Paper, Transparency, Other, or Unknown. The default is Paper.

#### Number of Colors

This field specifies not only the number of output colors but the colorspace, depth, and organization of the output data. There is one required field and three optional fields. For proper operation of printing filters, it is strongly recommended that the optional fields be specified.

The Number of Colors `<infofield>` has the format `<dataentry>` defined as

    <int> [<keyword> <int> <keyword>]

Arguments:

`<int>` |  | Required. Specifies the number of output colors the printer can currently print. If only this field is present, the following defaults apply
# of colors | colorspace | depth | organization
1 | k | 1 | chunky
3 | cmy | 1 | chunky
4 | cmyk | 1 | chunky
`<keyword>` |  | Optional. This field specifies the output colorspace and is either k, rgb, cmy, ymc, cmyk, ymck, w, or kcmy.
`<int>` |  | Optional. This field specifies the number of bits per color component and may be 1, 4, or 8.
`<keyword>` |  | Optional. This field specifies the data organization of the output data and is either chunky or 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)` reference page for additional information on raster data output formats.

#### Printer Options

This field is used to describe the currently available optional equipment or configurations. The 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` to calculate margins for printers whose resolutions can change, and it is very important that printer drivers update this information field to ensure proper rendering.

#### Validation Mask

This field can be used to differentiate among media entries that have the same media name but differ in other respects (for example, 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 `PDReadStatus(3)` reference page for more information on the use of this field.

#### Error, Warning, and Information Options

Each Error, Warning, and Information message `<infofield>` has the format `<msgentry>` defined as

    <hbyte> [<hbyte> [<hbyte>]] <separator> <string>

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` (see 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 (for example., 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

See the `PDMakeMessage()` routine for the best method of construction these messages. For the sake of internationalization, it is strongly recommended that you do not customize messages.

## Printer Log File Format

The log file is not currently implemented. You should supply an empty file in `/usr/spool/lp/pod` with the name `<printer name>.log,` and should not write to the log file.

Prev | Table of Contents | Next
Appendix B. Silicon Graphics Image File Format API |  | Appendix D. Transition Notes