summaryrefslogtreecommitdiffstats
path: root/magicfilter.man.in
blob: a76525ea6bdcaa45e66e4e052dcc898f173fd5c2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
.\" $Id$ -*- nroff -*-
.TH MAGICFILTER 8 "Version 1.3" "November 1998"
.\" man page for magicfilter
.\" -----------------------------------------------------------------------
.\"   
.\"   Copyright 1995-1998 H. Peter Anvin - All Rights Reserved
.\"
.\"   This file is free software; you can redistribute it and/or modify
.\"   it under the terms of the GNU General Public License as published by
.\"   the Free Software Foundation, Inc., 675 Mass Ave, Cambridge MA 02139,
.\"   USA; either version 2 of the License, or (at your option) any later
.\"   version; incorporated herein by reference.
.\"
.\" -----------------------------------------------------------------------
.SH NAME
magicfilter \- automatic configurable printer filter
.SH SYNOPSIS
.B magicfilter
config-file [\-\-debug] [\-c] [lpd-options]
.SH DESCRIPTION
.B magicfilter
is an extensible and customizable automatic printer filter.  It
selects an appropriate conversion technique for the input data by
seeking for
.IR "magic numbers" ,
and then utilizing the appropriate conversion utility.
.PP
.B magicfilter
is primarily intended for use as the ``input filter'' by the
.B lpd
print spooler.  The options accepted by
.B magicfilter
are exactly the ones passed to the input filter by
.BR lpd .
.SS OPTIONS
Typically
.B magicfilter
will be invoked by
.B lpd
and hence provided the right options automatically.  This list is
included for reference only.
.PP
Note that only the
.I \-n
and
.I \-h
options may have spaces between the option letter and the option value.
.TP
.I \-c
Copy the input to the output without any conversion whatsoever (used
by
.B lpd
whenever the
.I \-l
option is passed to the
.B lpr
program).
.TP
.I "\-nuser, \-n user"
The login name of the user who submitted the job.  Available to
subfilters as
.BR $LPUSER .
.TP
.I "\-hhost, \-h host"
The host on which the job was submitted.  Available to subfilters as
.BR $LPHOST .
.TP
.I "\-iindent"
A numeric option passed by
.BR lpd ;
can be set by the user by the
.I \-i
option to
.BR lpr.
Although nominally used for the amount of indentation requested,
.B magicfilter
makes it available to subfilters for any useful purpose as
.BR $LPINDENT .
.TP
.I "\-Cclassname"
LPRng class (priority) name.  Available to subfilters as
.BR $LPCLASS .
.TP
.I "\-Fformat"
Format letter (passed by LPRng only).  When used as input filter (if)
this will be
.IR f ,
when used as other filter types it will be the option character
corresponding to this filter.  Available to subfilters as
.BR $LPFORMAT .  
.TP
.I "\-Jjobname"
The name of the printer job (passed by LPRng only).  Available to
subfilters as
.BR $LPJOB .
.TP
.I "\-Kcopies"
Copy count (passed by LPRng only).  Available to subfilters as
.BR $LPCOPIES .
.TP
.I "\-Lbannername"
User name from the banner page (passed by LPRng only).  Available to
subfilters as
.BR $BANNERNAME .
.TP
.I "\-Pprinter"
Printer name (passed by LPRng only).  Available to subfilters as
.BR $PRINTER .
.TP
.I "\-Qqueuename"
Spool queue name (passed by LPRng only).  Available to subfilters as
.BR $LPQUEUE .
.TP
.I "\-Raccountinfo"
Accounting information (passed by LPRng only).  Available to
subfilters as 
.BR $LPACCT .
.TP
.I "\-Zoptions"
LPRng ``Z-options''.  The LPRng
.B lpr
program supports a
.I \-Z
option, which can be used to pass arbitrary information to the printer
filters.  Available to subfilters as
.BR $ZOPT .
.TP
.I \-\-debug
Write the name of each facility invoked (together with any options) to
standard error.  This can be useful for debugging complicated
configuration files.
.TP
.I "other options"
Any other options, such as the
.IR \-w ,
.IR \-l ,
.IR \-x ,
and
.I \-y 
options typically passed by
.B lpd
are ignored.
.SS RUNNING MAGICFILTER FROM LPD
To run
.B magicfilter
from
.B lpd
it should be entered as one of the filters in the
.I /etc/printcap
file.  Typically, it will be the input filter (if).  Since most
version of
.B lpd
do not accept arguments entered as part of the filter name, typically
the filter name entered into the
.I /etc/printcap
file will simply be the name of the configuration file, which is set
executable and starts with the line:
.PP
.B #! XXX_BINDIR_XXX/magicfilter
.PP
Most UNIX kernels will then be able to treat the configuration file
itself as if it was the actual program.
.PP
This version of
.B magicfilter
supports the enhanced 
.B lpd
included with the LPRng package from
.IR dickory.sdsu.edu .
.SS THE CONFIGURATION FILE
The configuration file is used by
.B 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:
.PP
.I "offset	magic	facility"
.PP
where the
.I offset
represents the location of the indentification string in the data
format,
.I magic
represents the identification string itself,
.I 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 (\e).

The
.I offset
is a nonnegative integer, which can be represented either in decimal
form (default), octal form (preceded by
.IR 0 ),
or hexadecimal form (preceded by
.IR 0x ).

The
.I magic
is a string of characters, which may include C-style \e-escape
sequences.  In addition, the sequence \e? 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:
.PP
\fBdefault\fR	\fIfacility\fR
.PP
which designates a default action to be used in case no other action
matches.  This will typically be the action for plain text.
.SS FACILITIES
.B magicfilter
provides the following options for the
.I facility
field in the configuration file:
.TP
\fBcat\fR [\fIprefix\fR [\fIsuffix\fR]]
Copy the input to the output without any conversion, like the
.B cat
command.  If the optional
.I prefix
and
.I suffix
strings are specified, they are transmitted to the printer immediately
before and after the data itself.  The
.I prefix
and
.I suffix
strings are specified in the same way as the
.I magic
string (except that the wildcard sequence \e? is not permitted), and like
the
.I magic
sequence can contain any control character, including nulls (\e0).  To
specify a
.I suffix
without a
.IR prefix ,
specify an empty
.I prefix
string enclosed in double quotes (i.e. "").
.TP
\fBtext\fR [\fIprefix\fR [\fIsuffix\fR]] 
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
.I prefix
and
.I suffix
arguments are treated the same way as for the
.B cat
facility; the
.IR suffix ,
if present, is added after the final line feed-form feed sequence.
.TP
\fBpostscript\fR
Same as the
.B 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
.TP
.I " "
\fBtext\fR "" \e004
.TP
\fBignore\fR
Ignore the job; do not provide any output whatsoever.
.TP
\fBreject\fR \fImessage\fR
Same as the
.B 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.
.TP
\fBfilter\fR \fIcommand\fR
Run the given
.IR command ,
feeding it the input data, and sending the output data to the printer.
The environment variables
.BR LPUSER ,
.BR LPHOST ,
and
.B LPINDENT
is set to the values of the user, host and indent options passed to
.BR magicfilter .
Since the
.I command
is fed to
.I /bin/sh
it may contain shell special characters, and the sequences
.BR $LPUSER ,
.BR $LPHOST ,
and
.B $LPINDENT
can be used to access the values of the passed environment variables.
If the
.B lpd
daemon on the system is LPRng, the following environment variables are also
available, see the
.B OPTIONS
section for details:
.BR LPCLASS ,
.BR LPFORMAT ,
.BR LPJOB ,
.BR LPCOPIES ,
.BR BANNERNAME ,
.BR PRINTER ,
.BR LPQUEUE ,
.BR LPACCT ,
and
.BR ZOPT .
.TP
\fBpipe\fR \fIcommand\fR
Same as the
.B filter
facility, except that the output data is fed back into
.B 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.
.TP
\fBffilter\fR \fIcommand\fR
.sp -0.5
.TP
\fBfpipe\fR \fIcommand\fR
Same as the
.B filter
and
.B pipe
facilities, respectively, except that the input is written to a
temporary file before being fed to the filter program given by
.IR command .
This is useful for programs which require seekable input, such as
.BR dvips ,
or which need to do multiple passes over an input file, such as
.BR grog .
The environment variable
.B FILE
is set to the name of the temporary file (and, like the other ones, it
can be accessed on the command line as
.BR $FILE ).
.TP
\fBrfilter\fR \fIcommand\fR
.sp -0.5
.TP
\fBrpipe\fR \fIcommand\fR
.sp -0.5
.TP
\fBrffilter\fR \fIcommand\fR
.sp -0.5
.TP
\fBrfpipe\fR \fIcommand\fR
Same as the
.BR filter ,
.BR pipe ,
.B ffilter
and
.B fpipe
facilities, respectively, but the program is given a named pipe (FIFO)
to write to rather than standard output.  This is used for programs
such as
.BR gs (1)
(Ghostscript), that may write diagnostic or console output on stdout.
.sp
The environment variable
.B OUT
(accessible as
.BR $OUT )
contains the name of this output FIFO.  A file descriptor is also
opened for writing onto this FIFO; the file descriptor number is given
in the environment variable
.B OUTFD
.RB ( $OUTFD ).
.sp
By default, the standard output of the program is redirected to the
.B magicfilter
standard error.
.SH HINTS
Using the
.B pipe
facility together with
.B zcat
or
.B gunzip
lets you transparently print compressed files.
.PP
The
.B netpbm
collection of image conversion utilities contain a large number of
very useful external filter programs.
.PP
Unless you have a printer capable of printing PostScript natively, you
probably want to get a host-based PostScript interpreter, such as
GhostScript (see
.BR gs (1)).
.PP
You will probably want to examine the sample configuration files
included with the
.B magicfilter
distribution before creating your own.  For most systems, these
configuration files will be usable without changes.
.SH BUGS
Some data formats cannot be easily identified by a simple fixed-offset
magic number check.
.PP
Providing large offsets can cause
.B magicfilter
to take up lots of memory.  Fortunately, large offsets for magic
numbers are pretty much unheard of.
.PP
There is no protection against the
.BR pipe ,
.BR fpipe ,
.B rpipe
or
.B rfpipe
facilities going into an infinite loop.
.PP
.SH AUTHOR
H. Peter Anvin <hpa@zytor.com>
.SH SEE ALSO
.BR printcap (5),
.BR lpr (8),
.BR dvips (1),
.BR grog (1),
.BR gs (1),
.BR gzip (1),
.BR troff (1).