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