Put in remaining pages and wiki contents.
[ikiwiki.git] / docs / handbook / handbook-printing-using.mdwn
1 \r
2 \r
3 ## 11.5 Using Printers \r
4 \r
5 This section tells you how to use printers you have set up with DragonFly. Here is an overview of the user-level commands:\r
6 \r
7 [lpr(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#lpr&section1):: Print jobs[lpq(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=lpq&section=1):: Check printer queues[lprm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=lprm&section=1):: Remove jobs from a printer's queue\r
8 \r
9 There is also an administrative command, [lpc(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#lpc&section8), described in the section [printing-using.html#PRINTING-LPC Administering the  **LPD**  Spooler], used to control printers and their queues.\r
10 \r
11 All three of the commands [lpr(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#lpr&section1), [lprm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=lprm&section=1), and [lpq(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=lpq&section=1) accept an option `-P `***printer-name****** to specify on which printer/queue to operate, as listed in the `/etc/printcap` file. This enables you to submit, remove, and check on jobs for various printers. If you do not use the `-P` option, then these commands use the printer specified in the `PRINTER` environment variable. Finally, if you do not have a `PRINTER` environment variable, these commands default to the printer named `lp`.\r
12 \r
13 Hereafter, the terminology ***default printer*** means the printer named in the `PRINTER` environment variable, or the printer named `lp` when there is no `PRINTER` environment variable.\r
14 \r
15 ### 11.5.1 Printing Jobs \r
16 \r
17 To print files, type:\r
18 \r
19     \r
20     % lpr `***filename***` `***...***`\r
21 \r
22 \r
23 This prints each of the listed files to the default printer. If you list no files, [lpr(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#lpr&section1) reads data to print from standard input. For example, this command prints some important system files:\r
24 \r
25     \r
26     % lpr /etc/host.conf /etc/hosts.equiv\r
27 \r
28 \r
29 To select a specific printer, type:\r
30 \r
31     \r
32     % lpr -P `***printer-name***` `***filename***` `***...***`\r
33 \r
34 \r
35 This example prints a long listing of the current directory to the printer named `rattan`:\r
36 \r
37     \r
38     % ls -l | lpr -P rattan\r
39 \r
40 \r
41 Because no files were listed for the [lpr(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#lpr&section1) command, `lpr` read the data to print from standard input, which was the output of the `ls -l` command.\r
42 \r
43 The [lpr(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#lpr&section1) command can also accept a wide variety of options to control formatting, apply file conversions, generate multiple copies, and so forth. For more information, see the section [printing-using.html#PRINTING-LPR-OPTIONS Printing Options].\r
44 \r
45 ### 11.5.2 Checking Jobs \r
46 \r
47 When you print with [lpr(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#lpr&section1), the data you wish to print is put together in a package called a ***print job***, which is sent to the  **LPD**  spooling system. Each printer has a queue of jobs, and your job waits in that queue along with other jobs from yourself and from other users. The printer prints those jobs in a first-come, first-served order.\r
48 \r
49 To display the queue for the default printer, type [lpq(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#lpq&section1). For a specific printer, use the `-P` option. For example, the command\r
50 \r
51     \r
52     % lpq -P bamboo\r
53 \r
54 \r
55  shows the queue for the printer named `bamboo`. Here is an example of the output of the `lpq` command:\r
56 \r
57     \r
58     bamboo is ready and printing\r
59     Rank   Owner    Job  Files                              Total Size\r
60     active kelly    9    /etc/host.conf, /etc/hosts.equiv   88 bytes\r
61     2nd    kelly    10   (standard input)                   1635 bytes\r
62     3rd    mary     11   ...                                78519 bytes\r
63 \r
64 \r
65 This shows three jobs in the queue for `bamboo`. The first job, submitted by user kelly, got assigned ***job number*** 9. Every job for a printer gets a unique job number. Most of the time you can ignore the job number, but you will need it if you want to cancel the job; see section [printing-using.html#PRINTING-LPRM Removing Jobs] for details.\r
66 \r
67 Job number nine consists of two files; multiple files given on the [lpr(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#lpr&section1) command line are treated as part of a single job. It is the currently active job (note the word `active` under the ***Rank*** column), which means the printer should be currently printing that job. The second job consists of data passed as the standard input to the [lpr(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=lpr&section=1) command. The third job came from user `mary`; it is a much larger job. The pathname of the file she is trying to print is too long to fit, so the [lpq(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=lpq&section=1) command just shows three dots.\r
68 \r
69 The very first line of the output from [lpq(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#lpq&section1) is also useful: it tells what the printer is currently doing (or at least what  **LPD**  thinks the printer is doing).\r
70 \r
71 The [lpq(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#lpq&section1) command also support a `-l` option to generate a detailed long listing. Here is an example of `lpq -l`:\r
72 \r
73     \r
74     waiting for bamboo to become ready (offline ?)\r
75     kelly: 1st                           [job 009rose]\r
76            /etc/host.conf                    73 bytes\r
77            /etc/hosts.equiv                  15 bytes\r
78     \r
79     kelly: 2nd                           [job 010rose]\r
80            (standard input)                  1635 bytes\r
81     \r
82     mary: 3rd                                [job 011rose]\r
83           /home/orchid/mary/research/venus/alpha-regio/mapping 78519 bytes\r
84 \r
85 \r
86 ### 11.5.3 Removing Jobs \r
87 \r
88 If you change your mind about printing a job, you can remove the job from the queue with the [lprm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#lprm&section1) command. Often, you can even use [lprm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=lprm&section=1) to remove an active job, but some or all of the job might still get printed.\r
89 \r
90 To remove a job from the default printer, first use [lpq(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#lpq&section1) to find the job number. Then type:\r
91 \r
92     \r
93     % lprm `***job-number***`\r
94 \r
95 \r
96 To remove the job from a specific printer, add the `-P` option. The following command removes job number 10 from the queue for the printer `bamboo`:\r
97 \r
98     \r
99     % lprm -P bamboo 10\r
100 \r
101 \r
102 The [lprm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#lprm&section1) command has a few shortcuts:\r
103 \r
104 lprm -:: Removes all jobs (for the default printer) belonging to you.lprm `***user***`:: Removes all jobs (for the default printer) belonging to `***user***`. The superuser can remove other users' jobs; you can remove only your own jobs.lprm:: With no job number, user name, or `-` appearing on the command line, [lprm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#lprm&section1) removes the currently active job on the default printer, if it belongs to you. The superuser can remove any active job.\r
105 \r
106 Just use the `-P` option with the above shortcuts to operate on a specific printer instead of the default. For example, the following command removes all jobs for the current user in the queue for the printer named `rattan`:\r
107 \r
108     \r
109     % lprm -P rattan -\r
110 \r
111 \r
112  **Note:** If you are working in a networked environment, [lprm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#lprm&section1) will let you remove jobs only from the host from which the jobs were submitted, even if the same printer is available from other hosts. The following command sequence demonstrates this:\r
113 \r
114     \r
115     % lpr -P rattan myfile\r
116     % rlogin orchid\r
117     % lpq -P rattan\r
118     Rank   Owner          Job  Files                          Total Size\r
119     active seeyan         12    ...                           49123 bytes\r
120     2nd    kelly      13   myfile                         12 bytes\r
121     % lprm -P rattan 13\r
122     rose: Permission denied\r
123     % logout\r
124     % lprm -P rattan 13\r
125     dfA013rose dequeued\r
126     cfA013rose dequeued\r
127     \r
128 \r
129 \r
130 ### 11.5.4 Beyond Plain Text: Printing Options \r
131 \r
132 The [lpr(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#lpr&section1) command supports a number of options that control formatting text, converting graphic and other file formats, producing multiple copies, handling of the job, and more. This section describes the options.\r
133 \r
134 #### Formatting and Conversion Options \r
135 \r
136 The following [lpr(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#lpr&section1) options control formatting of the files in the job. Use these options if the job does not contain plain text or if you want plain text formatted through the [pr(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pr&section=1) utility.\r
137 \r
138 For example, the following command prints a DVI file (from the TeX typesetting system) named `fish-report.dvi` to the printer named `bamboo`:\r
139 \r
140     \r
141     % lpr -P bamboo -d fish-report.dvi\r
142 \r
143 \r
144 These options apply to every file in the job, so you cannot mix (say) DVI and ditroff files together in a job. Instead, submit the files as separate jobs, using a different conversion option for each job.\r
145 \r
146  **Note:** All of these options except `-p` and `-T` require conversion filters installed for the destination printer. For example, the `-d` option requires the DVI conversion filter. Section [printing-advanced.html#PRINTING-ADVANCED-CONVFILTERS Conversion Filters] gives details.\r
147 \r
148 `-c`:: Print cifplot files.`-d`:: Print DVI files.`-f`:: Print FORTRAN text files.`-g`:: Print plot data.`-i `***number******:: Indent the output by `***number***` columns; if you omit `***number***`, indent by 8 columns. This option works only with certain conversion filters.\r
149  **Note:** Do not put any space between the `-i` and the number.`-l`:: Print literal text data, including control characters.`-n`:: Print ditroff (device independent troff) data.-p:: Format plain text with [pr(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#pr&section1) before printing. See [pr(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pr&section=1) for more information.`-T `***title******:: Use `***title***` on the [pr(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pr&section=1) header instead of the file name. This option has effect only when used with the `-p` option.`-t`:: Print troff data.`-v`:: Print raster data.\r
150 \r
151 Here is an example: this command prints a nicely formatted version of the [ls(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ls&section1) manual page on the default printer:\r
152 \r
153     \r
154     % zcat /usr/share/man/man1/ls.1.gz | troff -t -man | lpr -t\r
155 \r
156 \r
157 The [zcat(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#zcat&section1) command uncompresses the source of the [ls(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ls&section=1) manual page and passes it to the [troff(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=troff&section=1) command, which formats that source and makes GNU troff output and passes it to [lpr(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=lpr&section=1), which submits the job to the  **LPD**  spooler. Because we used the `-t` option to [lpr(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=lpr&section=1), the spooler will convert the GNU troff output into a format the default printer can understand when it prints the job.\r
158 \r
159 #### Job Handling Options \r
160 \r
161 The following options to [lpr(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#lpr&section1) tell  **LPD**  to handle the job specially:\r
162 \r
163 -# `***copies***`:: Produce a number of `***copies***` of each file in the job instead of just one copy. An administrator may disable this option to reduce printer wear-and-tear and encourage photocopier usage. See section [printing-advanced.html#PRINTING-ADVANCED-RESTRICTING-COPIES Restricting Multiple Copies].\r
164 This example prints three copies of `parser.c` followed by three copies of `parser.h` to the default printer:\r
165     \r
166     % lpr -#3 parser.c parser.h\r
167 -m:: Send mail after completing the print job. With this option, the  **LPD**  system will send mail to your account when it finishes handling your job. In its message, it will tell you if the job completed successfully or if there was an error, and (often) what the error was.-s:: Do not copy the files to the spooling directory, but make symbolic links to them instead.\r
168 If you are printing a large job, you probably want to use this option. It saves space in the spooling directory (your job might overflow the free space on the filesystem where the spooling directory resides). It saves time as well since  **LPD**  will not have to copy each and every byte of your job to the spooling directory.\r
169 There is a drawback, though: since  **LPD**  will refer to the original files directly, you cannot modify or remove them until they have been printed.\r
170  **Note:** If you are printing to a remote printer,  **LPD**  will eventually have to copy files from the local host to the remote host, so the `-s` option will save space only on the local spooling directory, not the remote. It is still useful, though.-r:: Remove the files in the job after copying them to the spooling directory, or after printing them with the `-s` option. Be careful with this option!\r
171 \r
172 #### Header Page Options \r
173 \r
174 These options to [lpr(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#lpr&section1) adjust the text that normally appears on a job's header page. If header pages are suppressed for the destination printer, these options have no effect. See section [printing-advanced.html#PRINTING-ADVANCED-HEADER-PAGES Header Pages] for information about setting up header pages.\r
175 \r
176 -C `***text***`:: Replace the hostname on the header page with `***text***`. The hostname is normally the name of the host from which the job was submitted.-J `***text***`:: Replace the job name on the header page with `***text***`. The job name is normally the name of the first file of the job, or `stdin` if you are printing standard input.-h:: Do not print any header page.\r
177  **Note:** At some sites, this option may have no effect due to the way header pages are generated. See [printing-advanced.html#PRINTING-ADVANCED-HEADER-PAGES Header Pages] for details.\r
178 \r
179 ### 11.5.5 Administering Printers \r
180 \r
181 As an administrator for your printers, you have had to install, set up, and test them. Using the [lpc(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#lpc&section8) command, you can interact with your printers in yet more ways. With [lpc(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=lpc&section=8), you can\r
182 \r
184 * Start and stop the printers\r
186 * Enable and disable their queues\r
188 * Rearrange the order of the jobs in each queue.\r
189 \r
190 First, a note about terminology: if a printer is ***stopped***, it will not print anything in its queue. Users can still submit jobs, which will wait in the queue until the printer is ***started*** or the queue is cleared.\r
191 \r
192 If a queue is ***disabled***, no user (except `root`) can submit jobs for the printer. An ***enabled*** queue allows jobs to be submitted. A printer can be ***started*** for a disabled queue, in which case it will continue to print jobs in the queue until the queue is empty.\r
193 \r
194 In general, you have to have `root` privileges to use the [lpc(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#lpc&section8) command. Ordinary users can use the [lpc(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=lpc&section=8) command to get printer status and to restart a hung printer only.\r
195 \r
196 Here is a summary of the [lpc(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#lpc&section8) commands. Most of the commands take a `***printer-name***` argument to tell on which printer to operate. You can use `all` for the `***printer-name***` to mean all printers listed in `/etc/printcap`.\r
197 \r
198 `abort `***printer-name******:: Cancel the current job and stop the printer. Users can still submit jobs if the queue is enabled.`clean `***printer-name******:: Remove old files from the printer's spooling directory. Occasionally, the files that make up a job are not properly removed by  **LPD** , particularly if there have been errors during printing or a lot of administrative activity. This command finds files that do not belong in the spooling directory and removes them.`disable `***printer-name******:: Disable queuing of new jobs. If the printer is running, it will continue to print any jobs remaining in the queue. The superuser (`root`) can always submit jobs, even to a disabled queue.\r
199 This command is useful while you are testing a new printer or filter installation: disable the queue and submit jobs as `root`. Other users will not be able to submit jobs until you complete your testing and re-enable the queue with the `enable` command.`down `***printer-name***` `***message******:: Take a printer down. Equivalent to `disable` followed by `stop`. The `***message***` appears as the printer's status whenever a user checks the printer's queue with [lpq(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#lpq&section1) or status with `lpc status`.`enable `***printer-name******:: Enable the queue for a printer. Users can submit jobs but the printer will not print anything until it is started.`help `***command-name******:: Print help on the command `***command-name***`. With no `***command-name***`, print a summary of the commands available.`restart `***printer-name' **:: Start the printer. Ordinary users can use this command if some extraordinary circumstance hangs** LPD***', but they cannot start a printer stopped with either the `stop` or `down` commands. The `restart` command is equivalent to `abort` followed by `start`.`start `***printer-name******:: Start the printer. The printer will print jobs in its queue.`stop `***printer-name******:: Stop the printer. The printer will finish the current job and will not print anything else in its queue. Even though the printer is stopped, users can still submit jobs to an enabled queue.`topq `***printer-name***` `***job-or-username******:: Rearrange the queue for `***printer-name***` by placing the jobs with the listed `***job***` numbers or the jobs belonging to `***username***` at the top of the queue. For this command, you cannot use `all` as the `***printer-name***`.`up `***printer-name******:: Bring a printer up; the opposite of the `down` command. Equivalent to `start` followed by `enable`.\r
200 \r
201 [lpc(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#lpc&section8) accepts the above commands on the command line. If you do not enter any commands, [lpc(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=lpc&section=8) enters an interactive mode, where you can enter commands until you type `exit`, `quit`, or end-of-file.\r
202 \r
203 \r
204 \r
205 CategoryHandbook\r
206 CategoryHandbook-printing\r