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$
  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
  44 The
  45 .Nm Printcap
  46 function
  47 is a simplified version of the
  48 .Xr termcap 5
  49 data base
  50 used to describe line printers.
  51 The spooling system accesses the
  52 .Nm
  53 file every time it is used, allowing dynamic
  54 addition and deletion of printers.
  55 Each entry in the data base
  56 is used to describe one printer.
  57 This data base may not be
  58 substituted for, as is possible for
  59 .Xr termcap 5 ,
  60 because it may allow accounting to be bypassed.
  61 .Pp
  62 The default printer is normally
  63 .Em lp ,
  64 though the environment variable
  65 .Ev PRINTER
  66 may be used to override this.
  67 Each spooling utility supports an option,
  68 .Fl P Ar printer ,
  69 to allow explicit naming of a destination printer.
  70 .Pp
  71 Refer to the
  72 .%T "4.3 BSD Line Printer Spooler Manual"
  73 for a complete discussion on how to setup the database for a given printer.
  74 .Sh CAPABILITIES
  75 Refer to
  76 .Xr termcap 5
  77 for 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
  83 call)
  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
  88 format)
  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
  93 format
  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 ,
 102 zero = unlimited
 103 .It "ms str" Ta Dv NULL Ta No "if lp is a tty, a comma-separated,"
 104 .Xr stty 1 Ns -like
 105 list describing the tty modes
 106 .It "mx num     0       maximum file size (in"
 107 .Dv BUFSIZ
 108 blocks), 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
 120 style 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
 139 Each 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
 186 If the local line printer driver supports indentation, the daemon
 187 must understand how to invoke it.
 188 .Sh FILTERS
 189 The
 190 .Xr lpd 8
 191 daemon creates a pipeline of
 192 .Em filters
 193 to process files for various printer types.
 194 The filters selected depend on the flags passed to
 195 .Xr lpr 1 .
 196 The pipeline set up is:
 197 .Bd -literal -offset indent
 198 p       pr | if regular text + pr(1)
 199 none    if      regular text
 200 c       cf      cifplot
 201 d       df      DVI (tex)
 202 g       gf      plot(3)
 203 n       nf      ditroff
 204 f       rf      Fortran
 205 t       tf      troff
 206 v       vf      raster image
 207 .Ed
 208 .Pp
 209 The
 210 .Sy if
 211 filter 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
 222 The
 223 .Fl c
 224 flag is passed only if the
 225 .Fl l
 226 flag (pass control characters literally)
 227 is specified to
 228 .Xr lpr 1 .
 229 The
 230 .Ar Width
 231 function
 232 and
 233 .Ar length
 234 specify the page width and length
 235 (from
 236 .Cm pw
 237 and
 238 .Cm pl
 239 respectively) in characters.
 240 The
 241 .Fl n
 242 and
 243 .Fl h
 244 parameters specify the login name and host name of the owner
 245 of the job respectively.
 246 The
 247 .Ar Acct-file
 248 function
 249 is passed from the
 250 .Cm af
 251 .Nm
 252 entry.
 253 .Pp
 254 If no
 255 .Cm if
 256 is specified,
 257 .Cm of
 258 is used instead,
 259 with the distinction that
 260 .Cm of
 261 is opened only once,
 262 while
 263 .Cm if
 264 is opened for every individual job.
 265 Thus,
 266 .Cm if
 267 is better suited to performing accounting.
 268 The
 269 .Cm of
 270 is only given the
 271 .Ar width
 272 and
 273 .Ar length
 274 flags.
 275 .Pp
 276 All 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
 285 where
 286 .Ar width
 287 and
 288 .Ar length
 289 are represented in pixels,
 290 specified by the
 291 .Cm px
 292 and
 293 .Cm py
 294 entries respectively.
 295 .Pp
 296 All filters take
 297 .Em stdin
 298 as the file,
 299 .Em stdout
 300 as the printer,
 301 may log either to
 302 .Em stderr
 303 or using
 304 .Xr syslog 3 ,
 305 and must not ignore
 306 .Dv SIGINT .
 307 .Sh REMOTE PRINTING
 308 When printing to a remote printer using
 309 .Cm rm ,
 310 it is possible to use either
 311 .Cm if
 312 or
 313 .Cm of .
 314 If both are specified,
 315 .Cm of
 316 is ignored.
 317 Both filters behave the same except that they are passed
 318 different arguments as above.
 319 Specifically, the output filter is
 320 terminated and restarted for each file transmitted.
 321 This is necessary
 322 in order to pass the resulting size to the remote
 323 .Xr lpd 8 .
 324 .Pp
 325 If the
 326 .Fl p
 327 flag was passed to
 328 .Xr lpr 1 ,
 329 .Xr pr 1
 330 is not executed locally, but is requested of the remote
 331 .Xr lpd 8 .
 332 Any input filtering via
 333 .Cm if
 334 will therefore happen before
 335 .Xr pr 1
 336 is executed rather than afterwards.
 337 .Pp
 338 There are some models of network printers which accept jobs from
 339 .Xr lpd 8 ,
 340 but they ignore the control file for a job and simply print
 341 each data file as it arrives at the printer.
 342 One side-effect of this behavior is that the printer will ignore any request
 343 for multiple copies as given with the
 344 .Fl #
 345 flag on the
 346 .Xr lpr 1
 347 command.
 348 The
 349 .Cm rc
 350 entry will cause
 351 .Xr lpd 8
 352 to resend each data file for each copy that the user
 353 originally requested.
 354 Note that the
 355 .Cm rc
 356 entry should only be specified on hosts which send jobs directly to
 357 the printer.
 358 .Pp
 359 If
 360 .Cm lp
 361 is specified as
 362 .Em port Ns @ Ns Em machine
 363 (and
 364 .Cm rm
 365 is not in use), print data will be sent directly to the given
 366 .Em port
 367 on the given
 368 .Em machine .
 369 .Sh TRANSFER STATISTICS
 370 When a print job is transfered to a remote machine (which might be
 371 another unix box, or may be a network printer), it may be useful
 372 to keep statistics on each transfer.
 373 The
 374 .Cm sr
 375 and
 376 .Cm ss
 377 options indicate filenames that lpd should use to store such
 378 statistics.
 379 A statistics line is written for each datafile of a
 380 job as the file is successfully transferred.
 381 The format of the
 382 line is the same for both the sending and receiving side of a
 383 transfer.
 384 .Pp
 385 Statistics on datafiles being received would be used on a print
 386 server, if you are interested in network performance between a
 387 variety of machines which are sending jobs to that print server.
 388 The print server could collect statistics on the speed of each
 389 print job as it arrived on the server.
 390 .Pp
 391 Statistics on datafiles being sent might be used as a minimal
 392 accounting record, when you want to know who sent which jobs to a
 393 remote printer, when they were sent, and how large (in bytes) the
 394 files were.
 395 This will not give include any idea of how many pages
 396 were printed, because there is no standard way to get that information
 397 back from a remote (network) printer in this case.
 398 .Sh LOGGING
 399 Error messages generated by the line printer programs themselves
 400 (that is, the
 401 .Xr lpd 8
 402 and related programs)
 403 are logged by
 404 .Xr syslog 3
 405 using the
 406 .Dv LPR
 407 facility.
 408 Messages printed on
 409 .Em stderr
 410 of one of the filters
 411 are sent to the corresponding
 412 .Cm lf
 413 file.
 414 The filters may, of course, use
 415 .Xr syslogd 8
 416 themselves.
 417 .Pp
 418 Error messages sent to the console have a carriage return and a line
 419 feed 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
 434 The
 435 .Nm
 436 file format appeared in
 437 .Bx 4.2 .