'\" te
.\" Copyright (c) 2000, Sun Microsystems, Inc.  All Rights Reserved
.\" Copyright 1989 AT&T
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH LPFILTER 1M "Apr 3, 1997"
.SH NAME
lpfilter \- administer filters used with the LP print service
.SH SYNOPSIS
.LP
.nf
\fB/usr/sbin/lpfilter\fR \fB-f\fR \fIfilter-name\fR
     {\fB-\fR | \fB-i\fR | \fB-l\fR | \fB-x\fR | \fB-F\fR \fIpathname\fR}
.fi

.SH DESCRIPTION
.sp
.LP
The \fBlpfilter\fR command is used to add, change, delete, or list a filter
used with the \fBLP\fR print service. These  filters convert the content of a
file to have a content type acceptable to a printer.
.SH OPTIONS
.sp
.LP
Arguments consist of the \fB-f\fR\fIfilter-name\fR option and exactly one of
the arguments appearing within braces (\fB{\fR\|\fB}\fR) in the SYNOPSIS.
.sp
.ne 2
.na
\fB\fB\(mi\fR\fR
.ad
.RS 18n
Adds or changes a filter as specified from standard input. The format of the
input is specified below. If \fB-f\fR \fBall\fR is specified with the
\fB\(mi\fR option, the specified change is made to all existing filters. This
is not useful.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR \fIfilter-name\fR\fR
.ad
.RS 18n
Specifies the  \fIfilter-name\fR of the filter to be added, changed, reset,
deleted, or listed. The  filter name \fBall\fR is a special filter name defined
below. The  \fB-f\fR option is required.
.RE

.sp
.ne 2
.na
\fB\fB-F\fR \fIpathname\fR\fR
.ad
.RS 18n
Adds or changes a filter as specified by the contents of the file
\fIpathname\fR. The format of the file's contents is specified below. If
\fB\fR\fB-f\fR\fB all\fR is specified with the \fB-F\fR option, the specified
change is made to all existing filters. This is not useful.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR\fR
.ad
.RS 18n
Resets a filter to its default settings. Using  \fB\fR\fB-f\fR\fB all\fR with
the  \fB-i\fR option restores  all filters for which predefined settings are
available to their original settings.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR\fR
.ad
.RS 18n
Lists a filter description. Using \fB-f\fR \fBall\fR with the \fB-l\fR option
produces a list of all filters.
.RE

.sp
.ne 2
.na
\fB\fB-x\fR\fR
.ad
.RS 18n
Deletes a filter. Using \fB-f\fR \fBall\fR with the \fB-x\fR option results in
all filters being deleted.
.RE

.SH USAGE
.SS "Adding or Changing a Filter"
.sp
.LP
The filter named in the \fB-f\fR option is added to the filter table. If the
filter already exists, its description is changed to reflect the new
information in the input.
.sp
.LP
When  \fB\(mi\fR is specified, standard input supplies the filter description.
When \fB-F\fR is specified, the file \fIpathname\fR supplies the filter
description. One of these two options must be specified to add or change a
filter.
.sp
.LP
When an existing filter is changed with the \fB-F\fR or \fB\(mi\fR 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.
.sp
.LP
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 \fBLP\fR
print service knows the following:
.RS +4
.TP
.ie t \(bu
.el o
The content type of the request (specified by  \fBlp\fR \fB-T\fR or determined
implicitly).
.RE
.RS +4
.TP
.ie t \(bu
.el o
The name of the printer (specified by  \fBlp\fR \fB-d\fR).
.RE
.RS +4
.TP
.ie t \(bu
.el o
The printer type (specified by \fBlpadmin\fR \fB-T\fR).
.sp
The printer type is intended to be a printer model, but some people specify it
with a content type even though \fBlpadmin\fR \fB-I\fR is intended for this
purpose.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The content types acceptable to the printer (specified by \fBlpadmin\fR
\fB-I\fR\fB)\fR.
.sp
The values specified by the \fBlpadmin\fR \fB-T\fR are treated as if they were
specified by the \fB-I\fR option as well.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The modes of printing asked for by the originator of the request (specified by
various options to \fBlp\fR).
.RE
.sp
.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 \fBlp\fR arguments that invoke
filters  (\fB-y\fR and \fB-P\fR).
.sp
.LP
The contents of the file (specified by the \fB-F\fR option) and the input
stream from standard input (specified by  \fB\(mi\fR) 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.
.sp
.in +2
.nf
\fBInput types: \fR\fIcontent-type-list\fR
\fBOutput types: \fR\fIcontent-type-list\fR
\fBPrinter types: \fR\fIprinter-type-list\fR
\fBPrinters: \fR\fIprinter-list\fR
\fBFilter type: \fR\fIfilter-type\fR
\fBCommand: \fR\fIshell-command\fR
\fBOptions: \fR\fItemplate-list\fR
.fi
.in -2
.sp

.sp
.ne 2
.na
\fB\fBInput\fR \fBtypes\fR\fR
.ad
.RS 17n
This gives the content types that can be accepted by the filter. The default is
\fBany\fR. The document content type must  be a member of this list for the
initial filter in the sequence.
.RE

.sp
.ne 2
.na
\fB\fBOutput\fR \fBtypes\fR\fR
.ad
.RS 17n
This gives the content types that the filter can  produce from any of the input
(content) types.  The default is \fBany\fR. The intersection of the output
types of this list and the content types acceptable to the printer (from
\fBlpadmin\fR \fB-I\fR and \fBlpadmin \fR\fB-T\fR) 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.
.RE

.sp
.ne 2
.na
\fB\fBPrinter\fR \fBtypes\fR\fR
.ad
.RS 17n
This gives the printer types for which this  printer can be used. The \fBLP\fR
print service will restrict the use of  the filter to these printer types (from
\fBlpadmin\fR \fB-T\fR). The default is \fBany\fR.
.RE

.sp
.ne 2
.na
\fB\fBPrinters\fR\fR
.ad
.RS 17n
This gives the names of the printers for which the filter can be used. The
\fBLP\fR print service will restrict the use of the filter to just the printers
named. The default is \fBany\fR.
.RE

.sp
.ne 2
.na
\fB\fBFilter\fR \fBtype\fR\fR
.ad
.RS 17n
This marks the filter as a \fBslow\fR filter or a \fBfast\fR 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 \fBslow\fR. 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.
.RE

.sp
.ne 2
.na
\fB\fBCommand\fR\fR
.ad
.RS 17n
This specifies which program to run to invoke the filter. The full program
pathname as well as fixed options must  be included in the \fIshell-command\fR;
additional options are constructed, based on the characteristics of each print
request and on the \fBOptions\fR 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.
.RE

.sp
.ne 2
.na
\fB\fBOptions\fR\fR
.ad
.RS 17n
This is a comma-separated list of templates used by  the  \fBLP\fR print
service to construct options to the filter from the  characteristics of each
print request listed in the table later. The \fB-y\fR and  \fB- P\fR arguments
to the \fBlp\fR command cause a filter sequence to be built even if there is no
need for a conversion of content types.
.sp
In general, each template is of the following form:
.sp
\fIkeyword pattern \fR\fB=\fR \fIreplacement\fR
.sp
The \fIkeyword\fR names the characteristic that the template attempts to map
into a filter-specific option; each valid \fIkeyword\fR is listed in the table
below.
.sp
A \fIpattern\fR is one of the following:  a literal pattern of one of the forms
listed in the table, a single asterisk (\fB*\fR), or a regular expression. If
\fIpattern\fR matches  the value of the characteristic, the template fits and
is used to generate a filter-specific option. The  \fIreplacement\fR is what
will be used as the option.
.sp
Regular expressions are the same as those found on the \fBregexp\fR(5) manual
page. This includes the \fB\e(\fR\&...\fB\e)\fR and \fB\e\fR\fIn\fR
constructions, which can be used to extract portions of the \fIpattern\fR for
copying into the \fIreplacement\fR, and the \fB&\fR, which can be used to copy
the entire \fIpattern\fR into the \fIreplacement\fR.
.sp
The \fIreplacement\fR can also contain a \fB*\fR; it too, is replaced with the
entire \fIpattern\fR, just like the \fB&\fR of \fBregexp\fR(5).
.RE

.sp
.LP
The keywords are:
.sp
.in +2
.nf
lp Option          Characteristic   \fIkeyword\fR         Possible \fIpatterns\fR

-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         \fIprinter-name\fR

-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          \fIinteger\fR
                  copies
.fi
.in -2
.sp

.SS "Resetting a Filter to Defaults"
.sp
.LP
If the filter named is one originally  delivered with the  \fBLP\fR print
service, the \fB-i\fR option restores the original filter description.
.SS "Deleting a Filter"
.sp
.LP
The  \fB-x\fR option is used to delete the filter  specified in filter-name
from the \fBLP\fR filter table.
.SS "Listing a Filter Description"
.sp
.LP
The  \fB-l\fR 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:
.sp
.in +2
.nf
\fBInput types: \fR\fIcontent-type-list\fR
\fBOutput types: \fR\fIcontent-type-list\fR
\fBPrinter types: \fR\fIprinter-type-list\fR
\fBPrinters: \fR\fIprinter-list\fR
\fBFilter type: \fR\fIfilter-type\fR
\fBCommand: \fR\fIshell-command\fR
\fBOptions: \fR\fItemplate-list\fR
.fi
.in -2
.sp

.sp
.LP
If the command fails, an error message is sent to standard error.
.SS "Large File Behavior"
.sp
.LP
See \fBlargefile\fR(5) for the description of the behavior of \fBlpfilter\fR
when encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
.SH EXAMPLES
.LP
\fBExample 1 \fRPrinting with the landscape option
.sp
.LP
For example, the template

.sp
.in +2
.nf
\fBMODES landscape = \fR\fB-l\fR
.fi
.in -2
.sp

.sp
.LP
shows that if a print request is submitted with the \fB-y\fR \fBlandscape\fR
option, the filter will be given the option \fB-l\fR.

.LP
\fBExample 2 \fRSelecting the printer type
.sp
.LP
As another example, the template

.sp
.in +2
.nf
\fBTERM * = \fR\fB-T\fR\fB *\fR
.fi
.in -2
.sp

.sp
.LP
shows that the filter will be given the option \fB-T\fR \fIprinter-type\fR for
whichever  \fIprinter-type\fR is associated with a print request using the
filter.

.LP
\fBExample 3 \fRUsing the keywords table
.sp
.LP
Consider the template

.sp
.in +2
.nf
\fBMODES prwidth\e=\e(.*\e) = \fR\fB-w\fR\fB\e1\fR
.fi
.in -2
.sp

.sp
.LP
Suppose a user gives the command

.sp
.in +2
.nf
\fBlp -y prwidth=10\fR
.fi
.in -2
.sp

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

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 12n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fInon-zero\fR\fR
.ad
.RS 12n
An error occurred.
.RE

.SH SEE ALSO
.sp
.LP
\fBlp\fR(1), \fBsh\fR(1), \fBlpadmin\fR(1M), \fBattributes\fR(5),
\fBlargefile\fR(5), \fBregexp\fR(5)
.sp
.LP
\fI\fR
.SH NOTES
.sp
.LP
If the \fBlp\fR 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.