Provided by: magicfilter_1.2-66_amd64 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).