LPRng-HOWTO: 15 Oct 2001 (For LPRng-3.7.9)
Prev | Chapter 16. Filters | Next

# 16.8. Filter Command Line Options and Environment Variables

Options used:

- `bk_filter_options=`Backwards Compatible Filter options

- `bk_of_filter_options=`Backwards Compatible OF Filter options

- `bkf` FLAG Backwards Compatible Filters

- `filter_ld_path=`Filter LD_LIBRARY_PATH environment

- `filter_options=`Filter options

- `filter_path=`Filter PATH environment

- `of_filter_options=`OF Filter options

- `pass_env=`Environment variables to copy to Filter environment

- `pl=`line count for page

- `pw=`column count for page

- `px=`pixel width for page

- `py=`pixel length for page

A filter (or program) specification in the LPRng printcap database has the form:

        :option=| [flags] /path [argument | "argument" | 'argument' ]*
        :option=[flags]   /path [argument | "argument" | 'argument' ]*

The first case is used where the option value can be a string or filter, and the second where a program is always expected. The following procedure is used to run a filter program. Arguments in single or double quotes are passed as a single value, as for a shell.

The sequence of operations to run a filter is as follows:

1. The program must be specified with an absolute path name.

2. By default, the program is run as the user if invoked from a client program such as lpr, lpc, etc. If invoked from lpd, it is run as the user ID specified by the `:user` (default `daemon`) configuration entry.

3. The `filter_path` (default `/bin:/usr/bin:/usr/local/bin`, and `filter_ld_path` (default `/lib:/usr/lib:/usr/local/lib`, configuration options specifies the value of the `PATH` and `LD_LIBRARY_PATH` environment variables.

4. The `filter_path` (default `/bin:/usr/bin:/usr/local/bin`, and `filter_ld_path` (default `/lib:/usr/lib:/usr/local/lib`, configuration option specifies the value of the `PATH` and `LD_LIBRARY_PATH` environment variables. The other enviroment variables are described in LPRng ftp mirror sites Filter Environment Variables

5. ROOT Flag. If the ROOT flag is specified the filter is executed with Userid and Effective Userid ROOT (User ID 0). By default it is executed with the `user` and `group` configuration option user and group ids. Running a filter as ROOT is extremely dangerous, and should only be used for programs that require root permissions to open files or make network connections from privileged ports.

6. `$-` or `-$` Flag. This flag suppresses appending options to the filter command line. If the $- or `-$` flag is not present, the `:filter_options` or `:of_filter_options` for the `:of` filter values are appended to the filter command line. If the `:bkf` (Berkeley lpd filter compatible flag) is `TRUE` then the `:bk_filter_options` and `:bk_of_filter_options` values are used instead of the `:filter_options` and `:of_filter_options` values.

   Table 16-1. Print Filter Command Line Options

   Option | DefaultValue
   --- | ---
   Option | DefaultValue
   `filter_options` | $C $F $H $J $L $P $Q $R $Z $a $c $d $e $f $h $i $j $k $l $n $p$r $s $w $x $y $-a
   `of_filter_options` | (same as `filter_options`)
   `bk_filter_options` | $P $w $l $x $y $F $c $L $i $J $C $0n $0h $-a
   `bk_of_filter_options` | $w $l $x $y

7. By default, for programs that are not being invoked as print job file filters, the `filter_options` arguments are added. For print job filters, if the `:bkf` flag is set, then the `bk_filter_options` and `bk_of_filter_options` entries are used. The default `bk` filter options are the same as originally used with the BSD lpr filters. For the `:of` filter, either the `of_filter_options` or `bk_of_filter_options` arguments will be added.

8. The program arguments will then be scanned and interpreted. Arguments of the form `$``letter` will be translated into values from the print job control file and/or printcap entry. The letters have the following meaning:

   Table 16-2. Filter Command Line Options and Values

   Option | Purpose or Value
   --- | ---
   `a` | printcap `af` (accounting file name)
   `b` | job size (in K bytes)
   `c` | binary file (`l` format for print file)
   `d` | printcap `cd` or `sd` entry
   `e` | print job data file name (currently being processed)
   `f` | print job original name when spooled for printing (N info from control file)
   `h` | print job originating host (H info from control file)
   `i` | indent request (I info from control file)
   `j` | job number in spool queue
   `k` | print job control file name
   `l` | printcap `pl` (page length)
   `m` | printcap `co`
   `n` | user name (L info from control file)
   `p` | remote printer (when processing for bounce queue)
   `r` | remote host (when processing for bounce queue)
   `s` | printcap `sf` (status file)
   `t` | time in common UNIX format
   `w` | printcap `pw` (page width)
   `x` | printcap `px` (page x dimension)
   `y` | printcap `py` (page y dimension)
   `F` | print file format
   `P` | printer name
   `S` | printcap `cm` (comment field)
   Capital letter | Corresponding line from control file
   {key} | printcap value for `key`

9. If there is no value for the specified argument, then the argument is removed from the list. If there is a value, the actual form of the substitution is controlled by additional flags as follows.

   Table 16-3. Filter Command Line Option Format

   Form | TranslatedValue
   --- | ---
   `$x` | `'-x` `value``'`
   `$-x` | `'``value``'`
   `$0x` | `-x '``value``'`
   `$'x` | `-x` `value`

   Each entry in quotes is treated as a single value, as in /bin/sh. The `$'x` does not quote the value. Combinations of the various flags are allowed. For example, `$-x` would simply substitute the value for `x`, and then pass the whitespace separated components as individual arguments. This last form is useful for adding in additional flags on the command line.

10. The command line is parsed, metacharacters are ruthlessly stripped from all arguments and pathnames and replaced by `_` (underscores), and an argument list suitable for the `execve` system call is formed.

11. A sanitized environment is set up for the program execution, with the following environment variables.

    Table 16-4. Filter Environment Variables

    Variable Name | Meaning
    --- | ---
    `CONTROL` | control file name
    `DATAFILES` | list of data file names
    `HOME` | Home directory (client only)
    `IFS` | `" \t"`
    `LD_LIBRARY_PATH` | `:filter_ld_path` configuration information
    `LOGDIR` | Home directory (client only)
    `LOGNAME` | `L` control file line
    `PATH` | `filter_path` configuration information
    `PRINTCAP_ENTRY` | printcap information
    `SHELL` | `:sh` configuration information (default `/bin/sh`)
    `SPOOL_DIR` | `:sd` printcap information
    `TZ` | Time zone
    `USER` | User name (client only)

12. If the filter is to be run by a client program such as lpr, then the environment variables specified by the `pass_env` configuration or printcap option will be extracted from the environment, have any metacharacters removed, and then placed in the environment variable list. Commonly, the PGPPASS, PGPPASSFD, and PGPPATH are specified.

13. The program is started, with STDIN, STDOUT, and STDERR attached to the appropriate files or file descriptors. If none is specified, then they are attached to `/dev/null`.

Prev | Home | Next
Chaining Filters | Up | LPRng Supported Filters