--- name: "printrc" section: "5" platform: "linux" package: "pdq" version: "2.2.1-7" release: "Debian 3.0 (Woody)" platforms: ["linux"] url: "https://new.carta.tech/printrc" --- # printrc(5) Printer resource database ## 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 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 \ ## SEE ALSO [pdq(1)](/pdq/1.md), [xpdq(1)](/xpdq/1.md), pdqstat(1)