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