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. 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: src/usr.sbin/lpr/lpr/printcap.5,v 1.16.2.11 2002/06/19 01:57:18 gad Exp $
  34 .\" $DragonFly: src/usr.sbin/lpr/lpr/printcap.5,v 1.3 2007/05/13 22:25:42 swildner Exp $
  35 .\"
  36 .Dd October 11, 2000
  37 .Dt PRINTCAP 5
  38 .Os
  39 .Sh NAME
  40 .Nm printcap
  41 .Nd printer capability data base
  42 .Sh SYNOPSIS
  43 .Nm
  44 .Sh DESCRIPTION
  45 The
  46 .Nm Printcap
  47 function
  48 is a simplified version of the
  49 .Xr termcap 5
  50 data base
  51 used to describe line printers.  The spooling system accesses the
  52 .Nm
  53 file every time it is used, allowing dynamic
  54 addition and deletion of printers.  Each entry in the data base
  55 is used to describe one printer.  This data base may not be
  56 substituted for, as is possible for
  57 .Xr termcap 5 ,
  58 because it may allow accounting to be bypassed.
  59 .Pp
  60 The default printer is normally
  61 .Em lp ,
  62 though the environment variable
  63 .Ev PRINTER
  64 may be used to override this.  Each spooling utility supports an option,
  65 .Fl P Ar printer ,
  66 to allow explicit naming of a destination printer.
  67 .Pp
  68 Refer to the
  69 .%T "4.3 BSD Line Printer Spooler Manual"
  70 for a complete discussion on how to setup the database for a given printer.
  71 .Sh CAPABILITIES
  72 Refer to
  73 .Xr termcap 5
  74 for a description of the file layout.
  75 .Bl -column Namexxx Typexx "/var/spool/lpdxxxxx"
  76 .Sy "Name       Type    Default Description
  77 .It "af str" Ta Dv NULL Ta No "name of accounting file"
  78 .It "br num     none    if lp is a tty, set the baud rate"
  79 .Xr ( ioctl 2
  80 call)
  81 .It "cf str" Ta Dv NULL Ta No "cifplot data filter"
  82 .It "ct num     120     TCP connection timeout in seconds"
  83 .It "df str" Ta Dv NULL Ta No "tex data filter"
  84 .Tn ( DVI
  85 format)
  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"
  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     1000    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.  Both filters behave the same except that they are passed
 314 different arguments as above.  Specifically, the output filter is
 315 terminated and restarted for each file transmitted.  This is necessary
 316 in order to pass the resulting size to the remote
 317 .Xr lpd 8 .
 318 .Pp
 319 If the
 320 .Fl p
 321 flag was passed to
 322 .Xr lpr 1 ,
 323 .Xr pr 1
 324 is not executed locally, but is requested of the remote
 325 .Xr lpd 8 .
 326 Any input filtering via
 327 .Cm if
 328 will therefore happen before
 329 .Xr pr 1
 330 is executed rather than afterwards.
 331 .Pp
 332 There are some models of network printers which accept jobs from
 333 .Xr lpd 8 ,
 334 but they ignore the control file for a job and simply print
 335 each data file as it arrives at the printer.
 336 One side-effect of this behavior is that the printer will ignore any request
 337 for multiple copies as given with the
 338 .Fl #
 339 flag on the
 340 .Xr lpr 1
 341 command.
 342 The
 343 .Cm rc
 344 entry will cause
 345 .Xr lpd 8
 346 to resend each data file for each copy that the user
 347 originally requested.
 348 Note that the
 349 .Cm rc
 350 entry should only be specified on hosts which send jobs directly to
 351 the printer.
 352 .Pp
 353 If
 354 .Cm lp
 355 is specified as
 356 .Em port Ns No @ Ns Em machine
 357 (and
 358 .Cm rm
 359 is not in use), printing will be send directly to the given
 360 .Em port
 361 on the given
 362 .Em machine .
 363 .Sh TRANSFER STATISTICS
 364 When a print job is transferred to a remote machine (which might be
 365 another unix box, or may be a network printer), it may be useful
 366 to keep statistics on each transfer.  The
 367 .Cm sr
 368 and
 369 .Cm ss
 370 options indicate filenames that lpd should use to store such
 371 statistics.  A statistics line is written for each datafile of a
 372 job as the file is successfully transferred.  The format of the
 373 line is the same for both the sending and receiving side of a
 374 transfer.
 375 .Pp
 376 Statistics on datafiles being received would be used on a print
 377 server, if you are interested in network performance between a
 378 variety of machines which are sending jobs to that print server.
 379 The print server could collect statistics on the speed of each
 380 print job as it arrived on the server.
 381 .Pp
 382 Statistics on datafiles being sent might be used as a minimal
 383 accounting record, when you want to know who sent which jobs to a
 384 remote printer, when they were sent, and how large (in bytes) the
 385 files were.  This will not give include any idea of how many pages
 386 were printed, because there is no standard way to get that information
 387 back from a remote (network) printer in this case.
 388 .Sh LOGGING
 389 Error messages generated by the line printer programs themselves
 390 (that is, the
 391 .Xr lpd 8
 392 and related programs)
 393 are logged by
 394 .Xr syslog 3
 395 using the
 396 .Dv LPR
 397 facility.
 398 Messages printed on
 399 .Em stderr
 400 of one of the filters
 401 are sent to the corresponding
 402 .Cm lf
 403 file.
 404 The filters may, of course, use
 405 .Xr syslogd 8
 406 themselves.
 407 .Pp
 408 Error messages sent to the console have a carriage return and a line
 409 feed appended to them, rather than just a line feed.
 410 .Sh SEE ALSO
 411 .Xr lpq 1 ,
 412 .Xr lpr 1 ,
 413 .Xr lprm 1 ,
 414 .Xr hosts.lpd 5 ,
 415 .Xr termcap 5 ,
 416 .Xr chkprintcap 8 ,
 417 .Xr lpc 8 ,
 418 .Xr lpd 8 ,
 419 .Xr pac 8
 420 .Rs
 421 .%T "4.3 BSD Line Printer Spooler Manual"
 422 .Re
 423 .Sh HISTORY
 424 The
 425 .Nm
 426 file format appeared in
 427 .Bx 4.2 .