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