NAME

       magicfilter - automatic configurable printer filter

SYNOPSIS

       magicfilter config-file [-c] [-n user] [-h host] [-iindent] [--debug] [other-options]

DESCRIPTION

       magicfilter  is  an  extensible  and  customizable  automatic  printer filter.  It selects an appropriate
       conversion technique for the input data by seeking for magic numbers, and then utilizing the  appropriate
       conversion utility.

       magicfilter  is primarily intended for use as the ``input filter'' by the lpd print spooler.  The options
       accepted by magicfilter are exactly the ones passed to the input filter by lpd.

   OPTIONS
       Typically magicfilter will be invoked by lpd and hence provided the right  options  automatically.   This
       list is included for reference only.

       Note that only the -n and -h options may have spaces between the option letter and the option value.

       -c     Copy the input to the output without any conversion whatsoever (used by lpd whenever the -l option
              is passed to the lpr program).

       -nuser, -n user
              The login name of the user who submitted the job.  Available to subfilters  as  $LPUSER.   If  the
              user has an associated GECOS entry it will be available as $LPUSERNAME.

       -hhost, -h host
              The host on which the job was submitted.  Available to subfilters as $LPHOST.

       -iindent
              A  numeric  option  passed  by  lpd;  can  be  set  by the user by the -i option to lpr.  Although
              nominally used for the  amount  of  indentation  requested,  magicfilter  makes  it  available  to
              subfilters for any useful purpose as $LPINDENT.

       -Cclassname
              LPRng class (priority) name.  Available to subfilters as $LPCLASS.

       -Fformat
              Format letter (passed by LPRng only).  When used as input filter (if) this will be f, when used as
              other filter types it will be the option character corresponding to  this  filter.   Available  to
              subfilters as $LPFORMAT.

       -Jjobname
              The name of the printer job (passed by LPRng only).  Available to subfilters as $LPJOB.

       -Kcopies
              Copy count (passed by LPRng only).  Available to subfilters as $LPCOPIES.

       -Lbannername
              User name from the banner page (passed by LPRng only).  Available to subfilters as $BANNERNAME.

       -Pprinter
              Printer name (passed by LPRng only).  Available to subfilters as $PRINTER.

       -Qqueuename
              Spool queue name (passed by LPRng only).  Available to subfilters as $LPQUEUE.

       -Raccountinfo
              Accounting information (passed by LPRng only).  Available to subfilters as $LPACCT.

       -Zoptions
              LPRng  ``Z-options''.   The  LPRng  lpr  program  supports  a -Z option, which can be used to pass
              arbitrary information to the printer filters.  Available to subfilters as $ZOPT.

       --debug
              Write the name of each facility invoked (together with any options) to standard error.   This  can
              be useful for debugging complicated configuration files.

       other options
              Any other options, such as the -w, -l, -x, and -y options typically passed by lpd are ignored.

   RUNNING MAGICFILTER FROM LPD
       To  run  magicfilter  from  lpd  it  should  be  entered as one of the filters in the /etc/printcap file.
       Typically, it will be the input filter (if).  Since most version of lpd do not accept  arguments  entered
       as  part of the filter name, typically the filter name entered into the /etc/printcap file will simply be
       the name of the configuration file, which is set executable and starts with the line:

       #! /usr/sbin/magicfilter

       Most UNIX kernels will then be able to treat the configuration file  itself  as  if  it  was  the  actual
       program.

       For  systems  which  do  not  support  the  ``#!-hack'',  the  filter set in the if entry should point to
       magicfilter directly, and the accounting file (af) entry should point to the configuration  file.   This,
       however, is a less general, and hence less desirable solution.

       This   version   of  magicfilter  supports  the  enhanced  lpd  included  with  the  LPRng  package  from
       dickory.sdsu.edu.

   THE CONFIGURATION FILE
       The configuration file is used by magicfilter to redirect various types of data to the various conversion
       utilities.   The  configuration  file  is  printer-specific,  and often system-specific, depending on the
       available conversion programs.  For example, a system which has GhostScript installed would  be  able  to
       print PostScript to a non-PostScript printer, whereas other systems typically would not.

       The configuration file contains a sequence of lines of the form:

       offset    magic     facility

       where  the  offset  represents  the  location  of  the  indentification  string in the data format, magic
       represents the identification string itself, facility represents the type of action to take.

       Blank lines and lines with a hash mark (#) as the first nonblank character are ignored.  A  line  may  be
       continued onto the next line by ending the line in a backslash (\).

       The  offset  is  a  nonnegative integer, which can be represented either in decimal form (default), octal
       form (preceded by 0), or hexadecimal form (preceded by 0x).

       The magic is a string of characters, which may include C-style  \-escape  sequences.   In  addition,  the
       sequence \? can be used to represent a ``wildcard'' byte.  If the string includes spaces, the spaces have
       to be preceded by a backslash, or the entire string must be enclosed in double quotation marks.

       For ambiguous matches, the first match is used.  Hence, the most specific match should always  be  placed
       first in the file.  In addition, the last line may be of the form:

       default   facility

       which designates a default action to be used in case no other action matches.  This will typically be the
       action for plain text.

   FACILITIES
       magicfilter provides the following options for the facility field in the configuration file:

       cat [prefix [suffix]]
              Copy the input to the output without any conversion, like the cat command.  If the optional prefix
              and suffix strings are specified, they are transmitted to the printer immediately before and after
              the data itself.  The prefix and suffix strings are specified in the same way as the magic  string
              (except  that  the wildcard sequence \? is not permitted), and like the magic sequence can contain
              any control character, including nulls (\0).  To specify a suffix without  a  prefix,  specify  an
              empty prefix string enclosed in double quotes (i.e. "").

       text [prefix [suffix]]
              Copy  the  input to the output, but add carriage return characters before every line feed and form
              feed character in the file, and a line feed-form feed sequence at end of  file.   The  prefix  and
              suffix  arguments  are  treated  the  same way as for the cat facility; the suffix, if present, is
              added after the final line feed-form feed sequence.

       postscript
              Same as the text facility, except add an ASCII EOT (Ctrl-D) character to  the  end  of  the  data.
              This  lets  a  PostScript  printer  know  that  the  end  of  the  job  has been reached.  This is
              functionally equivalent to the command

              text "" \004

       ignore Ignore the job; do not provide any output whatsoever.

       reject message
              Same as the ignore facility, but attempt to send an email message to the user  who  submitted  the
              job to inform that a job has been rejected and why.

       filter command
              Run the given command, feeding it the input data, and sending the output data to the printer.  The
              environment variables LPUSER, LPHOST, and LPINDENT is set to the values  of  the  user,  host  and
              indent  options  passed  to magicfilter.  Since the command is fed to /bin/sh it may contain shell
              special characters, and the sequences $LPUSER, $LPHOST, and $LPINDENT can be used  to  access  the
              values  of  the  passed  environment  variables.   If  the  lpd daemon on the system is LPRng, the
              following environment variables are also available, see the OPTIONS section for details:  LPCLASS,
              LPFORMAT, LPJOB, LPCOPIES, BANNERNAME, PRINTER, LPQUEUE, LPACCT, and ZOPT.

       pipe command
              Same  as  the  filter  facility,  except  that  the  output  data is fed back into magicfilter for
              reprocessing.  This is used for external filter programs which themselves do not produce a  format
              that the printer can accept, but which can be futher processed to obtain such a format.

       ffilter command

       fpipe command
              Same  as  the  filter  and  pipe  facilities,  respectively, except that the input is written to a
              temporary file before being fed to the filter program  given  by  command.   This  is  useful  for
              programs  which require seekable input, such as dvips, or which need to do multiple passes over an
              input file, such as grog.  The environment variable FILE is set to the name of the temporary  file
              (and, like the other ones, it can be accessed on the command line as $FILE).

HINTS

       Using the pipe facility together with zcat or gunzip lets you transparently print compressed files.

       The  pbmplus  or  netpbm  collections of image conversion utilities contain a large number of very useful
       external filter programs.

       You will probably  want  to  examine  the  sample  configuration  files  included  with  the  magicfilter
       distribution before creating your own.

BUGS

       Some data formats cannot be easily identified by a simple fixed-offset magic number check.

       Providing  large offsets can cause magicfilter to take up lots of memory.  Fortunately, large offsets for
       magic numbers are pretty much unheard of.

       Currently, there is no protection against the pipe or fpipe facilities going into an infinite loop.

AUTHOR

       H. Peter Anvin <hpa@zytor.com>

SEE ALSO

       printcap(5), lpr(8), dvips(1), grog(1), gs(1), gzip(1), troff(1).