2 <!-- SECTION: Getting Started -->
4 <TITLE>Command-Line Printing and Options
</TITLE>
8 <P>CUPS provides both the System V (
<A
9 HREF=
"man-lp.html">lp(
1)
</A>) and Berkeley (
<A
10 HREF=
"man-lpr.html">lpr(
1)
</A>) printing commands for printing
11 files. In addition, it supported a large number of standard and
12 printer-specific options that allow you to control how and where
13 files are printed.
</P>
16 <H2 CLASS=
"title"><A NAME=
"BASICS">Printing Files
</A></H2>
18 <P>CUPS understands many different types of files directly,
19 including text, PostScript, PDF, and image files. This allows you
20 to print from inside your applications or at the command-line,
21 whichever is most convenient! Type either of the following
22 commands to print a file to the default (or only) printer on the
30 <H3><A NAME=
"PRINTER">Choosing a Printer
</A></H3>
32 <P>Many systems will have more than one printer available to the
33 user. These printers can be attached to the local system via a
34 parallel, serial, or USB port, or available over the network. Use
35 the
<A HREF=
"man-lpstat.html">lpstat(
1)
</A> command to see a list
36 of available printers:
</P>
42 <P>The
<CODE>-p
</CODE> option specifies that you want to see a
43 list of printers, and the
<CODE>-d
</CODE> option reports the
44 current default printer or class.
</P>
46 <P>Use the
<CODE>-d
</CODE> option with the
<B>lp
</B> command to
47 print to a specific printer:
</P>
50 lp -d printer filename
53 <P>or the
<CODE>-P
</CODE> option with the
<B>lpr
</B> command:
</P>
56 lpr -P printer filename
59 <H3><A NAME=
"DEFAULT">Setting the Default Printer
</A></H3>
61 <P>If you normally use a particular printer, you can tell CUPS to
62 use it by default using the
<A
63 HREF=
"man-lpoptions.html">lpoptions(
1)
</A> command:
</P>
69 <H3><A NAME=
"PIPE">Printing the Output of a Program
</A></H3>
71 <P>Both the
<B>lp
</B> and
<B>lpr
</B> commands support printing
72 from the standard input:
</P>
76 program | lp -d printer
78 program | lpr -P printer
81 <P>If the program does not provide any output, then nothing will
82 be queued for printing.
</P>
84 <H3><A NAME=
"WITHOPTIONS">Specifying Printer Options
</A></H3>
86 <P>For many types of files, the default printer options may be
87 sufficient for your needs. However, there may be times when you
88 need to change the options for a particular file you are
91 <P>The
<B>lp
</B> and
<B>lpr
</B> commands allow you to pass
92 printer options using the
<CODE>-o
</CODE> option:
</P>
95 lp -o landscape -o scaling=
75 -o media=A4 filename.jpg
96 lpr -o landscape -o scaling=
75 -o media=A4 filename.jpg
99 <P>The available printer options vary depending on the printer.
100 The standard options are described in the
"<A
101 HREF="#OPTIONS
">Standard Printing Options</A>" section
102 below. Printer-specific options are also available and can be
103 listed using the
<B>lpoptions
</B> command:
</P>
105 <PRE CLASS=
"command">
106 lpoptions -p printer -l
109 <H3><A NAME=
"INSTANCES">Creating Saved Options
</A></H3>
111 <P>Saved options are supported in CUPS through
<em>printer
112 instances
</em>. Printer instances are, as their name implies, copies
113 of a printer that have certain options associated with them. Use the
114 <B>lpoptions
</B> command to create a printer instance:
</P>
116 <PRE CLASS=
"command">
117 lpoptions -p printer/instance -o name=value ...
120 <P>The
<CODE>-p printer/instance
</CODE> option provides the name of
121 the instance, which is always the printer name, a slash, and the
122 instance name which can contain any printable characters except
123 space and slash. The remaining options are then associated with the
124 instance instead of the main queue. For example, the following
125 command creates a duplex instance of the LaserJet queue:
</P>
127 <PRE CLASS=
"command">
128 lpoptions -p LaserJet/duplex -o sides=two-sided-long-edge
131 <P>Instances
<em>do not
</em> inherit lpoptions from the main
134 <H3><A NAME=
"COPIES">Printing Multiple Copies
</A></H3>
136 <P>Both the
<B>lp
</B> and
<B>lpr
</B> commands have options for
137 printing more than one copy of a file:
</P>
139 <PRE CLASS=
"command">
140 lp -n
<I>num-copies
</I> filename
141 lpr -#
<I>num-copies
</I> filename
144 <P>Copies are normally
<EM>not
</EM> collated for you. Use the
145 <CODE>-o Collate=True
</CODE> option to get collated copies:
</P>
147 <PRE CLASS=
"command">
148 lp -n
<I>num-copies
</I> -o Collate=True filename
149 lpr -#
<I>num-copies
</I> -o Collate=True filename
153 <H2 CLASS=
"title"><A NAME=
"CANCEL">Canceling a Print Job
</A></H2>
155 <P>The
<A HREF=
"man-cancel.html">cancel(
1)
</A> and
<A
156 HREF=
"man-lprm.html">lprm(
1)
</A> commands cancel a print job:
</P>
158 <PRE CLASS=
"command">
163 <P>The
<I>job-id
</I> is the number that was reported to you by
164 the
<B>lp
</B> command. You can also get the job ID using the
<A
165 HREF=
"man-lpq.html">lpq(
1)
</A> or
<A
166 HREF=
"man-lpstat.html">lpstat
</A> commands:
</P>
168 <PRE CLASS=
"command">
174 <H2 CLASS=
"title"><A NAME=
"LPMOVE">Moving a Print Job
</A></H2>
176 <P>The
<A HREF=
"man-lpmove.html">lpmove(
8)
</A> command moves a print
177 job to a new printer or class:
</P>
179 <PRE CLASS=
"command">
180 lpmove
<I>job-id
</I> <i>destination
</i>
183 <P>The
<I>job-id
</I> is the number that was reported to you by
184 the
<B>lp
</B> or
<B>lpstat
</B> commands.
<i>Destination
</i> is the
185 name of a printer or class that you want to actually print the job.
187 <BLOCKQUOTE><B>Note:
</B>
189 <P>The
<B>lpmove
</B> command is located in the system command
190 directory (typically
<VAR>/usr/sbin
</VAR> or
<VAR>/usr/local/sbin
</VAR>),
191 and so may not be in your command path. Specify the full path to the
192 command if you get a
"command not found" error, for example:
194 <PRE CLASS=
"command">
195 /usr/sbin/lpmove foo-
123 bar
201 <H2 CLASS=
"title"><A NAME=
"OPTIONS">Standard Printing Options
</A></H2>
203 <P>The following options apply when printing all types of
206 <H3><A NAME=
"MEDIA">Selecting the Media Size, Type, and Source
</A></H3>
208 <P>The
<CODE>-o media=xyz
</CODE> option sets the media size,
209 type, and/or source:
</P>
211 <PRE CLASS=
"command">
212 lp -o media=Letter filename
213 lp -o media=Letter,MultiPurpose filename
214 lpr -o media=Letter,Transparency filename
215 lpr -o media=Letter,MultiPurpose,Transparency filename
218 <P>The available media sizes, types, and sources depend on the
219 printer, but most support the following options (case is not
224 <LI><CODE>Letter
</CODE> - US Letter (
8.5x11 inches, or
216x279mm)
226 <LI><CODE>Legal
</CODE> - US Legal (
8.5x14 inches, or
216x356mm)
228 <LI><CODE>A4
</CODE> - ISO A4 (
8.27x11.69 inches, or
210x297mm)
230 <LI><CODE>COM10
</CODE> - US #
10 Envelope (
9.5x4.125 inches, or
233 <LI><CODE>DL
</CODE> - ISO DL Envelope (
8.66x4.33 inches, or
220x110mm)
235 <LI><CODE>Transparency
</CODE> - Transparency media type or source
237 <LI><CODE>Upper
</CODE> - Upper paper tray
239 <LI><CODE>Lower
</CODE> - Lower paper tray
241 <LI><CODE>MultiPurpose
</CODE> - Multi-purpose paper tray
243 <LI><CODE>LargeCapacity
</CODE> - Large capacity paper tray
247 <P>The actual options supported are defined in the printer's PPD
248 file in the
<CODE>PageSize
</CODE>,
<CODE>InputSlot
</CODE>, and
249 <CODE>MediaType
</CODE> options. You can list them using the
250 <B>lpoptions(
1)
</B> command:
</P>
252 <PRE CLASS=
"command">
253 lpoptions -p printer -l
256 <P>When
<CODE>Custom
</CODE> is listed for the
<CODE>PageSize
</CODE> option, you can specify custom media sizes using one of the following forms:
</P>
258 <PRE CLASS=
"command">
259 lp -o media=Custom.
<I>WIDTH
</I>x
<I>LENGTH
</I> filename
260 lp -o media=Custom.
<I>WIDTH
</I>x
<I>LENGTH
</I>in filename
261 lp -o media=Custom.
<I>WIDTH
</I>x
<I>LENGTH
</I>cm filename
262 lp -o media=Custom.
<I>WIDTH
</I>x
<I>LENGTH
</I>mm filename
265 <P>where
"WIDTH" and
"LENGTH" are the width and length of the media in points, inches, centimeters, or millimeters, respectively.
</P>
268 <H3><A NAME=
"ORIENTATION">Setting the Orientation
</A></H3>
270 <P>The
<CODE>-o landscape
</CODE> option will rotate the page
90
271 degrees to print in landscape orientation:
</P>
273 <PRE CLASS=
"command">
274 lp -o landscape filename
275 lpr -o landscape filename
278 <P>The
<CODE>-o orientation-requested=N
</CODE> option rotates the
279 page depending on the value of N:
</P>
283 <LI><CODE>-o orientation-requested=
3</CODE> - portrait
284 orientation (no rotation)
</LI>
286 <LI><CODE>-o orientation-requested=
4</CODE> - landscape
287 orientation (
90 degrees)
</LI>
289 <LI><CODE>-o orientation-requested=
5</CODE> - reverse
290 landscape or seascape orientation (
270 degrees)
</LI>
292 <LI><CODE>-o orientation-requested=
6</CODE> - reverse
293 portrait or upside-down orientation (
180 degrees)
</LI>
297 <H3><A NAME=
"SIDES">Printing On Both Sides of the Paper
</A></H3>
299 <P>The
<CODE>-o sides=two-sided-short-edge
</CODE> and
<CODE>-o
300 sides=two-sided-long-edge
</CODE> options will enable two-sided
301 printing on the printer if the printer supports it. The
<CODE>-o
302 sides=two-sided-short-edge
</CODE> option is suitable for
303 landscape pages, while the
<CODE>-o
304 sides=two-sided-long-edge
</CODE> option is suitable for portrait
307 <PRE CLASS=
"command">
308 lp -o sides=two-sided-short-edge filename
309 lp -o sides=two-sided-long-edge filename
310 lpr -o sides=two-sided-long-edge filename
313 <P>The default is to print single-sided:
</P>
315 <PRE CLASS=
"command">
316 lp -o sides=one-sided filename
317 lpr -o sides=one-sided filename
320 <H3><A NAME=
"JOBSHEETS">Selecting the Banner Page(s)
</A></H3>
322 <P>The
<CODE>-o jobsheets=start,end
</CODE> option sets the banner
323 page(s) to use for a job:
</P>
325 <PRE CLASS=
"command">
326 lp -o job-sheets=none filename
327 lp -o job-sheets=standard filename
328 lpr -o job-sheets=classified,classified filename
331 <P>If only one banner file is specified, it will be printed
332 before the files in the job. If a second banner file is
333 specified, it is printed after the files in the job.
</P>
335 <P>The available banner pages depend on the local system
336 configuration; CUPS includes the following banner files:
</P>
340 <LI><CODE>none
</CODE> - Do not produce a banner page.
342 <LI><CODE>classified
</CODE> - A banner page with a
"classified"
343 label at the top and bottom.
345 <LI><CODE>confidential
</CODE> - A banner page with a
346 "confidential" label at the top and bottom.
348 <LI><CODE>secret
</CODE> - A banner page with a
"secret" label
349 at the top and bottom.
351 <LI><CODE>standard
</CODE> - A banner page with no label at the
354 <LI><CODE>topsecret
</CODE> - A banner page with a
"top secret"
355 label at the top and bottom.
357 <LI><CODE>unclassified
</CODE> - A banner page with an
358 "unclassified" label at the top and bottom.
363 <H3><A NAME=
"OUTPUTORDER">Specifying the Output Order
</A></H3>
365 <P>The
<CODE>-o outputorder=normal
</CODE> and
<CODE>-o outputorder=reverse
</CODE> options specify the order of the pages. Normal order prints page
1 first, page
2 second, and so forth. Reverse order prints page
1 last.
</P>
368 <H3><A NAME=
"PAGERANGES">Selecting a Range of Pages
</A></H3>
370 <P>The
<CODE>-o page-ranges=pages
</CODE> option selects a range
371 of pages for printing:
</P>
373 <PRE CLASS=
"command">
374 lp -o page-ranges=
1 filename
375 lp -o page-ranges=
1-
4 filename
376 lp -o page-ranges=
1-
4,
7,
9-
12 filename
377 lpr -o page-ranges=
1-
4,
7,
9-
12 filename
380 <P>As shown above, the
<CODE>pages
</CODE> value can be a single page, a
381 range of pages, or a collection of page numbers and ranges separated by
382 commas. The pages will always be printed in ascending order, regardless
383 of the order of the pages in the
<CODE>page-ranges
</CODE> option.
385 <P>The default is to print all pages.
387 <H3><A NAME=
"PAGESET">Selecting Even or Odd Pages
</A></H3>
389 <P>Use the
<CODE>-o page-set=set
</CODE> option to select the even or odd pages:
</P>
391 <PRE CLASS=
"command">
392 lp -o page-set=odd filename
393 lp -o page-set=even filename
394 lpr -o page-set=even filename
397 <P>The default is to print all pages.
399 <H3><A NAME=
"NUMBERUP">N-Up Printing
</A></H3>
401 <P>The
<CODE>-o number-up=value
</CODE> option selects N-Up
402 printing. N-Up printing places multiple document pages on a
403 single printed page. CUPS supports
1,
2,
4,
6,
9, and
16-Up
404 formats; the default format is
1-Up:
</P>
406 <PRE CLASS=
"command">
407 lp -o number-up=
1 filename
408 lp -o number-up=
2 filename
409 lp -o number-up=
4 filename
410 lpr -o number-up=
16 filename
413 <P>The
<CODE>-o page-border=value
</CODE> option chooses the
414 border to draw around each page:
</P>
417 <LI><CODE>-o page-border=double
</CODE>; draw two hairline borders around each page
</LI>
418 <LI><CODE>-o page-border=double-thick
</CODE>; draw two
1pt borders around each page
</LI>
419 <LI><CODE>-o page-border=none
</CODE>; do not draw a border (default)
</LI>
420 <LI><CODE>-o page-border=single
</CODE>; draw one hairline border around each page
</LI>
421 <LI><CODE>-o page-border=single-thick
</CODE>; draw one
1pt border around each page
</LI>
424 <P>The
<CODE>-o number-up-layout=value
</CODE> option chooses the
425 layout of the pages on each output page:
</P>
428 <LI><CODE>-o number-up-layout=btlr
</CODE>; Bottom to top, left to right
</LI>
429 <LI><CODE>-o number-up-layout=btrl
</CODE>; Bottom to top, right to left
</LI>
430 <LI><CODE>-o number-up-layout=lrbt
</CODE>; Left to right, bottom to top
</LI>
431 <LI><CODE>-o number-up-layout=lrtb
</CODE>; Left to right, top to bottom (default)
</LI>
432 <LI><CODE>-o number-up-layout=rlbt
</CODE>; Right to left, bottom to top
</LI>
433 <LI><CODE>-o number-up-layout=rltb
</CODE>; Right to left, top to bottom
</LI>
434 <LI><CODE>-o number-up-layout=tblr
</CODE>; Top to bottom, left to right
</LI>
435 <LI><CODE>-o number-up-layout=tbrl
</CODE>; Top to bottom, right to left
</LI>
438 <H3><A NAME=
"FITPLOT">Scaling to Fit
</A></H3>
440 <P>The
<CODE>-o fitplot
</CODE> option specifies that the document
441 should be scaled to fit on the page:
</P>
443 <PRE CLASS=
"command">
444 lp -o fitplot filename
445 lpr -o fitplot filename
448 <P>The default is to use the size specified in the file.
</P>
450 <BLOCKQUOTE>Note: This feature depends upon an accurate size in
451 the print file. If no size is given in the file, the page may be
452 scaled incorrectly!
</BLOCKQUOTE>
454 <H3><A NAME=
"RAW">Raw or Unfiltered Output
</A></H3>
456 <P>The
<CODE>-o raw
</CODE> option allows you to send files
457 directly to a printer without filtering. This is sometimes
458 required when printing from applications that provide their own
459 "printer drivers" for your printer:
</P>
461 <PRE CLASS=
"command">
466 <P>The
<CODE>-l
</CODE> option can also be used with the
467 <B>lpr
</B> command to send files directly to a printer:
</P>
469 <PRE CLASS=
"command">
474 <H2 CLASS=
"title"><A NAME=
"TEXTOPTIONS">Text Options
</A></H2>
476 <P>CUPS supports several options that are only used when printing
477 plain text files. These options have absolutely no effect on
478 PostScript, PDF, HP-GL/
2, or image files.
</P>
480 <H3><A NAME=
"CPI">Setting the Number of Characters Per Inch
</A></H3>
482 <P>The
<CODE>-o cpi=value
</CODE> option sets the number of
483 characters per inch:
</P>
485 <PRE CLASS=
"command">
486 lp -o cpi=
10 filename
487 lp -o cpi=
12 filename
488 lpr -o cpi=
17 filename
491 <P>The default characters per inch is
10.
</P>
493 <H3><A NAME=
"LPI">Setting the Number of Lines Per Inch
</A></H3>
495 <P>The
<CODE>-o lpi=value
</CODE> option sets the number of lines
498 <PRE CLASS=
"command">
500 lpr -o lpi=
8 filename
503 <P>The default lines per inch is
6.
</P>
505 <H3><A NAME=
"COLUMNS">Setting the Number of Columns
</A></H3>
507 <P>The
<CODE>-o columns=value
</CODE> option sets the number of
510 <PRE CLASS=
"command">
511 lp -o columns=
2 filename
512 lpr -o columns=
3 filename
515 <P>The default number of columns is
1.
</P>
517 <H3><A NAME=
"MARGINS">Setting the Page Margins
</A></H3>
519 <P>Normally the page margins are set to the hard limits of the
520 printer. Use the
<CODE>-o page-left=value
</CODE>,
<CODE>-o
521 page-right=value
</CODE>,
<CODE>-o page-top=value
</CODE>, and
522 <CODE>-o page-bottom=value
</CODE> options to adjust the page
525 <PRE CLASS=
"command">
526 lp -o page-left=
<I>value
</I> filename
527 lp -o page-right=
<I>value
</I> filename
528 lp -o page-top=
<I>value
</I> filename
529 lp -o page-bottom=
<I>value
</I> filename
530 lpr -o page-left=
<I>value
</I> -o page-right=
<I>value
</I> -o page-top=
<I>value
</I> -o page-bottom=
<I>value
</I> filename
533 <P>The
<CODE>value
</CODE> argument is the margin in points; each
534 point is
1/
72 inch or
0.35mm.
</P>
536 <H3><A NAME=
"PRETTYPRINT">Pretty Printing
</A></H3>
538 <P>The
<CODE>-o prettyprint
</CODE> option puts a header at the
539 top of each page with the page number, job title (usually the
540 filename), and the date. Also, C and C++ keywords are
541 highlighted, and comment lines are italicized:
</P>
543 <PRE CLASS=
"command">
544 lp -o prettyprint filename
545 lpr -o prettyprint filename