| blob | d4a401c5e9373f09814d59ef025351ab4fac0896 |
1 '\" te
2 .\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved
3 .\" Copyright 1989 AT&T
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH LPFILTER 1M "Apr 3, 1997"
8 .SH NAME
9 lpfilter \- administer filters used with the LP print service
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fB/usr/sbin/lpfilter\fR \fB-f\fR \fIfilter-name\fR
14 {\fB-\fR | \fB-i\fR | \fB-l\fR | \fB-x\fR | \fB-F\fR \fIpathname\fR}
15 .fi
17 .SH DESCRIPTION
18 .sp
19 .LP
20 The \fBlpfilter\fR command is used to add, change, delete, or list a filter
21 used with the \fBLP\fR print service. These filters convert the content of a
22 file to have a content type acceptable to a printer.
23 .SH OPTIONS
24 .sp
25 .LP
26 Arguments consist of the \fB-f\fR\fIfilter-name\fR option and exactly one of
27 the arguments appearing within braces (\fB{\fR\|\fB}\fR) in the SYNOPSIS.
28 .sp
29 .ne 2
30 .na
31 \fB\fB\(mi\fR\fR
32 .ad
33 .RS 18n
34 Adds or changes a filter as specified from standard input. The format of the
35 input is specified below. If \fB-f\fR \fBall\fR is specified with the
36 \fB\(mi\fR option, the specified change is made to all existing filters. This
37 is not useful.
38 .RE
40 .sp
41 .ne 2
42 .na
43 \fB\fB-f\fR \fIfilter-name\fR\fR
44 .ad
45 .RS 18n
46 Specifies the \fIfilter-name\fR of the filter to be added, changed, reset,
47 deleted, or listed. The filter name \fBall\fR is a special filter name defined
48 below. The \fB-f\fR option is required.
49 .RE
51 .sp
52 .ne 2
53 .na
54 \fB\fB-F\fR \fIpathname\fR\fR
55 .ad
56 .RS 18n
57 Adds or changes a filter as specified by the contents of the file
58 \fIpathname\fR. The format of the file's contents is specified below. If
59 \fB\fR\fB-f\fR\fB all\fR is specified with the \fB-F\fR option, the specified
60 change is made to all existing filters. This is not useful.
61 .RE
63 .sp
64 .ne 2
65 .na
66 \fB\fB-i\fR\fR
67 .ad
68 .RS 18n
69 Resets a filter to its default settings. Using \fB\fR\fB-f\fR\fB all\fR with
70 the \fB-i\fR option restores all filters for which predefined settings are
71 available to their original settings.
72 .RE
74 .sp
75 .ne 2
76 .na
77 \fB\fB-l\fR\fR
78 .ad
79 .RS 18n
80 Lists a filter description. Using \fB-f\fR \fBall\fR with the \fB-l\fR option
81 produces a list of all filters.
82 .RE
84 .sp
85 .ne 2
86 .na
87 \fB\fB-x\fR\fR
88 .ad
89 .RS 18n
90 Deletes a filter. Using \fB-f\fR \fBall\fR with the \fB-x\fR option results in
91 all filters being deleted.
92 .RE
94 .SH USAGE
95 .SS "Adding or Changing a Filter"
96 .sp
97 .LP
98 The filter named in the \fB-f\fR option is added to the filter table. If the
99 filter already exists, its description is changed to reflect the new
100 information in the input.
101 .sp
102 .LP
103 When \fB\(mi\fR is specified, standard input supplies the filter description.
104 When \fB-F\fR is specified, the file \fIpathname\fR supplies the filter
105 description. One of these two options must be specified to add or change a
106 filter.
107 .sp
108 .LP
109 When an existing filter is changed with the \fB-F\fR or \fB\(mi\fR option,
110 lines in the filter description that are not specified in the new information
111 are not changed. When a new filter is added with this command, unspecified
112 lines receive default values. See below.
113 .sp
114 .LP
115 Filters are used to convert the content of a request from its initial type
116 into a type acceptable to a printer. For a given print request, the \fBLP\fR
117 print service knows the following:
118 .RS +4
119 .TP
120 .ie t \(bu
121 .el o
122 The content type of the request (specified by \fBlp\fR \fB-T\fR or determined
123 implicitly).
124 .RE
125 .RS +4
126 .TP
127 .ie t \(bu
128 .el o
129 The name of the printer (specified by \fBlp\fR \fB-d\fR).
130 .RE
131 .RS +4
132 .TP
133 .ie t \(bu
134 .el o
135 The printer type (specified by \fBlpadmin\fR \fB-T\fR).
136 .sp
137 The printer type is intended to be a printer model, but some people specify it
138 with a content type even though \fBlpadmin\fR \fB-I\fR is intended for this
139 purpose.
140 .RE
141 .RS +4
142 .TP
143 .ie t \(bu
144 .el o
145 The content types acceptable to the printer (specified by \fBlpadmin\fR
146 \fB-I\fR\fB)\fR.
147 .sp
148 The values specified by the \fBlpadmin\fR \fB-T\fR are treated as if they were
149 specified by the \fB-I\fR option as well.
150 .RE
151 .RS +4
152 .TP
153 .ie t \(bu
154 .el o
155 The modes of printing asked for by the originator of the request (specified by
156 various options to \fBlp\fR).
157 .RE
158 .sp
159 .LP
160 The system uses the above information to construct a list of one or more
161 filters that converts the document's content type into a content type
162 acceptable to the printer and consumes all \fBlp\fR arguments that invoke
163 filters (\fB-y\fR and \fB-P\fR).
164 .sp
165 .LP
166 The contents of the file (specified by the \fB-F\fR option) and the input
167 stream from standard input (specified by \fB\(mi\fR) must consist of a series
168 of lines, such that each line conforms to the syntax specified by one of the
169 seven lines below. All lists are comma or space separated. Each item contains a
170 description.
171 .sp
172 .in +2
173 .nf
174 \fBInput types: \fR\fIcontent-type-list\fR
175 \fBOutput types: \fR\fIcontent-type-list\fR
176 \fBPrinter types: \fR\fIprinter-type-list\fR
177 \fBPrinters: \fR\fIprinter-list\fR
178 \fBFilter type: \fR\fIfilter-type\fR
179 \fBCommand: \fR\fIshell-command\fR
180 \fBOptions: \fR\fItemplate-list\fR
181 .fi
182 .in -2
183 .sp
185 .sp
186 .ne 2
187 .na
188 \fB\fBInput\fR \fBtypes\fR\fR
189 .ad
190 .RS 17n
191 This gives the content types that can be accepted by the filter. The default is
192 \fBany\fR. The document content type must be a member of this list for the
193 initial filter in the sequence.
194 .RE
196 .sp
197 .ne 2
198 .na
199 \fB\fBOutput\fR \fBtypes\fR\fR
200 .ad
201 .RS 17n
202 This gives the content types that the filter can produce from any of the input
203 (content) types. The default is \fBany\fR. The intersection of the output
204 types of this list and the content types acceptable to the printer (from
205 \fBlpadmin\fR \fB-I\fR and \fBlpadmin \fR\fB-T\fR) must be non-null for the
206 last filter in the sequence. For adjacent filters in the sequence, the
207 intersection of output types of one and the input types of the next must be
208 non-null.
209 .RE
211 .sp
212 .ne 2
213 .na
214 \fB\fBPrinter\fR \fBtypes\fR\fR
215 .ad
216 .RS 17n
217 This gives the printer types for which this printer can be used. The \fBLP\fR
218 print service will restrict the use of the filter to these printer types (from
219 \fBlpadmin\fR \fB-T\fR). The default is \fBany\fR.
220 .RE
222 .sp
223 .ne 2
224 .na
225 \fB\fBPrinters\fR\fR
226 .ad
227 .RS 17n
228 This gives the names of the printers for which the filter can be used. The
229 \fBLP\fR print service will restrict the use of the filter to just the printers
230 named. The default is \fBany\fR.
231 .RE
233 .sp
234 .ne 2
235 .na
236 \fB\fBFilter\fR \fBtype\fR\fR
237 .ad
238 .RS 17n
239 This marks the filter as a \fBslow\fR filter or a \fBfast\fR filter. Slow
240 filters are generally those that take a long time to convert their input (that
241 is, minutes or hours). They are run before the job is scheduled for a printer,
242 to keep the printers from being tied up while the filter is running. If a
243 listed printer is on a remote system, the filter type for it must have the
244 value \fBslow\fR. That is, if a client defines a filter, it must be a slow
245 filter. Fast filters are generally those that convert their input quickly (that
246 is, faster than the printer can process the data), or those that must be
247 connected to the printer when run. Fast filters will be given to the interface
248 program to run while connected to the physical printer.
249 .RE
251 .sp
252 .ne 2
253 .na
254 \fB\fBCommand\fR\fR
255 .ad
256 .RS 17n
257 This specifies which program to run to invoke the filter. The full program
258 pathname as well as fixed options must be included in the \fIshell-command\fR;
259 additional options are constructed, based on the characteristics of each print
260 request and on the \fBOptions\fR field. A command must be given for each
261 filter. The command must accept a data stream as standard input and produce the
262 converted data stream on its standard output. This allows filter pipelines to
263 be constructed to convert data not handled by a single filter.
264 .RE
266 .sp
267 .ne 2
268 .na
269 \fB\fBOptions\fR\fR
270 .ad
271 .RS 17n
272 This is a comma-separated list of templates used by the \fBLP\fR print
273 service to construct options to the filter from the characteristics of each
274 print request listed in the table later. The \fB-y\fR and \fB- P\fR arguments
275 to the \fBlp\fR command cause a filter sequence to be built even if there is no
276 need for a conversion of content types.
277 .sp
278 In general, each template is of the following form:
279 .sp
280 \fIkeyword pattern \fR\fB=\fR \fIreplacement\fR
281 .sp
282 The \fIkeyword\fR names the characteristic that the template attempts to map
283 into a filter-specific option; each valid \fIkeyword\fR is listed in the table
284 below.
285 .sp
286 A \fIpattern\fR is one of the following: a literal pattern of one of the forms
287 listed in the table, a single asterisk (\fB*\fR), or a regular expression. If
288 \fIpattern\fR matches the value of the characteristic, the template fits and
289 is used to generate a filter-specific option. The \fIreplacement\fR is what
290 will be used as the option.
291 .sp
292 Regular expressions are the same as those found on the \fBregexp\fR(5) manual
293 page. This includes the \fB\e(\fR\&...\fB\e)\fR and \fB\e\fR\fIn\fR
294 constructions, which can be used to extract portions of the \fIpattern\fR for
295 copying into the \fIreplacement\fR, and the \fB&\fR, which can be used to copy
296 the entire \fIpattern\fR into the \fIreplacement\fR.
297 .sp
298 The \fIreplacement\fR can also contain a \fB*\fR; it too, is replaced with the
299 entire \fIpattern\fR, just like the \fB&\fR of \fBregexp\fR(5).
300 .RE
302 .sp
303 .LP
304 The keywords are:
305 .sp
306 .in +2
307 .nf
308 lp Option Characteristic \fIkeyword\fR Possible \fIpatterns\fR
310 -T Content type INPUT content-type
311 (input)
313 Not applicable Content type OUTPUT content-type
314 (output)
316 not applicable Printer type TERM printer-type
318 -d Printer name PRINTER \fIprinter-name\fR
320 -f, -o cpi= Character pitch CPI integer
322 -f, -o lpi= Line pitch LPI integer
324 -f, -o length= Page length LENGTH integer
326 -f, -o width= Page width WIDTH integer
328 -P Pages to print PAGES page-list
330 -S Character set CHARSET character-set-name
331 Print wheel CHARSET print-wheel-name
333 -f Form name FORM form-name
335 -y Modes MODES mode
337 -n Number of COPIES \fIinteger\fR
338 copies
339 .fi
340 .in -2
341 .sp
343 .SS "Resetting a Filter to Defaults"
344 .sp
345 .LP
346 If the filter named is one originally delivered with the \fBLP\fR print
347 service, the \fB-i\fR option restores the original filter description.
348 .SS "Deleting a Filter"
349 .sp
350 .LP
351 The \fB-x\fR option is used to delete the filter specified in filter-name
352 from the \fBLP\fR filter table.
353 .SS "Listing a Filter Description"
354 .sp
355 .LP
356 The \fB-l\fR option is used to list the description of the filter named in
357 filter-name. If the command is successful, the following message is sent to
358 standard output:
359 .sp
360 .in +2
361 .nf
362 \fBInput types: \fR\fIcontent-type-list\fR
363 \fBOutput types: \fR\fIcontent-type-list\fR
364 \fBPrinter types: \fR\fIprinter-type-list\fR
365 \fBPrinters: \fR\fIprinter-list\fR
366 \fBFilter type: \fR\fIfilter-type\fR
367 \fBCommand: \fR\fIshell-command\fR
368 \fBOptions: \fR\fItemplate-list\fR
369 .fi
370 .in -2
371 .sp
373 .sp
374 .LP
375 If the command fails, an error message is sent to standard error.
376 .SS "Large File Behavior"
377 .sp
378 .LP
379 See \fBlargefile\fR(5) for the description of the behavior of \fBlpfilter\fR
380 when encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
381 .SH EXAMPLES
382 .LP
383 \fBExample 1 \fRPrinting with the landscape option
384 .sp
385 .LP
386 For example, the template
388 .sp
389 .in +2
390 .nf
391 \fBMODES landscape = \fR\fB-l\fR
392 .fi
393 .in -2
394 .sp
396 .sp
397 .LP
398 shows that if a print request is submitted with the \fB-y\fR \fBlandscape\fR
399 option, the filter will be given the option \fB-l\fR.
401 .LP
402 \fBExample 2 \fRSelecting the printer type
403 .sp
404 .LP
405 As another example, the template
407 .sp
408 .in +2
409 .nf
410 \fBTERM * = \fR\fB-T\fR\fB *\fR
411 .fi
412 .in -2
413 .sp
415 .sp
416 .LP
417 shows that the filter will be given the option \fB-T\fR \fIprinter-type\fR for
418 whichever \fIprinter-type\fR is associated with a print request using the
419 filter.
421 .LP
422 \fBExample 3 \fRUsing the keywords table
423 .sp
424 .LP
425 Consider the template
427 .sp
428 .in +2
429 .nf
430 \fBMODES prwidth\e=\e(.*\e) = \fR\fB-w\fR\fB\e1\fR
431 .fi
432 .in -2
433 .sp
435 .sp
436 .LP
437 Suppose a user gives the command
439 .sp
440 .in +2
441 .nf
442 \fBlp -y prwidth=10\fR
443 .fi
444 .in -2
445 .sp
447 .sp
448 .LP
449 From the table above, the \fBLP\fR print service determines that the \fB-y\fR
450 option is handled by a \fBMODES\fR template. The \fBMODES\fR template here
451 works because the pattern prwidth=) matches the prwidth=10 given by the user.
452 The replacement -w1 causes the \fBLP\fR print service to generate the filter
453 option \fB-w10\fR. If necessary, the \fBLP\fR print service will construct a
454 filter pipeline by concatenating several filters to handle the user's file and
455 all the print options. See \fBsh\fR(1) for a description of a pipeline. If the
456 print service constructs a filter pipeline, the \fBINPUT\fR and \fBOUTPUT\fR
457 values used for each filter in the pipeline are the types of input and output
458 for that filter, not for the entire pipeline.
460 .SH EXIT STATUS
461 .sp
462 .LP
463 The following exit values are returned:
464 .sp
465 .ne 2
466 .na
467 \fB\fB0\fR\fR
468 .ad
469 .RS 12n
470 Successful completion.
471 .RE
473 .sp
474 .ne 2
475 .na
476 \fB\fInon-zero\fR\fR
477 .ad
478 .RS 12n
479 An error occurred.
480 .RE
482 .SH SEE ALSO
483 .sp
484 .LP
485 \fBlp\fR(1), \fBsh\fR(1), \fBlpadmin\fR(1M), \fBattributes\fR(5),
486 \fBlargefile\fR(5), \fBregexp\fR(5)
487 .sp
488 .LP
489 \fI\fR
490 .SH NOTES
491 .sp
492 .LP
493 If the \fBlp\fR command specifies more than one document, the filtering chain
494 is determined by the first document. Other documents may have a different
495 format, but they will print correctly only if the filter chain is able to
496 handle their format.