Provided by: magicfilter_1.2-64_i386 bug

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