MAGICFILTER(8)

✨ NAME ✨

okay so bestie, meet magicfilter — the automatic configurable printer filter. yes, this whole page is the MAGICFILTER(8) manual page from the System Manager's Manual, and no, it's not boring, stay with me 💖

---

🌸 SYNOPSIS 🌸

magicfilter config-file [-c] [-n user] [-h host] [-iindent] [--debug]
[other-options]

---

🦋 DESCRIPTION 🦋

magicfilter is an extensible and customizable automatic printer filter. it picks the right conversion technique for whatever data you throw at it by seeking for magic numbers, and then it calls in the appropriate conversion utility to handle it. like, it literally sniffs the file and goes "oh i know what this is" 💅

magicfilter is primarily intended to be used as the ``input filter'' by the lpd print spooler. and the options it accepts are exactly the ones lpd passes to the input filter — no more, no less. periodt.

---

👑 OPTIONS 👑

usually magicfilter gets invoked by lpd, so the right options just show up on their own like magic ✨. this list is here for reference only, bestie.

note that only the -n and -h options may have spaces between the option letter and the option value. the rest? no space, okay? 🙈

• -c — copy the input to the output with no 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. and if that user has an associated GECOS entry, it'll be available as $LPUSERNAME too 🎀
• -hhost, -h host — the host on which the job was submitted. available to subfilters as $LPHOST.
• -iindent — a numeric option passed by lpd; the user can set it with the -i option to lpr. nominally it's the amount of indentation requested, but magicfilter just makes it available to subfilters for any useful purpose as $LPINDENT. slay, flexible queen.
• -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'll 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 you can use to pass arbitrary information to the printer filters. available to subfilters as $ZOPT. iykyk 😌
• --debug — write the name of each facility invoked (together with any options) to standard error. this is so useful for debugging complicated configuration files, fr fr.
• other options — any other options, such as the -w, -l, -x, and -y options typically passed by lpd, are ignored. not their moment. 💀

---

🧚 RUNNING MAGICFILTER FROM LPD 🧚

to run magicfilter from lpd, you enter it as one of the filters in the /etc/printcap file. typically it'll be the input filter (if). since most versions of lpd don't accept arguments entered as part of the filter name, usually the filter name you put into /etc/printcap is simply the name of the configuration file — which you set executable, and which 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. iconic behaviour honestly 🫶

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. we don't love it but it exists.

this version of magicfilter supports the enhanced lpd included with the LPRng package from dickory.sdsu.edu. 💖

---

🌈 THE CONFIGURATION FILE 🌈

the configuration file is what magicfilter uses to redirect various types of data to the various conversion utilities. it's printer-specific, and often system-specific too, depending on which conversion programs you have available. for example: a system with GhostScript installed would be able to print PostScript to a non-PostScript printer, whereas other systems typically would not. it's giving "depends on your setup" ✨

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, and facility represents the type of action to take.

blank lines and lines with a hash mark (#) as the first nonblank character are ignored. and 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. also, 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. main character energy for plain text honestly 👑

---

💜 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're 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 they 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. not me ghosting the print job 💀
• 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. at least it's polite about it 🙈
• 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. round two, bestie 🔥
• 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. obsessed 😭
• 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. do your homework first 💅

---

💀 BUGS 💀

• some data formats cannot be easily identified by a simple fixed-offset magic number check. they're just mysterious like that.
• 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. be careful, bestie, do not let it spin forever ⭐

---

🎀 AUTHOR 🎀

H. Peter Anvin <hpa@zytor.com> — the legend who made all this happen 👑

---

🌟 SEE ALSO 🌟

printcap(5), lpr(8), dvips(1), grog(1), gs(1), gzip(1), troff(1).

---

that's the whole page bestie, thanks for reading all the way to the end 🫶 this was Version 1.2, dated March 1996, and it's been an absolute pleasure. go print something. slay 💖✨