The filter named in the -f option is added to the filter table. If the filter already exists, its description is changed to reflect the new information in the input.

When - is specified, standard input supplies the filter description. When -F is specified, the file pathname supplies the filter description. One of these two options must be specified to add or change a filter.

When an existing filter is changed with the -F or - option, lines in the filter description that are not specified in the new information are not changed. When a new filter is added with this command, unspecified lines receive default values. See below.

Filters are used to convert the content of a request from its initial type into a type acceptable to a printer. For a given print request, the LP print service knows the following:

• The content type of the request (specified by lp -T or determined implicitly).
• The name of the printer (specified by lp -d).
• The printer type (specified by lpadmin -T).

  The printer type is intended to be a printer model, but some people specify it with a content type even though lpadmin -I is intended for this purpose.

• The content types acceptable to the printer (specified by lpadmin -I).

  The values specified by the lpadmin -T are treated as if they were specified by the -I option as well.

• The modes of printing asked for by the originator of the request (specified by various options to lp).

The system uses the above information to construct a list of one or more filters that converts the document's content type into a content type acceptable to the printer and consumes all lp arguments that invoke filters (-y and -P).

The contents of the file (specified by the -F option) and the input stream from standard input (specified by -) must consist of a series of lines, such that each line conforms to the syntax specified by one of the seven lines below. All lists are comma or space separated. Each item contains a description.

Input types: content-type-list Output types: content-type-list Printer types: printer-type-list Printers: printer-list Filter type: filter-type Command: shell-command Options: template-list

Input types

This gives the content types that can be accepted by the filter. The default is any. The document content type must be a member of this list for the initial filter in the sequence.

Output types

This gives the content types that the filter can produce from any of the input (content) types. The default is any. The intersection of the output types of this list and the content types acceptable to the printer (from lpadmin -I and lpadmin -T) must be non-null for the last filter in the sequence. For adjacent filters in the sequence, the intersection of output types of one and the input types of the next must be non-null.

Printer types

This gives the printer types for which this printer can be used. The LP print service will restrict the use of the filter to these printer types (from lpadmin -T). The default is any.

Printers

This gives the names of the printers for which the filter can be used. The LP print service will restrict the use of the filter to just the printers named. The default is any.

Filter type

This marks the filter as a slow filter or a fast filter. Slow filters are generally those that take a long time to convert their input (that is, minutes or hours). They are run before the job is scheduled for a printer, to keep the printers from being tied up while the filter is running. If a listed printer is on a remote system, the filter type for it must have the value slow. That is, if a client defines a filter, it must be a slow filter. Fast filters are generally those that convert their input quickly (that is, faster than the printer can process the data), or those that must be connected to the printer when run. Fast filters will be given to the interface program to run while connected to the physical printer.

Command

This specifies which program to run to invoke the filter. The full program pathname as well as fixed options must be included in the shell-command; additional options are constructed, based on the characteristics of each print request and on the Options field. A command must be given for each filter. The command must accept a data stream as standard input and produce the converted data stream on its standard output. This allows filter pipelines to be constructed to convert data not handled by a single filter.

Options

This is a comma-separated list of templates used by the LP print service to construct options to the filter from the characteristics of each print request listed in the table later. The -y and - P arguments to the lp command cause a filter sequence to be built even if there is no need for a conversion of content types.

In general, each template is of the following form:

keyword pattern = replacement

The keyword names the characteristic that the template attempts to map into a filter-specific option; each valid keyword is listed in the table below.

A pattern is one of the following: a literal pattern of one of the forms listed in the table, a single asterisk (*), or a regular expression. If pattern matches the value of the characteristic, the template fits and is used to generate a filter-specific option. The replacement is what will be used as the option.

Regular expressions are the same as those found on the regexp(5) manual page. This includes the \(...\) and \n constructions, which can be used to extract portions of the pattern for copying into the replacement, and the &, which can be used to copy the entire pattern into the replacement.

The replacement can also contain a *; it too, is replaced with the entire pattern, just like the & of regexp(5).

The keywords are:

lp Option Characteristic keyword Possible patterns -T Content type INPUT content-type (input) Not applicable Content type OUTPUT content-type (output) not applicable Printer type TERM printer-type -d Printer name PRINTER printer-name -f, -o cpi= Character pitch CPI integer -f, -o lpi= Line pitch LPI integer -f, -o length= Page length LENGTH integer -f, -o width= Page width WIDTH integer -P Pages to print PAGES page-list -S Character set CHARSET character-set-name Print wheel CHARSET print-wheel-name -f Form name FORM form-name -y Modes MODES mode -n Number of COPIES integer copies

If the filter named is one originally delivered with the LP print service, the -i option restores the original filter description.

The -x option is used to delete the filter specified in filter-name from the LP filter table.

The -l option is used to list the description of the filter named in filter-name. If the command is successful, the following message is sent to standard output:

Input types: content-type-list Output types: content-type-list Printer types: printer-type-list Printers: printer-list Filter type: filter-type Command: shell-command Options: template-list

If the command fails, an error message is sent to standard error.

See largefile(5) for the description of the behavior of lpfilter when encountering files greater than or equal to 2 Gbyte ( 2³¹ bytes).

For example, the template

MODES landscape = -l

shows that if a print request is submitted with the -y landscape option, the filter will be given the option -l.

As another example, the template

TERM * = -T *

shows that the filter will be given the option -T printer-type for whichever printer-type is associated with a print request using the filter.

Consider the template

MODES prwidth\=\(.*\) = -w\1

Suppose a user gives the command

lp -y prwidth=10

From the table above, the LP print service determines that the -y option is handled by a MODES template. The MODES template here works because the pattern prwidth=) matches the prwidth=10 given by the user. The replacement -w1 causes the LP print service to generate the filter option -w10. If necessary, the LP print service will construct a filter pipeline by concatenating several filters to handle the user's file and all the print options. See sh(1) for a description of a pipeline. If the print service constructs a filter pipeline, the INPUT and OUTPUT values used for each filter in the pipeline are the types of input and output for that filter, not for the entire pipeline.