LPFILTER(8) Maintenance Commands and 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)
