1 .HTML "A Guide to the Lp Printer Spooler
11 is a collection of programs used to provide an easy-to-use
12 interface for printing a variety of document types on a variety
15 is the glue that connects various document language
16 translators and printer communication programs together so that
17 the users may have a consistent view of printers.
19 is shell script, which can be easily modified.
21 specify options to get sensible output in most cases.
24 so that others may make additions and changes.
31 is used to format and print data on a variety of output devices.
34 was rooted in the inability of other printer spoolers to do simple
35 tasks without a great deal of user specification of options.
38 was written, there were several printer
39 languages, such as ImPress and PostScript, and
40 an internally developed printer that would accept
43 Now, all our printers take PostScript,
44 but printers that use HPCL and HPGL abound and
45 support for those printers may be added easily.
46 A great deal of what underlies
52 The important features of this system are that most of the programs
53 are easily modified shell scripts and the user need not
54 learn to use the large amount of underlying software developed by others.
56 runs under Plan 9 and several flavors of
58 This document deals with
60 as it relates to Plan 9.
62 was developed using both Datakit and Ethernet to transport data between machines.
63 Now only the Ethernet transport mechanism remains.
65 Text, graphics, and formatted text files are appropriately processed and
66 placed into a spool directory from which they are taken to be printed by a daemon process.
67 Additional functions include checking the status of a printer queue
68 and removing jobs from the printer queue.
70 All the shell scripts (see
74 reside in the spool directory
78 command itself, which resides in
82 that are not shell scripts can most often be found
84 .CW /$cputype/bin/aux .
85 The directory where all the
87 scripts reside is defined within
91 In the remainder of this document, file names will be specified
92 with this shell variable as their root.
97 requires an output device to be specified
98 before it will process input.
99 This can be done in any of three ways described here.
103 may contain the name of a default output device.
104 This may not be practical for environments where
105 there are many printers.
107 The user's environment variable
109 may be set to the name of the device to be used.
110 This is often a more practical solution when there are several printers
123 as the device to which output should be directed, overriding the
124 previous two specifications.
131 a list of printers and other information in the
133 file is printed, as shown in Figure 1.
134 Quote the question mark to prevent it from being
135 interpreted by the shell language as a metacharacter.
140 device location host class
141 fn 2C-501 helix post/2+600dpi+duplex
142 pcclone - - post+nohead
143 peacock 2C-501 cetus post/2+300dpi+nohead+color
144 ps83 st8_fl3 rice post+300dpi+reverse
145 psu 2C-501 cetus post/2+1200dpi
152 .I "Figure 1. Sample listing of installed printers"
159 command to figure out what type of input it is receiving.
160 This is done within the
162 process which is discussed later in this paper in the
163 .B "Process directory"
165 To select a specific input processor the
166 \f(CW-p\fP\fIprocess\fP
169 is one of the shell scripts in the
174 output can be printed, in this case, on printer
178 % troff -ms lp.ms | lp -dfn
181 A file can be converted to PostScript using the pseudo-printer
184 % troff -ms lp.ms | lp -dstdout > lp.ps
186 LaTeX (and analogously TeX)
187 documents are printed in two steps:
198 produces a `.dvi' file and
199 does not permit the use of a pipe
200 connection to the standard input of
202 To look at the status and queue of a device, use
209 %%[ status: busy; source: lpd ]%%
213 rice29436.1 pg 0 17454
214 slocum17565.1 ches 1 49995
217 This command can print the status and queue of the local
219 Administrators should be advised that working in an environment where the
221 spool directory is shared among the local and remote hosts,
222 no spooling should be done on the local hosts.
223 The format of the status and queue printout is up to the administrator.
224 The job started above can be killed with
227 $ lp -dpsu -k rice29436.1
228 rice29436.1 removed from psu queue on cetus
233 There are options available to modify the way in which a job is handled.
236 programs to convert the option settings so they may be used by each of the
237 different translation and interface programs.
238 Not all options are applicable to all printer environments.
239 Table 1 lists the standard
241 options, the shell variable settings, and description of the options.
250 lfCWp-2 | lfCWp-2 cfCWp-2 cfCWp-2 | lp-2w(3i).
252 option shell variable action
253 \^ name default set \^
255 -D DEBUG N 1 turn on debugging mode.
257 -H NOHEADER N 1 suppress header page.
259 -L LAND N 1 make long page dimension horizontal.
261 -M \fImach\fP LPMACHID N \fImach\fP set the source machine name.
263 -Q QONLY N 1 do not execute daemon; for debugging.
265 -c \fIn\fP COPIES N \fIn\fP number of copies to be printed.
267 -d \fIprinter\fP LPDEST U \fIprinter\fP set job destination; override other settings.
269 -f \fIfont.pt\fP FONT N \fIfont\fP set font style and point size for printing.
272 -i \fIn\fP IBIN N \fIn\fP T{
273 select input paper tray options.
274 The argument given is dependent on the printer type.
275 A number can be given to select a particular tray and/or
279 may be used to get single or double sided output, where
281 Multiple options should be separated by commas.
285 take non-option arguments as job numbers to be removed from queue.
288 -l \fIn\fP LINES N \fIn\fP T{
289 for printed data, the number of lines per logical page.
292 -m \fIf\fP MAG N \fIf\fP T{
293 magnify the image by a factor \fIf\fP.
294 The factor should be a positive real number.
297 -n \fIn\fP NPAG N \fIn\fP T{
298 put \fIn\fP logical pages on a single physical page.
299 A simple algorithm is used to pack the pages.
302 -o \fIlist\fP OLIST N \fIlist\fP T{
303 print only those pages specified in the list.
304 The list may be a sequence of numbers or ranges separated by commas.
305 A range is a pair of numbers separated by a hyphen.
308 -p \fIproc\fP LPPROC L \fIproc\fP T{
309 use the preprocessor \fIproc\fP instead of the preprocessor given
312 file for this printer.
316 print the status and queue.
322 flag, changing whether or not page reversal should occur in preprocessing.
323 Page reversal is needed if a printer delivers pages face up.
331 If a document has already been processed this flag has no effect.
334 -u \fIuser\fP LPUSERID U \fIuser\fP T{
335 change the user id that appears on the cover page.
338 -x \fIoffset\fP XOFF N \fIoffset\fP T{
339 move the image \fIoffset\fP inches to the right.
340 A negative \fIoffset\fP will move the image to the left.
341 The \fIoffset\fP may be any reasonable real number.
344 -y \fIoffset\fP YOFF N \fIoffset\fP T{
347 except a positive offset will move the image down.
355 default setting definition
356 N set to the null string (`') initially in \fIlp\fP.
357 L set from printer entry in \f(CW\\s-\\n(XPdevices\\s+\\n(XP\fP file.
358 U set from the user's environment.
363 .I "Table 1. Lp Option List"
373 file is found in the spool directory.
374 Each line in the file is composed of 12 fields, separated
375 by tabs or spaces, that describe the attributes
376 of the printer and how it should be serviced.
379 command, a shell variable is set for each attribute;
380 the following list describes them:
381 .IP "\f(CW\s-\n(XPLPDEST\s+\n(XP\fP " 12
382 is the name of the device as given to
387 or as specified by the shell environment variable
391 .CW $LPLIB/defdevice .
392 This name is used in creating directories and log files that are associated with
393 the printers operation.
394 .IP "\f(CW\s-\n(XPLOC\s+\n(XP\fP "
395 just describes where the printer is physically located.
396 .IP "\f(CW\s-\n(XPDEST_HOST\s+\n(XP\fP "
397 is the host from which the files are printed.
398 Files may be spooled on other machines before being transferred to the
400 .IP "\f(CW\s-\n(XPOUT_DEV\s+\n(XP\fP "
401 is the physical device name or network address needed by the printer daemon
402 to connect to the printer.
403 This field depends on the requirements of the daemon and may contain a `\(en'
405 .IP "\f(CW\s-\n(XPSPEED\s+\n(XP\fP "
406 is the baud rate setting for the port.
407 This field depends on the requirements of the daemon and may contain a `\(en'
409 .IP "\f(CW\s-\n(XPLPCLASS\s+\n(XP\fP "
410 is used to encode minor printer differences.
413 is used by some of the preprocessors
414 to reverse the order the pages are printed to accommodate different output
415 trays (either face up or face down).
418 is used to suppress the header page.
419 This is used for special and color printers.
422 is used to coax double sided output from duplex printers.
423 .IP "\f(CW\s-\n(XPLPPROC\s+\n(XP\fP "
424 is the command from the
426 directory to be used to convert input to a format
427 that will be accepted by the device.
428 The preprocessor is invoked by the spooler.
429 .IP "\f(CW\s-\n(XPSPOOLER\s+\n(XP\fP "
430 is the command from the
432 directory which will select files using the
434 command and invoke the
436 command, putting its output
437 into the remote spool directory.
438 The output is sent directly to the spool directory on the
439 destination machine to avoid conflicts when client and
440 server machines share spool directories.
441 .IP "\f(CW\s-\n(XPSTAT\s+\n(XP\fP "
442 is the command from the
444 directory that prints the status of the device and the list of jobs
445 waiting on the queue for the device.
446 The status information depends on what is available from the printer
447 and interface software.
448 The queue information should be changed to show information
449 useful in tracking down problems.
452 command is used to show the jobs in the order
453 in which they will be printed.
454 .IP "\f(CW\s-\n(XPKILL\s+\n(XP\fP "
455 is the command from the
457 that removes jobs from the queue.
458 The jobs to be removed are given as arguments to the
461 When possible, it should also abort the currently running job
462 if it has to be killed.
463 .IP "\f(CW\s-\n(XPDAEMON\s+\n(XP\fP "
464 is the command from the
466 that is meant to run asynchronously to remove
468 Jobs may either be passed on to another host or sent to the
471 always tries to start a daemon process when one is specified.
472 .IP "\f(CW\s-\n(XPSCHED\s+\n(XP\fP "
473 is the command from the
475 that is used to present the job names to the
476 daemon and stat programs
477 in some order, e.g., first-in-first-out, smallest first.
481 The following sections describe the basic functions of the programs
482 that are found in the subdirectories of
484 The programs in a specific directory vary with the
485 type of output device or networks that have to be used.
492 is the default preprocessor for most printers.
495 command to determine the format of the input file.
496 The appropriate preprocessor is then selected to transform the
497 file to a format suitable for the printer.
499 Here is a list of some of the preprocessors and
500 a description of their function.
501 A complete list of preprocessors and their descriptions can be found in the manual page
504 .IP \f(CWdvipost\fP 14
505 Converts TeX or LaTeX output (\f(CW.dvi\fP files) to PostScript
507 Converts UTF text to PostScript.
508 The default font is Courier with Lucida fonts filling in
509 the remainder of the (available) Unicode character space.
511 Converts (device independent) troff output for the device type
514 .CW /sys/lib/troff/font/devutf
515 directory for troff font width table descriptions.
517 .CW /sys/lib/postscript/troff
518 directory for mappings of
521 character space to PostScript font space.
522 .IP \f(CWp9bitpost\fP
523 Converts Plan 9 bitmaps (see
527 Converts fax (CCITT-G31 format) to PostScript.
529 Does header page processing and page reversal processing, if
531 Page reversal is done here so the header page always comes
532 out at the beginning of the job.
533 Header page processing is very location-dependent.
539 spooler is responsible for executing the preprocessor
540 and directing its output to a file in the printer's queue.
541 An additional file is created containing information such as the system name,
542 user id, job number, and number of times this job was attempted.
544 Certain printer handling programs do not require separate
545 preprocessing and spooling.
546 For such circumstances a
548 spooler is available that just executes the preprocessing program.
549 The processing and spooling functions are assumed by this program and the output is sent to
551 or standard output if
557 spooler is used to send print jobs directly to a printer connected
558 to a 386 compatible printer port (See
563 The function of the shell scripts in the
565 directory is to present status information about the
566 printer and its queue.
569 scripts may be designed
570 to return information about the local queue as well as the remote queue.
571 This is not done on Plan 9 because many systems share the same queue directory.
572 The scheduler is used to print the queue in the order in which the jobs
579 scripts receive command line arguments passed to them by
581 and remove the job and id files which match the arguments
582 for the particular queue.
583 When a job is killed, the generic kill procedure:
585 kills the daemon for this queue if the job being killed
586 is first in the queue,
588 removes the files associated with the job from the queue,
590 attempts to restart the daemon.
596 shell scripts are the last to be invoked by
600 option has not been given.
601 The daemon process is executed asynchronously
602 with its standard output and standard error appended to
603 the printer log file.
604 The log file is described in a subsequent section.
605 Because the daemon runs asynchronously, it must
606 catch signals that could cause it to terminate abnormally.
607 The daemon first checks to see that it is the only one running
611 .CW /$cputype/bin/aux
617 file in the printer's queue directory.
618 The daemon then executes the scheduler to obtain the name of the
619 next job on the queue.
621 The processing of jobs may entail transfer to another host
622 or transmission to a printer.
623 The details of this are specific to the individual daemons.
624 If a job is processed without error, it is removed from the queue.
625 If a job does not succeed, the associated files may be
626 moved to a printer specific directory in
628 In either case, the daemon can make an entry in the printer's
630 Before exiting, the daemon should clean up lock files by calling
633 Several non-standard daemon programs have been designed
634 to suit various requirements and whims.
635 One such program announces job completion and empty paper trays
636 by causing icons to appear in peoples'
639 Another, using a voice synthesizer, makes verbal announcements.
640 Other daemons may be designed to taste.
644 The scheduler must decide which job files should be executed and
646 The most commonly used scheduler program is
648 which looks like this:
650 ls -tr $* | sed -n -e 's/.* *//' \e
651 -e '/^[0-9][0-9]*\.[1-9][0-9]*$/p'
653 This lists all the job files in this printer's queue in modification
655 Jobs entering the queue have a dot (.) prefixed to their name
656 to keep the scheduler from selecting them before they are complete.
658 Where Things Go Wrong
660 There are four directories where
663 On the Plan 9 release these directories may be found
664 in a directory on a scratch filesystem that is not
667 .CW /n/emelieother/lp .
668 It is built on top of a file system
670 that is mounted on the file server
672 The four directories in
673 this scratch directory
683 the first three into the directory
685 for its processes and their children.
688 directory is bound to the
690 directory so that the lp daemons, which run as user `none',
691 may write into this directory.
693 On any new installation, it is important that these directories
694 be set up and that the
696 command be editted to reflect the change.
697 If you do not have a scratch filesystem for these directories,
698 create the four directories
707 so that they are writable by anyone.
711 The log files for a particular
713 appear in a subdirectory of the spool directory
714 \f(CWlog\fP/\fIprinter\fP.
715 There are currently two types of log files.
716 One is for the daemon to log errors and successful completions
722 is the three letter abbreviation for the day of the week.
723 These are overwritten once a week to avoid the need for regular
725 The other type of log file contains the status of the printer and
726 is written by the program that communicates with the printer itself.
728 \fIprinter\fP.\f(CWst\fP.
729 These are overwritten with each new job and are saved in the
731 directory along with the job under circumstances described below.
732 When a printer does not appear to be functioning these files are the
737 When a job fails to produce output,
738 the log files should be checked for any obvious problems.
739 If none can be found, a directory with full read and write permissions
740 should be created with the name of the printer in the
743 Subsequent failure of a job will cause the daemon to leave a
744 copy of the job and the printer communication log in
745 \f(CW$LPLIB/prob/\fP\fIprinter\fP
747 It is common for a printer to enter states from which
748 it cannot be rescued except by manually cycling the power on the printer.
749 After this is done the print daemon should recover by itself
751 If it does not recover, remove the
753 file from the printer's spool directory to kill the daemon.
754 The daemon will have to be restarted by sending another job
756 For PostScript printers just use:
761 Repairing Stuck Daemons
763 There are conditions that occur which are not handled
765 One such problem can only be described as the printer entering a
767 The printer does not respond to any messages sent to it.
768 The daemon should recover from the reset and an error message
769 will appear in the log files.
770 If all else fails, one can kill the first job in the queue
773 file from the queue directory.
774 This will kill the daemon, which will have to be restarted.
776 Interprocessor Communication
778 A Plan 9 CPU server can be set up as a printer's spooling host.
779 That is, the machine where jobs are spooled and from which those jobs
780 are sent directly to the printer.
781 To do this, the CPU must listen on TCP port 515 which is the well known
782 port for the BSD line printer daemon.
784 .CW /rc/bin/service/tcp515
785 is executed when a call comes in on that port.
788 will accept jobs sent from BSD LPR/LPD systems.
790 .CW /$cputype/bin/aux/lpdaemon
791 command is executed from the service call and it accepts print jobs, requests for status,
792 and requests to kill jobs.
794 .CW /$cputype/bin/aux/lpsend
796 to other Plan 9 machines and is usually called from
797 within a spooler or daemon script.
799 .CW /$cputype/bin/aux/lpdsend
801 to machines and printers that use the BSD LPR/LPD protocol and is also usually called from
802 within a spooler or daemon script.
806 Special thanks to Rich Drechsler for supplying and maintaining most of
807 the PostScript translation and interface programs,
810 would be an empty shell.
811 Tomas Rokicki provided the
818 [Camp86] Ralph Campbell,
819 ``4.3BSD Line Printer Spooler Manual'', UNIX System Manager's Manual,
820 May, 1986, Berkeley, CA
822 [RFC1179] Request for Comments: 1179, Line Printer Daemon Protocol, Aug 1990
824 [Sys5] System V manual, date unknown
projects / plan9front.git / blob