--- name: "magicfilter" section: "8" platform: "linux" package: "magicfilter" version: "1.2-68" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/magicfilter" --- # magicfilter(8) 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 H. Peter Anvin \ ## SEE ALSO [**printcap**(5)](/printcap/5.md), **lpr**(8), [**dvips**(1)](/dvips/1.md), [**grog**(1)](/grog/1.md), [**gs**(1)](/gs/1.md), [**gzip**(1)](/gzip/1.md), [**troff**(1)](/troff/1.md).