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 con-
     vert the content of a file to have a content type acceptable
     to a printer.


OPTIONS

     Arguments consist of the -f filter-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 specified 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 special 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 con-
           tents is specified 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 sup-
     plies the filter description. 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  follow-
     ing:

        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  con-
     sumes 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  pro-
           duce  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 adja-
           cent 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 filter to these printer types (from  lpad-
           min -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, fas-
           ter 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;  addi-
           tional  options  are constructed, based on the charac-
           teristics 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  con-
           structed  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 filter 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
     filter-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 \n con-
     structions, 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**31bytes).


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\=\(.*\) = -w\1

     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 pipeline.


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  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWpsu                     |
    |_____________________________|_____________________________|


SEE ALSO

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

     System Administration Guide: Basic Administration


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.


Man(1) output converted with man2html