lpfilter(1M)						  System Administration Commands					      lpfilter(1M)

NAME

       lpfilter - administer filters used with the LP print service

SYNOPSIS

       /usr/sbin/lpfilter -f filter-name
	    {- | -i | -l | -x | -F pathname}

DESCRIPTION

       The lpfilter command is used to add, change, delete, or list a filter used with the LP print service. These  filters convert the content of
       a file to have a content type acceptable to a printer.

OPTIONS

       Arguments consist of the -ffilter-name option and exactly one of the arguments appearing within braces ({}) in the SYNOPSIS.

       -		 Adds or changes a filter as specified from standard input. The format of the input is specified below. If -f all is spec-
			 ified with the  - option, the specified change is made to all existing filters. This is not useful.

       -f filter-name	 Specifies  the  filter-name of the filter to be added, changed, reset, deleted, or listed. The  filter name all is a spe-
			 cial filter name defined below. The  -f option is required.

       -F pathname	 Adds or changes a filter as specified by the contents of the file pathname. The format of the file's contents	is  speci-
			 fied  below. If -f all is specified with the -F option, the specified change is made to all existing filters. This is not
			 useful.

       -i		 Resets a filter to its default settings. Using  -f all with the  -i option restores  all  filters  for  which	predefined
			 settings are available to their original settings.

       -l		 Lists a filter description. Using -f all with the -l option produces a list of all filters.

       -x		 Deletes a filter. Using -f all with the -x option results in all filters being deleted.

USAGE

   Adding or Changing a Filter
       The filter named in the -f option is added to the filter table. If the filter already exists, its description is changed to reflect the new
       information in the input.

       When  - is specified, standard input supplies the filter description. When -F is specified, the file pathname supplies the filter  descrip-
       tion. One of these two options must be specified to add or change a filter.

       When  an  existing filter is changed with the -F or - 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.

       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 LP print service knows the following:

	   o	  The content type of the request (specified by  lp -T or determined implicitly).

	   o	  The name of the printer (specified by  lp -d).

	   o	  The printer type (specified by lpadmin -T).

		  The  printer	type  is  intended to be a printer model, but some people specify it with a content type even though lpadmin -I is
		  intended for this purpose.

	   o	  The content types acceptable to the printer (specified by lpadmin -I).

		  The values specified by the lpadmin -T are treated as if they were specified by the -I option as well.

	   o	  The modes of printing asked for by the originator of the request (specified by various options to 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 lp arguments that invoke filters  (-y and -P).

       The  contents  of the file (specified by the -F option) and the input stream from standard input (specified by  -) 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.

	 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  gives the content types that can be accepted by the filter. The default is any. The document content type must  be a
			member of this list for the initial filter in the sequence.

       Output types	This gives the content types that the filter can  produce from any of the input (content) types.  The default is any.  The
			intersection of the output types of this list and the content types acceptable to the printer (from lpadmin -I and lpadmin
			-T) must be non-null for the last filter in the sequence.  For adjacent filters in the sequence, the intersection of  out-
			put types of one and the input types of the next must be non-null.

       Printer types	This  gives the printer types for which this  printer can be used. The LP print service will restrict the use of  the fil-
			ter to these printer types (from lpadmin -T). The default is any.

       Printers 	This gives the names of the printers for which the filter can be used. The LP print service will restrict the use  of  the
			filter to just the printers named. The default is any.

       Filter type	This marks the filter as a slow filter or a fast 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 slow. 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.

       Command		This  specifies  which	program  to  run to invoke the filter. The full program pathname as well as fixed options must	be
			included in the shell-command; additional options are constructed, based on the characteristics of each print request  and
			on the Options 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.

       Options		This  is  a  comma-separated  list of templates used by  the  LP print service to construct options to the filter from the
			characteristics of each print request listed in the table later. The -y and  - P arguments to the lp command cause a  fil-
			ter sequence to be built even if there is no need for a conversion of content types.

			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 one of the following:  a literal pattern of one of the forms listed in the table, a single asterisk (*), or a
			regular expression. If	pattern matches  the value of the characteristic, the template fits and is used to generate a fil-
			ter-specific option. The  replacement is what will be used as the option.

			Regular expressions are the same as those found on the regexp(5) manual page. This includes the (...) and  
  construc-
			tions, which can be used to extract portions of the pattern for copying into the replacement, and the &, which can be used
			to copy the entire pattern into the replacement.

			The replacement can also contain a *; it too, is replaced with the entire pattern, just like the & of regexp(5).

       The keywords are:

	 lp Option	    Characteristic   keyword	     Possible patterns

	 -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	     printer-name

	 -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	     integer
			   copies

   Resetting a Filter to Defaults
       If the filter named is one originally  delivered with the  LP print service, the -i option restores the original filter description.

   Deleting a Filter
       The  -x option is used to delete the filter  specified in filter-name from the LP filter table.

   Listing a Filter Description
       The  -l 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:

	 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

       If the command fails, an error message is sent to standard error.

   Large File Behavior
       See largefile(5) for the description of the behavior of lpfilter when encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).

EXAMPLES

       Example 1 Printing with the landscape option

       For example, the template

	 MODES landscape = -l

       shows that if a print request is submitted with the -y landscape option, the filter will be given the option -l.

       Example 2 Selecting the printer type

       As another example, the template

	 TERM * = -T *

       shows  that  the  filter  will be given the option -T printer-type for whichever  printer-type is associated with a print request using the
       filter.

       Example 3 Using the keywords table

       Consider the template

	 MODES prwidth=(.*) = -w1

       Suppose a user gives the command

	 lp -y prwidth=10

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

EXIT STATUS

       The following exit values are returned:

       0	   Successful completion.

       non-zero    An error occurred.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWpsu			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       lp(1), sh(1), lpadmin(1M), attributes(5), largefile(5), regexp(5)

NOTES

       If  the	lp  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.

SunOS 5.11							    3 Apr 1997							      lpfilter(1M)