lpfilter(ADM) 19 June 1992 lpfilter(ADM) Name lpfilter - administer filters used with the print service Syntax /usr/lib/lpfilter -f filtername -C 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. (The functions of lpfilter are also accessible through the sysadmsh(ADM) Printers -> Auxillary -> Filter selection.) 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: -C pathname (or - for standard input) to add or change a filter, -i to reset an original LP print service filter to its factory setting, -x to delete a filter, or -l to list a filter description. The argument all can be used instead of a filtername with any of these options. When all is specified with the -C or - option, the requested change is made to all filters. Using all with the -i option has the effect of restoring to their original settings all filters for which predefined settings were initially available. Using the all argument with the -l option produces a list of all filters, and using all with the -x option results in all filters being deleted. 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. In general these three functions are very printer-specific, and a single filter capable of doing everything would be very complex. Therefore, in order to provice a flexible print service, the roles are separated out in a modular fashion. Consequently, the system administrator can substitute a different filter that performs a specific function without changing the rest of the print service. A default filter is provided with the print service to provide simple printer fault detection; it does not convert files or handle any of the special modes. This may be adequate for your needs. Converting files The print service allows you to type each printer you add to the system and allows a user to type each file he or she submits for printing. This information is used to match a file with the printer that can best repro- duce that file. Because many applications can generate data for various printers, this is often sufficient. However, not all of the applications you use may be able to generate output that works on your printers. By defining and creating a filter that converts such output into a type that your printers can handle, you can begin to support more applications in the print service. A small set of simple filters are provided that convert output from applications like nroff to data streams that print properly on some printers. Each filter that is added to the system is classified with the input type it can accept and the output type it can produce. Now the print service can be more sophisticated in its attempt to match a user's file with a printer. If it cannot find a direct match, it consults the table of filters to find one that converts the file's type into the printer's type. Handling special modes Another important role that filters can provide is the handling of the various printing modes that may be encountered. Each filter you add to the filter table can be registered as handling several aspects of print- ing. These are listed here: Input type Output type Printer type Character pitch Line pitch Page length Page width Pages to print Character set Form name Number of copies Modes A filter is not required to handle most of these, only the modes. The print service provides a default handling for the rest. However, it may be more efficient to have a filter handle these, or it may be that a filter has to know several of these aspects if it is to fulfill its other roles properly. A filter may need to know, for example, the page size and the print spacing if it is going to break up the pages in a file to fit on the printed pages. As another example, some printers can handle multiple copies more efficiently than the print service can, so a filter that is controlling the printer can use the number of copies information to skip the print service's default handling of this. Later we see how you can register the printing modes and other aspects of printing with each filter. Detecting printer faults Just as converting a file and handling special printing modes is a print- er-specific role, so is the detection of printer faults. The print ser- vice attempts to do this in general, and for most printers it properly detects a fault. However, it is limited to checking for ``hang-ups'' (loss of carrier or the signal that indicates the printer is on-line) and excessive delays in printing (that is, receipt of an XOFF flow-control character to shut off the data flow with no matching XON to turn the flow back on). It also cannot determine the cause of the fault, so it cannot tell you what to look for. A properly designed filter can provide better fault coverage. Some printers can send a message to the host describing the reason for a fault. Others indicate a fault by dropping carrier or shutting off data flow. A filter can serve you by giving more information about a fault and detecting more of them. Another benefit a filter can give is to wait for a printer fault to clear and to resume printing. This allows for more efficient printing when a fault occurs because the print request that was interrupted does not have to be reprinted in its entirety. Only a real filter, which understands the control sequences used by a printer, know where a file breaks into pages; thus, only the filter knows how far back to go in the file to res- tart properly. The print service has a simple interface that lets the filter get the fault information to you and restart if it can. The alerting mechanism is handled by the print service; the interface program that manages the filter takes all error messages from the filter and places them into an alert message that can be sent to you. Thus, you see any fault descrip- tions that the filter puts out. If you set the printer configuration so that printing should automatically resume after a fault is cleared, the interface program keeps the filter active so that it can pick right up where it left off. 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 -C 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. Filters are used to convert the content of a request into a data stream acceptable to a printer. For a given print request, the LP print service will know the following: + the type of content in the request + the name of the printer + the type of the printer + the types of content acceptable to the printer + the modes of printing asked for by the originator of the request It will use this information to find a filter that will convert the con- tent into a type acceptable to the printer. Below is a list of items that provide input to this command and descrip- tions of each item. All lists are separated by commas or spaces. 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 is the list of file types that the filter can process. Most filters can take only one input type, but the print service does not restrict them to one. Several file types may be similar enough for the filter that it can deal with them. You can use whatever names you like here. Because the print service uses these names to match a filter with a file type, you should be consistent in your naming conven- tion. For example, if more than one filter can accept the same input type, use the same name. These names should be advertised to your users so they know how to name a file's type when they submit the file for printing. Output types This is the list of file types that the filter can produce as output. For each file, the filter produces a single output type, but it may be able to vary that type on demand. These names should either match the types of printers you have on your system or should match the input types handled by other filters. The print service gangs filters together in a shell pipeline to produce a new filter if it finds that several passes by different filters are needed to con- vert a file. It is unlikely that you need this level of sophistication, but the print service allows it. Try to find a set of filters that take as input types all the dif- ferent files your users may want printed and that convert those files directly into types your printers can handle. Printer types This is a list of printer types into which the filter can convert files. While for most filters this list is identi- cal to the output types, it can be different. For example, you may have a printer that is given a single type for purposes of initialization but which can recognize several different types of files. In essence, these print- ers have an internal filter that converts the various types into one with which they can deal. Thus, a filter may pro- duce one of several output types that match the ``file types'' that the printer can handle. The filter should be marked as working with that printer type. As another example, you may have two different models of printers that are listed as both accepting the same types of files. However, due to slight differences in manufac- ture, one printer deviates in the results it produces. You label the printers as being of different printer types, say A and B, where B is the one that deviates. You create a filter that adjusts files to account for the deviation pro- duced by printers of type B. Because this filter is only needed for those printer types, you would list it as work- ing only on type B printers. For most printers and filters, you can leave this part of the filter definition blank. Printers You may have some printers that, although they are of the correct type for a filter, are in other ways not adequate for the output that the filter produces. For instance, you may want to dedicate one printer for fast turn-around; only files that the printer can handle without filtering are sent to that printer. Other printers, of identical type, you allow for files that may need extensive filtering before they can be printed. You will label the filter as working with only the latter printers. In most cases, the filter should be able to work with all printers that accept the output that the filter produces, so you can leave this part of the filter definition blank. Filter type The print service recognizes fast filters and slow filters. Fast filters are labeled fast either because they incur little overhead in preparing a file for printing or because they must have access to the printer when they run. A filter that is to detect printer faults has to be a fast filter. Slow filters are the opposite. Filters that incur a lot of overhead in preparing a file and that do not have to have access to the printer should be labeled slow. The print service runs slow filters in the background without tying up a printer. This allows files that need fast filtering (or no filtering) to move ahead; printers are not left idle while a slow filter works on a file if other files can be printed. Command This is the full pathname of the program to run; this is the filter. If there are any fixed options that the pro- gram always needs, you can include them here. Options This is a list of templates separated by commas used by the LP print service to construct options to the filter from the characteristics of each print request listed in the table later. 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 either a literal pattern of one of the forms listed in the table or a single asterisk, (*); if the pattern matches the value of the characteristic, the template fits and is used to generate a filter-specific option. A pattern of ``*'' matches any value. The replacement is a string used as a filter-specific option with an embedded asterisk (*) replaced with the value of the characteristic. ___________________________________________________________ lp option Characteristic keyword Possible ___________________________________________________________ -T Content type INPUT content-type (input) N/A Content type OUTPUT content-type (output) N/A Printer type TERM printer-type -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- print wheel set-name/ print- wheel-name -f Form name FORM form-name -y Modes MODES mode -n Number of COPIES integer copies If a pattern or replacement must include a comma or equals sign (=), escape its special meaning by preceding it with a backslash. A backslash in front of these two characters is removed when the pattern or replace- ment is used. (All other backslashes are left alone.) The source of the values for these templates are as follows: + The values of the INPUT and OUTPUT templates come from the file type that needs to be converted by the filter and the output type that has to be produced, respectively. They will each a type registered with the filter. + The value for the TERM template is the printer type. + The values for the CPI, LPI, LENGTH, and WIDTH templates come from the user's request, the form being used, or the defaults for the printer. + The value for the PAGES template is a list of pages that should be printed. Typically it is a list of page ranges, either a pair of num- bers or a single number, each range separated by a comma (for example, 1-5,6,8,10 for pages 1 through 5, 6, 8, and 10). However, whatever value was given in the -P option to a print request is passed unchanged. + The value for the CHARSET template is the name of the character set to be used. + The value for the FORM template is the name of the form being printed on, if any. + The value of the COPIES template is the number of copies of the file that should be made. If the filter uses this template, the print ser- vice reduces the number of copies of the filtered file it prints to 1, because this ``single copy'' is really the multiple copies produced by the filter. + The value of the MODES template comes from the -y option of the lp command, the command a person uses to submit a print request. Because a user can give several -y options, there may be several values for the MODES template. The values are applied in the left-to-right order given by the user. For example, the template MODES landscape = -l would show that if a print request includes the -y landscape option, the filter should be given the option -l. As another example, the template TERM * = -T * would show that the filter should be given the option -T printer-type for whichever printer-type is associated with a print request using the filter. When an existing filter is changed with this command, items that are not specified in the new information are left as they were. When a new filter is added with this command, unspecified items are given default values. Note that a filter name and a command must be given. A filter with no input type value is assumed to work with any input type; this is also true for the output type, printer type, and printer values. After you gather this information about the filter, use it as input to the lpfilter(ADM) command (or the sysadmsh equivalent). You may want to first record this information in your own file to make it easier to edit the information as you enter it. You can then give the file as input instead. However you enter it, you should present the information in the following way: Input types: input-type-list Output types: output-type-list Printer types: printer-type-list Printers: printer-list Filter type: fast or slow Command: simple-command Options: template-list The information can appear in any order. Not all the information has to be given. The table below contains the defaults used for any missing in- formation. _________________________________________________________________________ Item Default _________________________________________________________________________ Input types any Output types any Printer types any Printers any Filter type slow Command (no default) Options (none) As you can see, the defaults define a very flexible filter, so you prob- ably have to supply at least the input and output type(s). When you enter a list, separate the items in the list with blanks or commas. Once you have a filter definition complete, use one the following com- mands to add it to the system: /usr/lib/lpfilter -f filtername -F filename /usr/lib/lpfilter -f filtername - <DELTA> sysadmsh users select: Printers -> Auxiliary -> Filter -> Change 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 applica- ble 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 <DELTA> sysadmsh users select: Printers -> Auxiliary -> Filter -> Remove 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 <DELTA> sysadmsh users select: Printers -> Auxiliary -> Filter -> List 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. See also lp(C), lpadmin(ADM) Authorization Permission to use this utility requires the lp authorization. Examples This section contains several 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 print- er 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 fol- lows: /usr/bin/x9700 -ib -s gothic -o landscape Notes It is tempting to use a program like troff, nroff, or a similar word-pro- cessing 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 print- ing 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 addi- tional files. We suggest you do not use the program as a filter, but have each user run the program before submitting the files for print- ing. 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. Like- wise, 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 acces- sible 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. Addi- tionally, 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. Warnings 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 charac- teristics 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.