| blob | c57beb1a1c9e85c451ad0d5ced4a7a69256ddf6c |
1 .\" $NetBSD: printcap.5,v 1.24 2008/07/21 07:52:10 wiz Exp $
2 .\"
3 .\" Copyright (c) 1983, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)printcap.5 8.2 (Berkeley) 12/11/93
31 .\"
32 .Dd July 18, 2008
33 .Dt PRINTCAP 5
34 .Os
35 .Sh NAME
36 .Nm printcap
37 .Nd printer capability data base
38 .Sh SYNOPSIS
39 .Nm printcap
40 .Sh DESCRIPTION
41 The
42 .Nm
43 data base is a simplified version of the
44 .Xr termcap 5
45 data base used to describe line printers.
46 The spooling system accesses the
47 .Nm printcap
48 file every time it is used, allowing dynamic
49 addition and deletion of printers.
50 Each entry in the data base is used to describe one printer.
51 This data base may not be substituted for, as is possible for
52 .Xr termcap 5 ,
53 because it may allow accounting to be bypassed.
54 .Pp
55 The default printer is normally
56 .Em lp ,
57 though the environment variable
58 .Ev PRINTER
59 may be used to override this.
60 Each spooling utility supports an option,
61 .Fl P Ar printer ,
62 to allow explicit naming of a destination printer.
63 .Pp
64 Refer to the
65 .%T "4.3 BSD Line Printer Spooler Manual"
66 for a complete discussion on how to set up the database for a given printer.
67 .Sh CAPABILITIES
68 Refer to
69 .Xr termcap 5
70 for a description of the file layout.
71 .Bl -column Name Type "/var/spool/output/lpd"
72 .It Sy Name Type Default Description
73 .It "af str" Ta Dv NULL Ta No "name of accounting file"
74 .It "br num none if lp is a tty, set the baud rate"
75 .Pf ( Xr ioctl 2
76 call)
77 .It "cf str" Ta Dv NULL Ta No "cifplot data filter"
78 .It "df str" Ta Dv NULL Ta No "tex data filter"
79 .Pf ( Tn DVI
80 format)
81 .It "fc num 0 if lp is a tty, clear flag bits"
82 .Pq Pa sgtty.h
83 .It "ff str" Ta So Li \ef Sc Ta No "string to send for a form feed"
84 .It "fo bool false print a form feed when device is opened"
85 .It "fs num 0 like `fc' but set bits"
86 .It "gf str" Ta Dv NULL Ta No "graph data filter"
87 .Pf ( Xr plot 3
88 format
89 .It "hl bool false print the burst header page last"
90 .It "ic bool false driver supports (non standard) ioctl to indent printout"
91 .It "if str" Ta Dv NULL Ta No "name of text filter which does accounting"
92 .It "lf str" Ta Pa /dev/console Ta No "error logging file name"
93 .It "lo str" Ta Pa lock Ta No "name of lock file"
94 .It "lp str" Ta Pa /dev/lp Ta No "device name to open for output to local \
95 printer, or port@host for remote printer/printer on print server"
96 .It "ms str" Ta Dv NULL Ta No "list of terminal modes to set or clear"
97 .It "mx num 1000 maximum file size (in"
98 .Dv BUFSIZ
99 blocks), zero = unlimited
100 .It "nd str" Ta Dv NULL Ta No "next directory for list of queues (unimplemented)"
101 .It "nf str" Ta Dv NULL Ta No "ditroff data filter (device independent troff)"
102 .It "of str" Ta Dv NULL Ta No "name of output filtering program"
103 .It "pc num 200 price per foot or page in hundredths of cents"
104 .It "pf str" Ta Dv NULL Ta No "filter for printing"
105 .Tn PostScript
106 files
107 .It "pl num 66 page length (in lines)"
108 .It "pw num 132 page width (in characters)"
109 .It "px num 0 page width in pixels (horizontal)"
110 .It "py num 0 page length in pixels (vertical)"
111 .It "rf str" Ta Dv NULL Ta No "filter for printing"
112 .Tn FORTRAN
113 style text files
114 .It "rg str" Ta Dv NULL Ta No "restricted group. Only members of group allowed access"
115 .It "rm str" Ta Dv NULL Ta No "machine name for remote printer or port@host \
116 for a remote printer on a port other than the standard port."
117 .Po
118 also suppress the burst page, see
119 .Sx NOTES
120 .Pc
121 .It "rp str ``lp'' remote printer name argument"
122 .It "rs bool false restrict remote users to those with local accounts"
123 .It "rw bool false open the printer device for reading and writing"
124 .It "sb bool false short banner (one line only)"
125 .It "sc bool false suppress multiple copies"
126 .It "sd str" Ta Pa /var/spool/output/lpd Ta No "spool directory"
127 .It "sf bool false suppress form feeds"
128 .It "sh bool false suppress printing of burst page header"
129 .Po
130 local only, see
131 .Sx NOTES
132 .Pc
133 .It "st str" Ta Pa status Ta No "status file name"
134 .It "tf str" Ta Dv NULL Ta No "troff data filter (cat phototypesetter)"
135 .It "tr str" Ta Dv NULL Ta No "trailer string to print when queue empties"
136 .It "vf str" Ta Dv NULL Ta No "raster image filter"
137 .It "xc num 0 if lp is a tty, clear local mode bits"
138 .Pq Xr tty 4
139 .It "xs num 0 like `xc' but set bits"
140 .El
141 .Pp
142 If the local line printer driver supports indentation, the daemon
143 must understand how to invoke it.
144 .Sh FILTERS
145 If a printer is specified via
146 .Sy lp
147 (either local or remote),
148 the
149 .Xr lpd 8
150 daemon creates a pipeline of
151 .Em filters
152 to process files for various printer types.
153 The pipeline is not set up for remote printers specified via
154 .Sy rm
155 unless the local host is the same as the remote printer host
156 given.
157 The filters selected depend on the flags passed to
158 .Xr lpr 1 .
159 The pipeline set up is:
160 .Bd -literal -offset indent
161 p pr | if regular text + pr(1)
162 none if regular text
163 c cf cifplot
164 d df DVI (tex)
165 g gf plot(3)
166 n nf ditroff
167 o pf PostScript
168 f rf Fortran
169 t tf troff
170 v vf raster image
171 .Ed
172 .Pp
173 The
174 .Sy if
175 filter is invoked with arguments:
176 .Bd -filled -offset indent
177 .Cm if
178 .Op Fl c
179 .Fl w Ns Ar width
180 .Fl l Ns Ar length
181 .Fl i Ns Ar indent
182 .Fl n Ar login
183 .Op Fl j Ar jobname
184 .Fl h Ar host acct-file
185 .Ed
186 .Pp
187 The
188 .Fl c
189 flag is passed only if the
190 .Fl l
191 flag (pass control characters literally)
192 is specified to
193 .Xr lpr 1 .
194 The
195 .Ar width
196 and
197 .Ar length
198 specify the page width and length
199 (from
200 .Cm pw
201 and
202 .Cm pl
203 respectively) in characters.
204 The
205 .Fl n
206 and
207 .Fl h
208 parameters specify the login name and host name of the owner
209 of the job respectively.
210 The
211 .Fl j
212 parameter is optional and specifies the name of the print
213 job if available.
214 The
215 .Ar acct-file
216 option is passed from the
217 .Cm af
218 .Nm printcap
219 entry.
220 .Pp
221 If no
222 .Cm if
223 is specified,
224 .Cm of
225 is used instead,
226 with the distinction that
227 .Cm of
228 is opened only once,
229 while
230 .Cm if
231 is opened for every individual job.
232 Thus,
233 .Cm if
234 is better suited to performing accounting.
235 The
236 .Cm of
237 is only given the
238 .Ar width
239 and
240 .Ar length
241 flags.
242 .Pp
243 All other filters are called as:
244 .Bd -filled -offset indent
245 .Nm filter
246 .Fl x Ns Ar width
247 .Fl y Ns Ar length
248 .Fl n Ar login
249 .Op Fl j Ar jobname
250 .Fl h Ar host acct-file
251 .Ed
252 .Pp
253 where
254 .Ar width
255 and
256 .Ar length
257 are represented in pixels,
258 specified by the
259 .Cm px
260 and
261 .Cm py
262 entries respectively.
263 .Pp
264 All filters take
265 .Em stdin
266 as the file,
267 .Em stdout
268 as the printer,
269 may log either to
270 .Em stderr
271 or using
272 .Xr syslog 3 ,
273 and must not ignore
274 .Dv SIGINT .
275 .Pp
276 Filters can communicate errors to lpd by their exit code and by modifying
277 the mode of the spool lock file as follows:
278 .Bl -tag -width Exit-code -compact -offset indent
279 .It Sy Exit code
280 .Sy Description
281 .It 0
282 Success.
283 .It 1
284 An attempt is made to reprint the job and mail is sent if it fails.
285 .It 2
286 .Xr lpd 8
287 silently discards the job.
288 .It n
289 .Xr lpd 8
290 discards the job and mail is sent.
291 .El
292 .Bl -tag -width lockxmode -compact -offset indent
293 .It Sy lock code
294 .Sy Description
295 .It u+x
296 Stop printing and leave queue disabled (S_IXUSR).
297 .It o+x
298 Rebuild the queue (S_IXOTH).
299 .El
300 .Sh LOGGING
301 Error messages generated by the line printer programs themselves
302 (that is, the lp* programs) are logged by
303 .Xr syslog 3
304 using the
305 .Dv LPR
306 facility.
307 Messages printed on
308 .Em stderr
309 of one of the filters are sent to the corresponding
310 .Cm lf
311 file.
312 The filters may, of course, use
313 .Xr syslog 3
314 themselves.
315 .Pp
316 Error messages sent to the console have a carriage return and a line
317 feed appended to them, rather than just a line feed.
318 .Sh SEE ALSO
319 .Xr lpq 1 ,
320 .Xr lpr 1 ,
321 .Xr lprm 1 ,
322 .Xr termcap 5 ,
323 .Xr lpc 8 ,
324 .Xr lpd 8 ,
325 .Xr pac 8
326 .Rs
327 .%T "4.3 BSD Line Printer Spooler Manual"
328 .Re
329 .Sh NOTES
330 The
331 .Sy sh
332 flag is a function of the spooler with the locally attached printer,
333 and so has no effect when used with
334 .Sy rm .
335 .Nx
336 never adds a burst page when used as a remote spooler.
337 To suppress the burst page for other systems or dedicated devices,
338 refer to the documentation for those systems or devices.
339 .Sh HISTORY
340 The
341 .Nm
342 file format appeared in
343 .Bx 4.2 .