Provided by: magicfilter_1.2-59_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).