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 Administering printers 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:

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:

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:


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

Authorization

Permission to use this utility requires the lp authorization.

See also

lp(C), lpadmin(ADM)

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


© 2005 The SCO Group, Inc. All rights reserved.
SCO OpenServer Release 6.0.0 -- 03 June 2005