magicfilter - automatic configurable printer filter
magicfilter config-file [-c] [-n user] [-h host] [-iindent]
[--debug] [other-options]
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.
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.
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 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.
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).
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.
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.
H. Peter Anvin <hpa@zytor.com>