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:
offsetmagicfacility
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:
defaultfacility
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.
rejectmessage
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.
filtercommand
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.
pipecommand
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.
ffiltercommand
fpipecommand
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.