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