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