doc/help/options.html

   1 <HTML>
   2 <!-- SECTION: Getting Started -->
   3 <HEAD>
   4         <TITLE>Command-Line Printing and Options</TITLE>
   5 </HEAD>
   6 <BODY>
   7
   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>
  14
  15
  16 <H2 CLASS="title"><A NAME="BASICS">Printing Files</A></H2>
  17
  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
  23 system:</P>
  24
  25 <PRE CLASS="command">
  26 lp filename
  27 lpr filename
  28 </PRE>
  29
  30 <H3><A NAME="PRINTER">Choosing a Printer</A></H3>
  31
  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>
  37
  38 <PRE CLASS="command">
  39 lpstat -p -d
  40 </PRE>
  41
  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>
  45
  46 <P>Use the <CODE>-d</CODE> option with the <B>lp</B> command to
  47 print to a specific printer:</P>
  48
  49 <PRE CLASS="command">
  50 lp -d printer filename
  51 </PRE>
  52
  53 <P>or the <CODE>-P</CODE> option with the <B>lpr</B> command:</P>
  54
  55 <PRE CLASS="command">
  56 lpr -P printer filename
  57 </PRE>
  58
  59 <H3><A NAME="DEFAULT">Setting the Default Printer</A></H3>
  60
  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>
  64
  65 <PRE CLASS="command">
  66 lpoptions -d printer
  67 </PRE>
  68
  69 <H3><A NAME="PIPE">Printing the Output of a Program</A></H3>
  70
  71 <P>Both the <B>lp</B> and <B>lpr</B> commands support printing
  72 from the standard input:</P>
  73
  74 <PRE CLASS="command">
  75 program | lp
  76 program | lp -d printer
  77 program | lpr
  78 program | lpr -P printer
  79 </PRE>
  80
  81 <P>If the program does not provide any output, then nothing will
  82 be queued for printing.</P>
  83
  84 <H3><A NAME="WITHOPTIONS">Specifying Printer Options</A></H3>
  85
  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
  89 printing.</P>
  90
  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>
  93
  94 <PRE CLASS="command">
  95 lp -o landscape -o scaling=75 -o media=A4 filename.jpg
  96 lpr -o landscape -o scaling=75 -o media=A4 filename.jpg
  97 </PRE>
  98
  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>
 104
 105 <PRE CLASS="command">
 106 lpoptions -p printer -l
 107 </PRE>
 108
 109 <H3><A NAME="INSTANCES">Creating Saved Options</A></H3>
 110
 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>
 115
 116 <PRE CLASS="command">
 117 lpoptions -p printer/instance -o name=value ...
 118 </PRE>
 119
 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>
 126
 127 <PRE CLASS="command">
 128 lpoptions -p LaserJet/duplex -o sides=two-sided-long-edge
 129 </PRE>
 130
 131 <P>Instances <em>do not</em> inherit lpoptions from the main
 132 queue.</P>
 133
 134 <H3><A NAME="COPIES">Printing Multiple Copies</A></H3>
 135
 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>
 138
 139 <PRE CLASS="command">
 140 lp -n <I>num-copies</I> filename
 141 lpr -#<I>num-copies</I> filename
 142 </PRE>
 143
 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>
 146
 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
 150 </PRE>
 151
 152
 153 <H2 CLASS="title"><A NAME="CANCEL">Canceling a Print Job</A></H2>
 154
 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>
 157
 158 <PRE CLASS="command">
 159 cancel <I>job-id</I>
 160 lprm <I>job-id</I>
 161 </PRE>
 162
 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>
 167
 168 <PRE CLASS="command">
 169 lpq
 170 lpstat
 171 </PRE>
 172
 173
 174 <H2 CLASS="title"><A NAME="LPMOVE">Moving a Print Job</A></H2>
 175
 176 <P>The <A HREF="man-lpmove.html">lpmove(8)</A> command moves a print
 177 job to a new printer or class:</P>
 178
 179 <PRE CLASS="command">
 180 lpmove <I>job-id</I> <i>destination</i>
 181 </PRE>
 182
 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.
 186
 187 <BLOCKQUOTE><B>Note:</B>
 188
 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:
 193
 194 <PRE CLASS="command">
 195 /usr/sbin/lpmove foo-123 bar
 196 </PRE>
 197
 198 </BLOCKQUOTE>
 199
 200
 201 <H2 CLASS="title"><A NAME="OPTIONS">Standard Printing Options</A></H2>
 202
 203 <P>The following options apply when printing all types of
 204 files.</P>
 205
 206 <H3><A NAME="MEDIA">Selecting the Media Size, Type, and Source</A></H3>
 207
 208 <P>The <CODE>-o media=xyz</CODE> option sets the media size,
 209 type, and/or source:</P>
 210
 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
 216 </PRE>
 217
 218 <P>The available media sizes, types, and sources depend on the
 219 printer, but most support the following options (case is not
 220 significant):</P>
 221
 222 <UL>
 223
 224         <LI><CODE>Letter</CODE> - US Letter (8.5x11 inches, or 216x279mm)
 225
 226         <LI><CODE>Legal</CODE> - US Legal (8.5x14 inches, or 216x356mm)
 227
 228         <LI><CODE>A4</CODE> - ISO A4 (8.27x11.69 inches, or 210x297mm)
 229
 230         <LI><CODE>COM10</CODE> - US #10 Envelope (9.5x4.125 inches, or
 231         241x105mm)
 232
 233         <LI><CODE>DL</CODE> - ISO DL Envelope (8.66x4.33 inches, or 220x110mm)
 234
 235         <LI><CODE>Transparency</CODE> - Transparency media type or source
 236
 237         <LI><CODE>Upper</CODE> - Upper paper tray
 238
 239         <LI><CODE>Lower</CODE> - Lower paper tray
 240
 241         <LI><CODE>MultiPurpose</CODE> - Multi-purpose paper tray
 242
 243         <LI><CODE>LargeCapacity</CODE> - Large capacity paper tray
 244
 245 </UL>
 246
 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>
 251
 252 <PRE CLASS="command">
 253 lpoptions -p printer -l
 254 </PRE>
 255
 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>
 257
 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
 263 </PRE>
 264
 265 <P>where "WIDTH" and "LENGTH" are the width and length of the media in points, inches, centimeters, or millimeters, respectively.</P>
 266
 267
 268 <H3><A NAME="ORIENTATION">Setting the Orientation</A></H3>
 269
 270 <P>The <CODE>-o landscape</CODE> option will rotate the page 90
 271 degrees to print in landscape orientation:</P>
 272
 273 <PRE CLASS="command">
 274 lp -o landscape filename
 275 lpr -o landscape filename
 276 </PRE>
 277
 278 <P>The <CODE>-o orientation-requested=N</CODE> option rotates the
 279 page depending on the value of N:</P>
 280
 281 <UL>
 282
 283         <LI><CODE>-o orientation-requested=3</CODE> - portrait
 284         orientation (no rotation)</LI>
 285
 286         <LI><CODE>-o orientation-requested=4</CODE> - landscape
 287         orientation (90 degrees)</LI>
 288
 289         <LI><CODE>-o orientation-requested=5</CODE> - reverse
 290         landscape or seascape orientation (270 degrees)</LI>
 291
 292         <LI><CODE>-o orientation-requested=6</CODE> - reverse
 293         portrait or upside-down orientation (180 degrees)</LI>
 294
 295 </UL>
 296
 297 <H3><A NAME="SIDES">Printing On Both Sides of the Paper</A></H3>
 298
 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
 305 pages:</P>
 306
 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
 311 </PRE>
 312
 313 <P>The default is to print single-sided:</P>
 314
 315 <PRE CLASS="command">
 316 lp -o sides=one-sided filename
 317 lpr -o sides=one-sided filename
 318 </PRE>
 319
 320 <H3><A NAME="JOBSHEETS">Selecting the Banner Page(s)</A></H3>
 321
 322 <P>The <CODE>-o jobsheets=start,end</CODE> option sets the banner
 323 page(s) to use for a job:</P>
 324
 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
 329 </PRE>
 330
 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>
 334
 335 <P>The available banner pages depend on the local system
 336 configuration; CUPS includes the following banner files:</P>
 337
 338 <UL>
 339
 340         <LI><CODE>none</CODE> - Do not produce a banner page.
 341
 342         <LI><CODE>classified</CODE> - A banner page with a "classified"
 343         label at the top and bottom.
 344
 345         <LI><CODE>confidential</CODE> - A banner page with a
 346         "confidential" label at the top and bottom.
 347
 348         <LI><CODE>secret</CODE> - A banner page with a "secret" label
 349         at the top and bottom.
 350
 351         <LI><CODE>standard</CODE> - A banner page with no label at the
 352         top and bottom.
 353
 354         <LI><CODE>topsecret</CODE> - A banner page with a "top secret"
 355         label at the top and bottom.
 356
 357         <LI><CODE>unclassified</CODE> - A banner page with an
 358         "unclassified" label at the top and bottom.
 359
 360 </UL>
 361
 362
 363 <H3><A NAME="OUTPUTORDER">Specifying the Output Order</A></H3>
 364
 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>
 366
 367
 368 <H3><A NAME="PAGERANGES">Selecting a Range of Pages</A></H3>
 369
 370 <P>The <CODE>-o page-ranges=pages</CODE> option selects a range
 371 of pages for printing:</P>
 372
 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
 378 </PRE>
 379
 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.
 384
 385 <P>The default is to print all pages.
 386
 387 <H3><A NAME="PAGESET">Selecting Even or Odd Pages</A></H3>
 388
 389 <P>Use the <CODE>-o page-set=set</CODE> option to select the even or odd pages:</P>
 390
 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
 395 </PRE>
 396
 397 <P>The default is to print all pages.
 398
 399 <H3><A NAME="NUMBERUP">N-Up Printing</A></H3>
 400
 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>
 405
 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
 411 </PRE>
 412
 413 <P>The <CODE>-o page-border=value</CODE> option chooses the
 414 border to draw around each page:</P>
 415
 416 <UL>
 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>
 422 </UL>
 423
 424 <P>The <CODE>-o number-up-layout=value</CODE> option chooses the
 425 layout of the pages on each output page:</P>
 426
 427 <UL>
 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>
 436 </UL>
 437
 438 <H3><A NAME="FITPLOT">Scaling to Fit</A></H3>
 439
 440 <P>The <CODE>-o fitplot</CODE> option specifies that the document
 441 should be scaled to fit on the page:</P>
 442
 443 <PRE CLASS="command">
 444 lp -o fitplot filename
 445 lpr -o fitplot filename
 446 </PRE>
 447
 448 <P>The default is to use the size specified in the file.</P>
 449
 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>
 453
 454 <H3><A NAME="RAW">Raw or Unfiltered Output</A></H3>
 455
 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>
 460
 461 <PRE CLASS="command">
 462 lp -o raw filename
 463 lpr -o raw filename
 464 </PRE>
 465
 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>
 468
 469 <PRE CLASS="command">
 470 lpr -l filename
 471 </PRE>
 472
 473
 474 <H2 CLASS="title"><A NAME="TEXTOPTIONS">Text Options</A></H2>
 475
 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>
 479
 480 <H3><A NAME="CPI">Setting the Number of Characters Per Inch</A></H3>
 481
 482 <P>The <CODE>-o cpi=value</CODE> option sets the number of
 483 characters per inch:</P>
 484
 485 <PRE CLASS="command">
 486 lp -o cpi=10 filename
 487 lp -o cpi=12 filename
 488 lpr -o cpi=17 filename
 489 </PRE>
 490
 491 <P>The default characters per inch is 10.</P>
 492
 493 <H3><A NAME="LPI">Setting the Number of Lines Per Inch</A></H3>
 494
 495 <P>The <CODE>-o lpi=value</CODE> option sets the number of lines
 496 per inch:</P>
 497
 498 <PRE CLASS="command">
 499 lp -o lpi=6 filename
 500 lpr -o lpi=8 filename
 501 </PRE>
 502
 503 <P>The default lines per inch is 6.</P>
 504
 505 <H3><A NAME="COLUMNS">Setting the Number of Columns</A></H3>
 506
 507 <P>The <CODE>-o columns=value</CODE> option sets the number of
 508 text columns:</P>
 509
 510 <PRE CLASS="command">
 511 lp -o columns=2 filename
 512 lpr -o columns=3 filename
 513 </PRE>
 514
 515 <P>The default number of columns is 1.</P>
 516
 517 <H3><A NAME="MARGINS">Setting the Page Margins</A></H3>
 518
 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
 523 margins:</P>
 524
 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
 531 </PRE>
 532
 533 <P>The <CODE>value</CODE> argument is the margin in points; each
 534 point is 1/72 inch or 0.35mm.</P>
 535
 536 <H3><A NAME="PRETTYPRINT">Pretty Printing</A></H3>
 537
 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>
 542
 543 <PRE CLASS="command">
 544 lp -o prettyprint filename
 545 lpr -o prettyprint filename
 546 </PRE>
 547
 548 </BODY>
 549 </HTML>