PRINTRC(5)

NAME
printrc - Printer resource database

SYNOPSIS
printrc

DESCRIPTION
This document describes the structure of the printrc files. The files /usr/local/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 escaping 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 continues without errors. Note that pattern is first tilde expanded, then globbed. Files beginning in . and ending in ~ are ignored, as they are probably editor backup files.

printer name block
    A printer named name is defined in block. Structure 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 whitespace.

driver_args block
    Arguments for the driver are contained in block, which consists of pairs of argument name and argument value separated by whitespace.

interface_opts block
    Options for the interface are contained in block, which consists of option names separated by whitespace.

interface_args block
    Arguments for the interface are contained in block, which consists of pairs of argument name and argument value separated by whitespace.

location description
    The block description is taken to be the descriptive location of the printer. This keyword should not affect functionality.

model description
    The block description is taken to be the descriptive 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 component is taken to be unavailable. Informative failure 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-separated list of program names required by this component. 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 environment variable INPUT. The filtered output should be written to the file named by environment variable 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. 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. 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-separated 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-separated 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 and \t. The help keyword does not affect 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 shebang, it is taken to be /bin/sh. The function of the script is to convert the file named by environment variable INPUT into a form suitable for printing (or into a form expected by the filter_exec script defined for the driver). The converted output should be written to the file named by environment 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 environment variables set by options for this component, 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 component is taken to be unavailable. Informative failure 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-separated list of program names required by this component. 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 shebang, it is taken to be /bin/sh. The function of the script is to send the file named by environment variable INPUT to the printer. If the script exits 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. 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 shebang, 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 immediately be executed. The exit code of the script is ignored. This script also has access to all environment variables set by options and arguments for this component. There is no default value for cancel_exec.

status_exec script
    The argument 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 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 status_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-separated 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-separated list of names of arguments required for this component. If all arguments are not available either through printrc specification or command-line specification, the component will be unavailable.

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 argument 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 provided 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 utilities 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 environment 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 the default.

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 variable var, which is given as an option keyword, will be string.

help text
    A short description of the choice should be provided 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 utilities that allow graphical selection of printer options.

STATUS MESSAGES
The convert_exec, filter_exec, filetype_exec, and send_exec scripts may also set the status of the printjob by writing to the file named by environment variable STATUS. The status will be set to the last nontrivial line in this file, not to exceed 1023 characters. Note that IO buffering may cause delays in status updates. The status file almost always overrides internal status messages.

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), pdqstat(1)