]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - usr.sbin/lpr/lpr/printcap.5
Merge llvm, clang, compiler-rt, libc++, libunwind, lld, lldb and openmp
[FreeBSD/FreeBSD.git] / usr.sbin / lpr / lpr / printcap.5
1 .\" Copyright (c) 1983, 1991, 1993
2 .\"     The Regents of the University of California.  All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\" 3. Neither the name of the University nor the names of its contributors
13 .\"    may be used to endorse or promote products derived from this software
14 .\"    without specific prior written permission.
15 .\"
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .\" SUCH DAMAGE.
27 .\"
28 .\"     @(#)printcap.5  8.2 (Berkeley) 12/11/93
29 .\" $FreeBSD$
30 .\"
31 .Dd October 11, 2000
32 .Dt PRINTCAP 5
33 .Os
34 .Sh NAME
35 .Nm printcap
36 .Nd printer capability data base
37 .Sh SYNOPSIS
38 .Nm
39 .Sh DESCRIPTION
40 The
41 .Nm Printcap
42 function
43 is a simplified version of the
44 .Xr termcap 5
45 data base
46 used to describe line printers.
47 The spooling system accesses the
48 .Nm
49 file every time it is used, allowing dynamic
50 addition and deletion of printers.
51 Each entry in the data base
52 is used to describe one printer.
53 This data base may not be
54 substituted for, as is possible for
55 .Xr termcap 5 ,
56 because it may allow accounting to be bypassed.
57 .Pp
58 The default printer is normally
59 .Em lp ,
60 though the environment variable
61 .Ev PRINTER
62 may be used to override this.
63 Each spooling utility supports an option,
64 .Fl P Ar printer ,
65 to allow explicit naming of a destination printer.
66 .Pp
67 Refer to the
68 .%T "4.3 BSD Line Printer Spooler Manual"
69 for a complete discussion on how to setup the database for a given printer.
70 .Sh CAPABILITIES
71 Refer to
72 .Xr termcap 5
73 for a description of the file layout.
74 .Bl -column Namexxx Typexx "/var/spool/lpdxxxxx"
75 .Sy "Name       Type    Default Description"
76 .It "af str" Ta Dv NULL Ta No "name of accounting file"
77 .It "br num     none    if lp is a tty, set the baud rate"
78 .Xr ( ioctl 2
79 call)
80 .It "cf str" Ta Dv NULL Ta No "cifplot data filter"
81 .It "ct num     120     TCP connection timeout in seconds"
82 .It "df str" Ta Dv NULL Ta No "tex data filter"
83 .Tn ( DVI
84 format)
85 .It "du num     1       UID to run daemon as"
86 .It "ff str" Ta So Li \ef Sc Ta No "string to send for a form feed"
87 .It "fo bool    false   print a form feed when device is opened"
88 .It "gf str" Ta Dv NULL Ta No "graph data filter"
89 .Xr ( plot 3
90 format
91 .It "hl bool    false   print the burst header page last"
92 .It "ic bool    false   driver supports (non standard) ioctl to indent printout"
93 .It "if str" Ta Dv NULL Ta No "name of text filter which does accounting"
94 .It "lf str" Ta Pa /dev/console Ta No "error logging file name"
95 .It "lo str" Ta Pa lock Ta No "name of lock file"
96 .It "lp str" Ta Pa /dev/lp Ta No "device name to open for output, or" Em port Ns @ Ns Em machine No "to open a TCP socket"
97 .It "mc num     0       maximum number of copies which can be requested on"
98 .Xr lpr 1 ,
99 zero = unlimited
100 .It "ms str" Ta Dv NULL Ta No "if lp is a tty, a comma-separated,"
101 .Xr stty 1 Ns -like
102 list describing the tty modes
103 .It "mx num     0       maximum file size (in"
104 .Dv BUFSIZ
105 blocks), zero = unlimited
106 .It "nd str" Ta Dv NULL Ta No "next directory for list of queues (unimplemented)"
107 .It "nf str" Ta Dv NULL Ta No "ditroff data filter (device independent troff)"
108 .It "of str" Ta Dv NULL Ta No "name of output filtering program"
109 .It "pc num     200     price per foot or page in hundredths of cents"
110 .It "pl num     66      page length (in lines)"
111 .It "pw num     132     page width (in characters)"
112 .It "px num     0       page width in pixels (horizontal)"
113 .It "py num     0       page length in pixels (vertical)"
114 .It "rc bool    false   when sending to a remote host, resend copies (see below)"
115 .It "rf str" Ta Dv NULL Ta No "filter for printing"
116 .Tn FORTRAN
117 style text files
118 .It "rg str" Ta Dv NULL Ta No "restricted group. Only members of group allowed access"
119 .It "rm str" Ta Dv NULL Ta No "machine name for remote printer"
120 .It "rp str" Ta Pa lp Ta No "remote printer name argument"
121 .It "rs bool    false   restrict remote users to those with local accounts"
122 .It "rw bool    false   open the printer device for reading and writing"
123 .It "sb bool    false   short banner (one line only)"
124 .It "sc bool    false   suppress multiple copies"
125 .It "sd str" Ta Pa /var/spool/lpd Ta No "spool directory"
126 .It "sf bool    false   suppress form feeds"
127 .It "sh bool    false   suppress printing of burst page header"
128 .It "sr str" Ta Dv NULL Ta No "file name to hold statistics of each datafile as it is received"
129 .It "ss str" Ta Dv NULL Ta No "file name to hold statistics of each datafile as it is sent"
130 .It "st str" Ta Pa status Ta No "status file name"
131 .It "tf str" Ta Dv NULL Ta No "troff data filter (cat phototypesetter)"
132 .It "tr str" Ta Dv NULL Ta No "trailer string to print when queue empties"
133 .It "vf str" Ta Dv NULL Ta No "raster image filter"
134 .El
135 .Pp
136 Each two-letter capability has a human-readable alternate name.
137 .Bl -column "Short form" "Long form"
138 .Sy "Short form Long form"
139 .It "af acct.file"
140 .It "br tty.rate"
141 .It "cf filt.cifplot"
142 .It "ct remote.timeout"
143 .It "df filt.dvi"
144 .It "du daemon.user"
145 .It "ff job.formfeed"
146 .It "fo job.topofform"
147 .It "gf filt.plot"
148 .It "hl banner.last"
149 .It "if filt.input"
150 .It "lf spool.log"
151 .It "lo spool.lock"
152 .It "lp tty.device"
153 .It "mc max.copies"
154 .It "ms tty.mode"
155 .It "mx max.blocks"
156 .It "nf filt.ditroff"
157 .It "of filt.output"
158 .It "pc acct.price"
159 .It "pl page.length"
160 .It "pw page.width"
161 .It "px page.pwidth"
162 .It "py page.plength"
163 .It "rc remote.resend_copies"
164 .It "rf filt.fortran"
165 .It "rg daemon.restrictgrp"
166 .It "rm remote.host"
167 .It "rp remote.queue"
168 .It "rs daemon.restricted"
169 .It "rw tty.rw"
170 .It "sb banner.short"
171 .It "sc job.no_copies"
172 .It "sd spool.dir"
173 .It "sf job.no_formfeed"
174 .It "sh banner.disable"
175 .It "sr stat.recv"
176 .It "ss stat.send"
177 .It "st spool.status"
178 .It "tf filt.troff"
179 .It "tr job.trailer"
180 .It "vf filt.raster"
181 .El
182 .Pp
183 If the local line printer driver supports indentation, the daemon
184 must understand how to invoke it.
185 .Sh FILTERS
186 The
187 .Xr lpd 8
188 daemon creates a pipeline of
189 .Em filters
190 to process files for various printer types.
191 The filters selected depend on the flags passed to
192 .Xr lpr 1 .
193 The pipeline set up is:
194 .Bd -literal -offset indent
195 p       pr | if regular text + pr(1)
196 none    if      regular text
197 c       cf      cifplot
198 d       df      DVI (tex)
199 g       gf      plot(3)
200 n       nf      ditroff
201 f       rf      Fortran
202 t       tf      troff
203 v       vf      raster image
204 .Ed
205 .Pp
206 The
207 .Sy if
208 filter is invoked with arguments:
209 .Bd -ragged -offset indent
210 .Cm if
211 .Op Fl c
212 .Fl w Ns Ar width
213 .Fl l Ns Ar length
214 .Fl i Ns Ar indent
215 .Fl n Ar login
216 .Fl h Ar host acct-file
217 .Ed
218 .Pp
219 The
220 .Fl c
221 flag is passed only if the
222 .Fl l
223 flag (pass control characters literally)
224 is specified to
225 .Xr lpr 1 .
226 The
227 .Ar Width
228 function
229 and
230 .Ar length
231 specify the page width and length
232 (from
233 .Cm pw
234 and
235 .Cm pl
236 respectively) in characters.
237 The
238 .Fl n
239 and
240 .Fl h
241 parameters specify the login name and host name of the owner
242 of the job respectively.
243 The
244 .Ar Acct-file
245 function
246 is passed from the
247 .Cm af
248 .Nm
249 entry.
250 .Pp
251 If no
252 .Cm if
253 is specified,
254 .Cm of
255 is used instead,
256 with the distinction that
257 .Cm of
258 is opened only once,
259 while
260 .Cm if
261 is opened for every individual job.
262 Thus,
263 .Cm if
264 is better suited to performing accounting.
265 The
266 .Cm of
267 is only given the
268 .Ar width
269 and
270 .Ar length
271 flags.
272 .Pp
273 All other filters are called as:
274 .Bd -ragged -offset indent
275 .Nm filter
276 .Fl x Ns Ar width
277 .Fl y Ns Ar length
278 .Fl n Ar login
279 .Fl h Ar host acct-file
280 .Ed
281 .Pp
282 where
283 .Ar width
284 and
285 .Ar length
286 are represented in pixels,
287 specified by the
288 .Cm px
289 and
290 .Cm py
291 entries respectively.
292 .Pp
293 All filters take
294 .Em stdin
295 as the file,
296 .Em stdout
297 as the printer,
298 may log either to
299 .Em stderr
300 or using
301 .Xr syslog 3 ,
302 and must not ignore
303 .Dv SIGINT .
304 .Sh REMOTE PRINTING
305 When printing to a remote printer using
306 .Cm rm ,
307 it is possible to use either
308 .Cm if
309 or
310 .Cm of .
311 If both are specified,
312 .Cm of
313 is ignored.
314 Both filters behave the same except that they are passed
315 different arguments as above.
316 Specifically, the output filter is
317 terminated and restarted for each file transmitted.
318 This is necessary
319 in order to pass the resulting size to the remote
320 .Xr lpd 8 .
321 .Pp
322 If the
323 .Fl p
324 flag was passed to
325 .Xr lpr 1 ,
326 .Xr pr 1
327 is not executed locally, but is requested of the remote
328 .Xr lpd 8 .
329 Any input filtering via
330 .Cm if
331 will therefore happen before
332 .Xr pr 1
333 is executed rather than afterwards.
334 .Pp
335 There are some models of network printers which accept jobs from
336 .Xr lpd 8 ,
337 but they ignore the control file for a job and simply print
338 each data file as it arrives at the printer.
339 One side-effect of this behavior is that the printer will ignore any request
340 for multiple copies as given with the
341 .Fl #
342 flag on the
343 .Xr lpr 1
344 command.
345 The
346 .Cm rc
347 entry will cause
348 .Xr lpd 8
349 to resend each data file for each copy that the user
350 originally requested.
351 Note that the
352 .Cm rc
353 entry should only be specified on hosts which send jobs directly to
354 the printer.
355 .Pp
356 If
357 .Cm lp
358 is specified as
359 .Em port Ns @ Ns Em machine
360 (and
361 .Cm rm
362 is not in use), print data will be sent directly to the given
363 .Em port
364 on the given
365 .Em machine .
366 .Sh TRANSFER STATISTICS
367 When a print job is transferred to a remote machine (which might be
368 another unix box, or may be a network printer), it may be useful
369 to keep statistics on each transfer.
370 The
371 .Cm sr
372 and
373 .Cm ss
374 options indicate filenames that lpd should use to store such
375 statistics.
376 A statistics line is written for each datafile of a
377 job as the file is successfully transferred.
378 The format of the
379 line is the same for both the sending and receiving side of a
380 transfer.
381 .Pp
382 Statistics on datafiles being received would be used on a print
383 server, if you are interested in network performance between a
384 variety of machines which are sending jobs to that print server.
385 The print server could collect statistics on the speed of each
386 print job as it arrived on the server.
387 .Pp
388 Statistics on datafiles being sent might be used as a minimal
389 accounting record, when you want to know who sent which jobs to a
390 remote printer, when they were sent, and how large (in bytes) the
391 files were.
392 This will not give include any idea of how many pages
393 were printed, because there is no standard way to get that information
394 back from a remote (network) printer in this case.
395 .Sh LOGGING
396 Error messages generated by the line printer programs themselves
397 (that is, the
398 .Xr lpd 8
399 and related programs)
400 are logged by
401 .Xr syslog 3
402 using the
403 .Dv LPR
404 facility.
405 Messages printed on
406 .Em stderr
407 of one of the filters
408 are sent to the corresponding
409 .Cm lf
410 file.
411 The filters may, of course, use
412 .Xr syslogd 8
413 themselves.
414 .Pp
415 Error messages sent to the console have a carriage return and a line
416 feed appended to them, rather than just a line feed.
417 .Sh SEE ALSO
418 .Xr lpq 1 ,
419 .Xr lpr 1 ,
420 .Xr lprm 1 ,
421 .Xr hosts.lpd 5 ,
422 .Xr termcap 5 ,
423 .Xr chkprintcap 8 ,
424 .Xr lpc 8 ,
425 .Xr lpd 8 ,
426 .Xr pac 8
427 .Rs
428 .%T "4.3 BSD Line Printer Spooler Manual"
429 .Re
430 .Sh HISTORY
431 The
432 .Nm
433 file format appeared in
434 .Bx 4.2 .