lpfilter(ADM)

Syntax

/usr/lib/lpfilter -f filtername -

/usr/lib/lpfilter -f filtername -i

/usr/lib/lpfilter -f filtername -x

/usr/lib/lpfilter -f filtername -l

Description

-F pathname

(or - for standard input) to add or change a filter. When all is specified with the -F or - option, the requested change is made to all filters.

-i

to reset an original LP print service filter to its factory setting. Using all with the -i option has the effect of restoring to their original settings all filters for which predefined settings were initially available.

-x

to delete a filter. Using all with the -x option results in all filters being deleted.

-l

to list a filter description. Using the all argument with the -l option produces a list of all filters.

Filters can be set up to do the following:

• Convert a user's file into a data stream that prints properly on a given printer.

• Handle the various modes of printing that people may request with the -y option to the lp command, such as two-sided printing, landscape printing, draft or letter-quality printing, and so on.

• Detect printer faults and inform the print service, which in turn can alert the system administrator.

Adding or changing a filter

The filter named in the -f option and described in the input is added to the filter table. If the filter already exists, its description is changed to reflect the new information in the input. Once added, a filter is available for use.

The filter description is taken from the pathname if the -F option is given or from the standard input if the - option is given. One of the two must be given to define or change a filter. If the filter named is one originally delivered with the LP print service, the -i option will restore the original filter description.

Once you have a filter definition complete, use one the following commands to add it to the system:

/usr/lib/lpfilter -f filtername -F filename

/usr/lib/lpfilter -f filtername -

The first command gets the filter definition from a file, and the second command gets the filter definition from you through the standard input. The filtername can be anything you choose as long as it contains 14 or less letters, digits, and underscores.

If you need to change a filter, just re-enter one of the same commands. You need only give the changed information; information you leave out stays the same.

Removing a filter

Use the following command to remove a filter:

/usr/lib/lpfilter -f filtername -x

Listing a filter description

You can use one the following commands to examine a defined filter:

/usr/lib/lpfilter -f filtername -l
/usr/lib/lpfilter -f filtername -l >filename

The first command presents the definition of the filter on your screen; the second command captures this definition in a file, which can later be used to redefine the filter if you inadvertently remove the filter from the print service.

The -l option is used to list the description of the filter named in filter-name. If the command is successful, the same listing of filter attributes is displayed that is shown earlier. If the command fails, an error message is sent to standard error.

Examples

Example 1

-Xb

only for the input type X

-l integer

for the length of the output page

-w integer

for the width of the output page

The filter definition looks like this:

   Input types: X,nroff37
   Output types: TX
   Printer types: TX
   Command: /usr/bin/npf
   Options: INPUT X = -Xb, LENGTH * = -l*,
   WIDTH * = -w*

This filter is called upon by the print service to convert the file. The filter is invoked as:

/usr/bin/npf -l72

Example 2

Example 3

-l integer

for the length of the output page

-s name

for the character set

-o portrait

-o landscape

for portrait or landscape orientation of the paper

You decide that your users need to give just the abbreviations port and land when they ask for the paper orientation. Because these are not options intrinsic to the print service, users specify them using the -y option to the lp command.

The filter definition looks like this:

   Input types: troff
   Output types: 9700
   Printer types: 9700
   Command: /usr/bin/x9700 -ib
   Options: LENGTH * = -l *, CHARSET * = -s *,
            MODES port = -o portrait, MODES land
            = -o landscape

A user submits a file of type troff for printing on a printer of type 9700 and requests landscape orientation using the gothic character set:

lp -T troff -S gothic -y land

This filter is invoked by the print service to convert the file as follows:

/usr/bin/x9700 -ib -s gothic -o landscape

Warning

Because of this possible impact, you may want to make changes to filters during periods when the print service is not being used much.

Limitations

Here are guidelines that can help you choose a good filter:

• Examine the kinds of files people submit for printing that have to be processed by the filter. If they stand alone, that is, if they do not reference other files that the filter needs, the filter is probably okay. Check also to see if the filter expects any other files except those submitted by a user for printing.

• If there can be referenced files inside the files submitted for printing or if the filter needs files other than those submitted by a user, then the filter is likely to fail because it does not access the additional files. We suggest you do not use the program as a filter, but have each user run the program before submitting the files for printing.

While a filter can be as simple or as complex as needed, there are only a few external requirements:

• The filter should get the content of a user's file from its standard input and send the converted file to the standard output.

• A slow filter can send messages about errors in the file to standard error. A fast filter should not send messages, as described below. Error messages from a slow filter will be collected and sent to the user who submitted the file for printing.
  

• If a slow filter dies because of receiving a signal, the print request is finished and the user who submitted the request is notified. Likewise, if a slow filter exits with a non-zero exit code, the print request is finished and the user is notified. The exit codes from fast filters are treated differently, as described later.

• A filter should not depend on other files that are not normally accessible to a regular user; if the filter fails when the user ran it directly, it will fail when the print service runs it.

• If it can, it should wait for a fault to clear before exiting. Additionally, it should continue printing at the top of the page where printing stopped after the fault clears. If this is not the administrator's intention, the print service should stop the filter before alerting the administrator.

• The filter should send printer fault messages to its standard error as soon as the fault is recognized. It does not have to exit but can wait as described above.
  

• It should not send messages about errors in the file to standard error. Any messages on the standard error eventually generate a pointer fault. These should be included in the standard output stream, where they can be read by the user.

• It should exit with a zero exit code if the user's file is finished (even if errors in the file prevented it from printing correctly).

• It should exit with a non-zero exit code only if a printer fault kept it from finishing a file.

• When added to the filter table, it must be added as a fast filter.
  

Authorization

See also

``Managing printers and print jobs'' in Administering printers