NAME
printrc - Printer resource database
SYNOPSIS
printrc
DESCRIPTION
This document describes the structure of the printrc
files. The files /etc/pdq/printrc and ~/.printrc are
parsed, if they exist, and solely determine the print
resources available, although each printrc file may
include other rc files.
LEXICAL STRUCTURE
Each printrc file consists of a series of blocks separated
by whitespace. In this context, a block is defined to be
either a simple word constructed of [A-Z] [a-z] [0-9] _ .
/ : @ - or any characters enclosed in delimiters {} [] ()
'' "". Delimiters may be included in the block by escap-
ing them with \. Whitespace is defined to be spaces,
tabs, newlines, any of # ; , = and characters between #
and newline.
TOP-LEVEL KEYWORDS
Keywords defined in this section may be included anywhere
in the rc file. Some items (such as printers, drivers,
and interfaces) look for other sets of keywords within
their description block. Those cases are documented in
subsequent sections. Repeated occurrences of keywords
overwrite earlier definitions, except for uniquely named
printers, drivers, and interfaces.
include pattern
All files matching pattern are opened and parsed as
printrc files. If any matched file cannot be
opened, or if no files match pattern, parsing stops
with an error. Note that pattern is first tilde
expanded, then globbed.
try_include pattern
All files matching pattern are opened and parsed as
printrc files. If any matched file cannot be
opened, or if no files match pattern, parsing con-
tinues without errors. Note that pattern is first
tilde expanded, then globbed.
printer name block
A printer named name is defined in block. Struc-
ture of block is described later in this file.
driver name block
A driver named name is defined in block. Structure
of block is described later in this file.
interface name block
An interface named is defined in block. Structure
of block is described later in this file.
default_printer printer
The printer named printer will be used as the
default printer. There is no default.
job_dir directory
The job work directory will be set to directory.
Note that directory is tilde-expanded. The default
is ~/.printjobs.
interface_command_path path
The environment variables PATH will be set to path
for all scripts defined in the interfaces. The
default is bin:/usr/bin:/usr/local/bin.
driver_command_path path
The environment variables PATH will be set to path
for all scripts defined in the drivers. The
default is bin:/usr/bin:/usr/local/bin.
max_send_tries i
The interface script send_exec will be executed at
most i times before the job aborts. The default is
30.
delay_between_tries i
If the interface script send_exec fails, i seconds
should pass before re-executing the script. The
default is 10.
job_history_duration i
Any information in the job directory ( job_dir )
will not be deleted until it is at least i seconds
old. The default is 259200 (3 days).
PRINTER KEYWORDS
driver name
The block name is taken to be the name of the
driver for this printer. The driver must be
defined elsewhere in the printrc files.
interface name
The block name is taken to be the name of the
interface for this printer. The interface must be
defined elsewhere in the printrc files.
driver_opts block
Options for the driver are contained in block,
which consists of option names separated by whites-
pace.
driver_args block
Arguments for the driver are contained in block,
which consists of pairs of argument name and argu-
ment value separated by whitespace.
interface_opts block
Options for the interface are contained in block,
which consists of option names separated by whites-
pace.
interface_args block
Arguments for the interface are contained in block,
which consists of pairs of argument name and argu-
ment value separated by whitespace.
location description
The block description is taken to be the descrip-
tive location of the printer. This keyword should
not affect functionality.
model description
The block description is taken to be the descrip-
tive model name of the printer. This keyword
should not affect functionality.
delete This printer and all prior declarations of the same
name are ignored. This keyword is provided so that
ordinary users may remove entries for printers
defined in global resource files.
DRIVER KEYWORDS
filetype_exec script
The argument script is taken to be a shell script.
If the interpreter command is not specified with a
shebang, it is taken to be /bin/sh. The function
of the script is to determine the type of the file
named in the environment variable INPUT. A
description of the filetype should be printed to
stdout, and should be less than 1024 bytes. Any
messages printed to sterr will be logged. If the
exit code is not zero the print job will abort.
The default is file.
verify_exec script
The argument script is taken to be a shell script.
If the interpreter command is not specified with a
shebang, it is taken to be /bin/sh. The function
of the script is to determine whether or not the
system has capabilities required by this component.
If the script exits with nonzero status, the compo-
nent is taken to be unavailable. Informative fail-
ure messages should be sent to either stdout or
stderr. The default is not to execute anything.
requires files
The argument files is taken to be a whitespace-sep-
arated list of program names required by this com-
ponent. Each item in the list must be found in the
relevant path, and have executable permissions.
Otherwise the component is taken to be unavailable.
filter_exec script
The argument script is taken to be a shell script.
If the interpreter command is not specified with a
shebang, it is taken to be /bin/sh. The function
of the script is to filter the file named by envi-
ronment variable INPUT. The filtered output should
be written to the file named by environment vari-
able OUTPUT. Note that other scripts are used to
convert into an appropriate language. This script
should only be used to finalize the document before
sending it to the printer. If the script exits
with nonzero status, the job is aborted. Informa-
tive failure messages should be sent to either std-
out or stderr. This script also has access to all
environment variables set by options and arguments
for this component. The default is ln -s $OUTPUT
$INPUT.
language_driver block
A language-driver named name is defined in block.
Structure of block is described later in this file.
option block
An option for this component is defined in block.
Structure of block is described later in this file.
default_options list
The argument list is taken to be a whitespace-sepa-
rated list of default options for this component.
argument block
An argument for this component is defined in block.
Structure of block is described later in this file.
required_args list
The argument list is taken to be a whitespace-sepa-
rated list of names of arguments required for this
component. If required arguments are not specified
in a printer definition or passed through command-
line options, the component will be unavailable.
help text
The argument text should describe the driver and
list printers that are known to work. Newlines,
tabs, and spaces all get compressed to a single
space. Tabs and newlines may be added by using \n
functionality.
LANGUAGE-DRIVER KEYWORDS
convert_exec script
The argument is taken to be a shell script. If the
interpreter command is not specified with a she-
bang, it is taken to be /bin/sh. The function of
the script is to convert the file named by environ-
ment variable INPUT into a form suitable for print-
ing (or into a form expected by the filter_exec
script defined for the driver). The converted out-
put should be written to the file named by environ-
ment variable OUTPUT. If the script exits with
nonzero status, the job is aborted. Informative
failure messages should be sent to either stdout or
stderr. This script also has access to all envi-
ronment variables set by options for this compo-
nent, as well as those set by options and arguments
for the driver in which it is defined. The default
is ln -s $OUTPUT $INPUT .
filetype_regx pattern
If pattern matches any part of the filetype, as
returned by the filetype_exec script defined in the
driver, then this language driver will be used to
convert the print job. The language drivers are
tried in the sequence they are defined, and the
first match selects a language driver.
INTERFACE KEYWORDS
verify_exec script
The argument script is taken to be a shell script.
If the interpreter command is not specified with a
shebang, it is taken to be /bin/sh. The function
of the script is to determine whether or not the
system has capabilities required by this component.
If the script exits with nonzero status, the compo-
nent is taken to be unavailable. Informative fail-
ure messages should be sent to either stdout or
stderr. The default is not to execute anything.
requires files
The argument files is taken to be a whitespace-sep-
arated list of program names required by this com-
ponent. Each item in the list must be found in the
relevant path, and have executable permissions.
Otherwise the component is taken to be unavailable.
send_exec script
The argument is taken to be a shell script. If the
interpreter command is not specified with a she-
bang, it is taken to be /bin/sh. The function of
the script is to send the file named by environment
with nonzero status, the script will be re-executed
at intervals of delay_between_tries seconds, up to
max_send_tries times. Informative failure messages
should be sent to either stdout or stderr. This
script also has access to all environment variables
set by options and arguments for this component.
This script may also set the status of the printjob
by writing to the pipe named by environment vari-
able STATUS. The pipe may be closed and re-opened
repeatedly, although the pipe does not need to be
closed for the update to occur. Note that some
scripting languages (such as perl) are fully
buffered by default. There is no default value for
send_exec. Specification of this script is
required.
cancel_exec script
The argument is taken to be a shell script. If the
interpreter command is not specified with a she-
bang, it is taken to be /bin/sh. The function of
the script is to cancel a printing job. If the
send_exec script is still executing, it will be
sent a SIG_TERM signal and cancel_exec will immedi-
ately be executed. The exit code of the script is
ignored. This script also has access to all envi-
ronment variables set by options and arguments for
this component. There is no default value for can-
cel_exec.
status_exec script
The argument is taken to be a shell script. If the
interpreter command is not specified with a she-
bang, it is taken to be /bin/sh. The function of
the script is to print the status of the printer.
This script also has access to all environment
variables set by options and arguments for this
component. There is no default value for sta-
tus_exec.
option block
An option for this component is defined in block.
Structure of block is described later in this file.
default_options list
The argument list is taken to be a whitespace-sepa-
rated list of default options for this component.
argument block
An argument for this component is defined in block.
Structure of block is described later in this file.
required_args list
The argument list is taken to be a whitespace-sepa-
component. If all arguments are not available
either through printrc specification or command-
line specification, the component will be unavail-
able.
help text
The argument text should describe the interface.
Newlines, tabs, and spaces all get compressed to a
single space. Tabs and newlines may be added by
using \n and \t. The help keyword does not affect
functionality.
ARGUMENT KEYWORDS
var name
The environment variable controlled by this argu-
ment is name.
desc text
A very short description of the argument should be
provided in text.
def_value string
If this argument is not specified, the default
value will be string.
help text
A short description of the argument should be pro-
vided in text. Newlines, tabs, and spaces all get
compressed to a single space. Tabs and newlines
may be added by using \n and \t. The contents of
text will be displayed in popup tooltips of utili-
ties that allow graphical selection of printer
arguments.
OPTION KEYWORDS
var name
The environment variable controlled by this option
is name.
choice name block
A choice named name is described in block. The
choices are used to control the values of environ-
ment variable specified by var, and name is used to
select the option from the command line.
desc text
A very short description of the option should be
provided in text.
default_choice name
If no choice for this option is specified, the
choice name will be used. If default_choice is not
specified, the first choice listed is taken to be
CHOICE KEYWORDS
desc text
A very short description of the option should be
provided in text.
value string
If this choice is selected, the environment vari-
able var, which is given as an option keyword, will
be string.
help text
A short description of the choice should be pro-
vided in text. Newlines, tabs, and spaces all get
compressed to a single space. Tabs and newlines
may be added by using \n and \t. The contents of
text will be displayed in popup tooltips of utili-
ties that allow graphical selection of printer
options.
BUGS
Some interpreters (such as perl) have different locations
on different systems. There should be a means of defining
interpreter locations so that the shebang line of the exec
scripts can be fixed before execution.
AUTHOR
Jacob A. Langford <langford@uiuc.edu>
SEE ALSO
pdq(1), xpdq(1)
Man(1) output converted with
man2html