LPFILTER(8) Maintenance Procedures LPFILTER(8)

NAME

lpfilter - administer filters used with the LP print service

SYNOPSIS

/usr/sbin/lpfilter -f filter-name
{- | -i | -l | -x | -F pathname}

DESCRIPTION

The lpfilter command is used to add, change, delete, or list a filter
used with the LP print service. These filters convert the content of a
file to have a content type acceptable to a printer.

OPTIONS

Arguments consist of the -ffilter-name option and exactly one of the
arguments appearing within braces ({}) in the SYNOPSIS.

-
Adds or changes a filter as specified from standard
input. The format of the input is specified below. If
-f all is specified with the - option, the specified
change is made to all existing filters. This is not
useful.


-f filter-name
Specifies the filter-name of the filter to be added,
changed, reset, deleted, or listed. The filter name
all is a special filter name defined below. The -f
option is required.


-F pathname
Adds or changes a filter as specified by the contents
of the file pathname. The format of the file's contents
is specified below. If -f all is specified with the -F
option, the specified change is made to all existing
filters. This is not useful.


-i
Resets a filter to its default settings. Using -f all
with the -i option restores all filters for which
predefined settings are available to their original
settings.


-l
Lists a filter description. Using -f all with the -l
option produces a list of all filters.


-x
Deletes a filter. Using -f all with the -x option
results in all filters being deleted.

USAGE

Adding or Changing a Filter

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:

o The content type of the request (specified by lp -T or
determined implicitly).

o The name of the printer (specified by lp -d).

o 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.

o 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.

o 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(7) 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(7).


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

Resetting a Filter to Defaults

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

Deleting a Filter

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

Listing a Filter Description

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.

Large File Behavior

See largefile(7) for the description of the behavior of lpfilter when
encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).

EXAMPLES

Example 1: Printing with the landscape option

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.

Example 2: Selecting the printer type

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.

Example 3: Using the keywords table

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.

EXIT STATUS

The following exit values are returned:

0
Successful completion.


non-zero
An error occurred.

SEE ALSO

lp(1), sh(1), attributes(7), largefile(7), regexp(7), lpadmin(8)

NOTES

If the lp command specifies more than one document, the filtering chain
is determined by the first document. Other documents may have a different
format, but they will print correctly only if the filter chain is able to
handle their format.


April 3, 1997 LPFILTER(8)