lpfilter(ADM)

lpfilter -- administer filters used with the print service

Syntax

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

/usr/lib/lpfilter -f filtername -

/usr/lib/lpfilter -f filtername -i

/usr/lib/lpfilter -f filtername -x

/usr/lib/lpfilter -f filtername -l

Description

The lpfilter command is used to add, change, delete, and list filters used with the LP print service. (These functions are also accessible through the Printer Manager. See ``The Printer Manager interface'' in the System Administration Guide for more information) These filters are used to convert the content type of a file to a content type acceptable to a given printer. One of the following options must be used with the lpfilter command:

-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

Use lpfilter -f filtername to add or change 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

The print service has no fixed limit to the number of filters you can define. However, it is a good idea to remove filters no longer applicable to avoid extra processing by the print service, which must examine all filters to find one that works in a given situation.

Use the following command to remove a filter:

/usr/lib/lpfilter -f filtername -x

Listing a filter description

You can examine a filter definition once you add it to the print service. The lpfilter command displays the definition of the filter in a form suitable as input again so that you can save the output in a file for future reference.

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

This section contains several fictitious examples of filters and their uses.

Example 1

The filter program is called /usr/bin/npf. The program takes two input types, nroff37 and X, produces an output type called TX, and works with any printer of type TX. The program accepts three options:

-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*

A user submits a file of type nroff37 and asks that it be printed by a printer named lp1 which is of type TX, and requests a page length of 72:

lp -T nroff37 -d lp1 -o length=72

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

/usr/bin/npf -l72

Example 2

Another user submits a file of type X that is to be printed on the same printer, with default length and width. The filter is invoked as:

/usr/bin/npf -Xb

Example 3

The filter program is called /usr/bin/x9700. It takes one input type, troff, produces an output type called 9700, and will work with any printer of type 9700. The program has one fixed option, -ib, and accepts three other options:

-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

(The last line is split into three lines for readability in this example. It must be entered as a single line.)

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

Adding, changing, or deleting filters can cause print requests still queued to be canceled. This is because the print service evaluates each print request still queued to see which are affected by the filter change. Requests that are no longer printable, because a filter has been removed or changed, are canceled (with notifications sent to the people who submitted them). There can also be a delay in the response to new or changed print requests when filters are changed, due to the many characteristics that must be evaluated for each print request still queued. This delay can become noticeable if there are a large number of requests needing filtering.

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

It is tempting to use a program like troff, nroff, or a similar word-processing program as a filter. However, the troff and nroff programs have a feature that allows people to reference additional files in the source document; these are called ``include files''. The spooler does not know about these files and does not queue them with the source document. The troff or nroff program may fail because it cannot access these additional files. Other programs may have similar features that limit their use as filters.

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.

Referenced files that are always given with full pathnames may be okay, but only if the filter is used for local print requests. When used on requests submitted from a remote machine for printing on your machine, the filter may still fail if the referenced files are only on the remote machine.

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.

There are a few more requirements if the filter is also to detect printer faults:

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

Permission to use this utility requires the lp authorization.