Ubuntu Manpage: magicfilter - automatic configurable printer filter

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