POD(4) Impressario POD(4)NAMEpod - 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
Page 1
POD(4) Impressario POD(4)
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.
Page 2
POD(4) Impressario POD(4)
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:
Page 3
POD(4) Impressario POD(4)
<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
Page 4
POD(4) Impressario POD(4)
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.
Page 5
POD(4) Impressario POD(4)
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.
Page 6
POD(4) Impressario POD(4)
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.
Page 7
POD(4) Impressario POD(4)
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
Page 8
POD(4) Impressario POD(4)
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
Page 9
POD(4) Impressario POD(4)
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:
Page 10
POD(4) Impressario POD(4)
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
Page 11
POD(4) Impressario POD(4)
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
Page 12
POD(4) Impressario POD(4)
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 ALSOlibpod(3), podd(1M), libstiff(3), psrip(1)
Page 13
