[thirdparty/cups.git] / doc / help / options.html

<HTML>
<!-- SECTION: Getting Started -->
<HEAD>
	<TITLE>Command-Line Printing and Options</TITLE>
	<LINK REL="STYLESHEET" TYPE="text/css" HREF="../cups-printable.css">
</HEAD>
<BODY>

<H1 CLASS="title">Command-Line Printing and Options</H1>

<P>CUPS provides both the System V (<A
HREF="man-lp.html">lp(1)</A>) and Berkeley (<A
HREF="man-lpr.html">lpr(1)</A>) printing commands for printing
files. In addition, it supported a large number of standard and
printer-specific options that allow you to control how and where
files are printed.</P>


<H2 CLASS="title"><A NAME="BASICS">Printing Files</A></H2>

<P>CUPS understands many different types of files directly,
including text, PostScript, PDF, and image files. This allows you
to print from inside your applications or at the command-line,
whichever is most convenient! Type either of the following
commands to print a file to the default (or only) printer on the
system:</P>

<PRE CLASS="command">
lp filename
lpr filename
</PRE>

<H3><A NAME="PRINTER">Choosing a Printer</A></H3>

<P>Many systems will have more than one printer available to the
user. These printers can be attached to the local system via a
parallel, serial, or USB port, or available over the network. Use
the <A HREF="man-lpstat.html">lpstat(1)</A> command to see a list
of available printers:</P>

<PRE CLASS="command">
lpstat -p -d
</PRE>

<P>The <CODE>-p</CODE> option specifies that you want to see a
list of printers, and the <CODE>-d</CODE> option reports the
current default printer or class.</P>

<P>Use the <CODE>-d</CODE> option with the <B>lp</B> command to
print to a specific printer:</P>

<PRE CLASS="command">
lp -d printer filename
</PRE>

<P>or the <CODE>-P</CODE> option with the <B>lpr</B> command:</P>

<PRE CLASS="command">
lpr -P printer filename
</PRE>

<H3><A NAME="DEFAULT">Setting the Default Printer</A></H3>

<P>If you normally use a particular printer, you can tell CUPS to
use it by default using the <A
HREF="man-lpoptions.html">lpoptions(1)</A> command:</P>

<PRE CLASS="command">
lpoptions -d printer
</PRE>

<H3><A NAME="PIPE">Printing the Output of a Program</A></H3>

<P>Both the <B>lp</B> and <B>lpr</B> commands support printing
from the standard input:</P>

<PRE CLASS="command">
program | lp
program | lp -d printer
program | lpr
program | lpr -P printer
</PRE>

<P>If the program does not provide any output, then nothing will
be queued for printing.</P>

<H3><A NAME="WITHOPTIONS">Specifying Printer Options</A></H3>

<P>For many types of files, the default printer options may be
sufficient for your needs. However, there may be times when you
need to change the options for a particular file you are
printing.</P>

<P>The <B>lp</B> and <B>lpr</B> commands allow you to pass
printer options using the <CODE>-o</CODE> option:</P>

<PRE CLASS="command">
lp -o landscape -o fit-to-page -o media=A4 filename.jpg
lpr -o landscape -o fit-to-page -o media=A4 filename.jpg
</PRE>

<P>The available printer options vary depending on the printer.
The standard options are described in the "<A
HREF="#OPTIONS">Standard Printing Options</A>" section
below. Printer-specific options are also available and can be
listed using the <B>lpoptions</B> command:</P>

<PRE CLASS="command">
lpoptions -p printer -l
</PRE>

<H3><A NAME="INSTANCES">Creating Saved Options</A></H3>

<P>Saved options are supported in CUPS through <em>printer
instances</em>. Printer instances are, as their name implies, copies
of a printer that have certain options associated with them. Use the
<B>lpoptions</B> command to create a printer instance:</P>

<PRE CLASS="command">
lpoptions -p printer/instance -o name=value ...
</PRE>

<P>The <CODE>-p printer/instance</CODE> option provides the name of
the instance, which is always the printer name, a slash, and the
instance name which can contain any printable characters except
space and slash. The remaining options are then associated with the
instance instead of the main queue. For example, the following
command creates a duplex instance of the LaserJet queue:</P>

<PRE CLASS="command">
lpoptions -p LaserJet/duplex -o sides=two-sided-long-edge
</PRE>

<P>Instances <em>do not</em> inherit lpoptions from the main
queue.</P>

<H3><A NAME="COPIES">Printing Multiple Copies</A></H3>

<P>Both the <B>lp</B> and <B>lpr</B> commands have options for
printing more than one copy of a file:</P>

<PRE CLASS="command">
lp -n <EM>num-copies</EM> filename
lpr -#<EM>num-copies</EM> filename
</PRE>

<P>Copies are normally <EM>not</EM> collated for you. Use the
<CODE>-o collate=true</CODE> option to get collated copies:</P>

<PRE CLASS="command">
lp -n <EM>num-copies</EM> -o collate=true filename
lpr -#<EM>num-copies</EM> -o collate=true filename
</PRE>


<H2 CLASS="title"><A NAME="CANCEL">Canceling a Print Job</A></H2>

<P>The <A HREF="man-cancel.html">cancel(1)</A> and <A
HREF="man-lprm.html">lprm(1)</A> commands cancel a print job:</P>

<PRE CLASS="command">
cancel <EM>job-id</EM>
lprm <EM>job-id</EM>
</PRE>

<P>The <EM>job-id</EM> is the number that was reported to you by
the <B>lp</B> command. You can also get the job ID using the <A
HREF="man-lpq.html">lpq(1)</A> or <A
HREF="man-lpstat.html">lpstat</A> commands:</P>

<PRE CLASS="command">
lpq
lpstat
</PRE>


<H2 CLASS="title"><A NAME="LPMOVE">Moving a Print Job</A></H2>

<P>The <A HREF="man-lpmove.html">lpmove(8)</A> command moves a print
job to a new printer or class:</P>

<PRE CLASS="command">
lpmove <EM>job-id</EM> <i>destination</i>
</PRE>

<P>The <EM>job-id</EM> is the number that was reported to you by
the <B>lp</B> or <B>lpstat</B> commands. <i>Destination</i> is the
name of a printer or class that you want to actually print the job.

<BLOCKQUOTE><B>Note:</B>

<P>The <B>lpmove</B> command is located in the system command
directory (typically <VAR>/usr/sbin</VAR> or <VAR>/usr/local/sbin</VAR>),
and so may not be in your command path. Specify the full path to the
command if you get a "command not found" error, for example:

<PRE CLASS="command">
/usr/sbin/lpmove foo-123 bar
</PRE>

</BLOCKQUOTE>


<H2 CLASS="title"><A NAME="OPTIONS">Standard Printing Options</A></H2>

<P>The following options apply when printing all types of
files.</P>

<H3><A NAME="MEDIA">Selecting the Media Size, Type, and Source</A></H3>

<P>The <CODE>-o media=xyz</CODE> option sets the media size,
type, and/or source:</P>

<PRE CLASS="command">
lp -o media=Letter filename
lp -o media=Letter,MultiPurpose filename
lpr -o media=Letter,Transparency filename
lpr -o media=Letter,MultiPurpose,Transparency filename
</PRE>

<P>The available media sizes, types, and sources depend on the
printer, but most support the following options (case is not
significant):</P>

<UL>

	<LI><CODE>Letter</CODE> - US Letter (8.5x11 inches, or 216x279mm)

	<LI><CODE>Legal</CODE> - US Legal (8.5x14 inches, or 216x356mm)

	<LI><CODE>A4</CODE> - ISO A4 (8.27x11.69 inches, or 210x297mm)

	<LI><CODE>COM10</CODE> - US #10 Envelope (9.5x4.125 inches, or
	241x105mm)

	<LI><CODE>DL</CODE> - ISO DL Envelope (8.66x4.33 inches, or 220x110mm)

	<LI><CODE>Transparency</CODE> - Transparency media type or source

	<LI><CODE>Upper</CODE> - Upper paper tray

	<LI><CODE>Lower</CODE> - Lower paper tray

	<LI><CODE>MultiPurpose</CODE> - Multi-purpose paper tray

	<LI><CODE>LargeCapacity</CODE> - Large capacity paper tray

</UL>

<P>The actual options supported are defined in the printer's PPD
file in the <CODE>PageSize</CODE>, <CODE>InputSlot</CODE>, and
<CODE>MediaType</CODE> options. You can list them using the
<B>lpoptions(1)</B> command:</P>

<PRE CLASS="command">
lpoptions -p printer -l
</PRE>

<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>

<PRE CLASS="command">
lp -o media=Custom.<EM>WIDTH</EM>x<EM>LENGTH</EM> filename
lp -o media=Custom.<EM>WIDTH</EM>x<EM>LENGTH</EM>in filename
lp -o media=Custom.<EM>WIDTH</EM>x<EM>LENGTH</EM>cm filename
lp -o media=Custom.<EM>WIDTH</EM>x<EM>LENGTH</EM>mm filename
</PRE>

<P>where "WIDTH" and "LENGTH" are the width and length of the media in points, inches, centimeters, or millimeters, respectively.</P>


<H3><A NAME="ORIENTATION">Setting the Orientation</A></H3>

<P>The <CODE>-o landscape</CODE> option will rotate the page 90
degrees to print in landscape orientation:</P>

<PRE CLASS="command">
lp -o landscape filename
lpr -o landscape filename
</PRE>

<P>The <CODE>-o orientation-requested=N</CODE> option rotates the
page depending on the value of N:</P>

<UL>

	<LI><CODE>-o orientation-requested=3</CODE> - portrait
	orientation (no rotation)</LI>

	<LI><CODE>-o orientation-requested=4</CODE> - landscape
	orientation (90 degrees)</LI>

	<LI><CODE>-o orientation-requested=5</CODE> - reverse
	landscape or seascape orientation (270 degrees)</LI>

	<LI><CODE>-o orientation-requested=6</CODE> - reverse
	portrait or upside-down orientation (180 degrees)</LI>

</UL>


<H3><A NAME="SIDES">Printing On Both Sides of the Paper</A></H3>

<P>The <CODE>-o sides=two-sided-short-edge</CODE> and <CODE>-o
sides=two-sided-long-edge</CODE> options will enable two-sided
printing on the printer if the printer supports it. The <CODE>-o
sides=two-sided-short-edge</CODE> option is suitable for
landscape pages, while the <CODE>-o
sides=two-sided-long-edge</CODE> option is suitable for portrait
pages:</P>

<PRE CLASS="command">
lp -o sides=two-sided-short-edge filename
lp -o sides=two-sided-long-edge filename
lpr -o sides=two-sided-long-edge filename
</PRE>

<P>The default is to print single-sided:</P>

<PRE CLASS="command">
lp -o sides=one-sided filename
lpr -o sides=one-sided filename
</PRE>


<H3><A NAME="JOBSHEETS">Selecting the Banner Page(s)</A></H3>

<P>The <CODE>-o job-sheets=start,end</CODE> option sets the banner
page(s) to use for a job:</P>

<PRE CLASS="command">
lp -o job-sheets=none filename
lp -o job-sheets=standard filename
lpr -o job-sheets=classified,classified filename
</PRE>

<P>If only one banner file is specified, it will be printed
before the files in the job. If a second banner file is
specified, it is printed after the files in the job.</P>

<P>The available banner pages depend on the local system
configuration; CUPS includes the following banner files:</P>

<UL>

	<LI><CODE>none</CODE> - Do not produce a banner page.

	<LI><CODE>classified</CODE> - A banner page with a "classified"
	label at the top and bottom.

	<LI><CODE>confidential</CODE> - A banner page with a
	"confidential" label at the top and bottom.

	<LI><CODE>secret</CODE> - A banner page with a "secret" label
	at the top and bottom.

	<LI><CODE>standard</CODE> - A banner page with no label at the
	top and bottom.

	<LI><CODE>topsecret</CODE> - A banner page with a "top secret"
	label at the top and bottom.

	<LI><CODE>unclassified</CODE> - A banner page with an
	"unclassified" label at the top and bottom.

</UL>


<H3><A NAME="JOBHOLDUNTIL">Holding Jobs for Later Printing</A></H3>

<P>The <CODE>-o job-hold-until=when</CODE> option tells CUPS to
delay printing until the "when" time, which can be one of the
following:</P>

<UL>

	<LI><CODE>-o job-hold-until=indefinite</CODE>; print only
	after released by the user or an administrator</LI>

	<LI><CODE>-o job-hold-until=day-time</CODE>; print from
	6am to 6pm local time</LI>

	<LI><CODE>-o job-hold-until=night</CODE>; print from
	6pm to 6am local time</LI>

	<LI><CODE>-o job-hold-until=second-shift</CODE>; print from
	4pm to 12am local time</LI>

	<LI><CODE>-o job-hold-until=third-shift</CODE>; print from
	12am to 8am local time</LI>

	<LI><CODE>-o job-hold-until=weekend</CODE>; print on Saturday
	or Sunday</LI>

	<LI><CODE>-o job-hold-until=HH:MM</CODE>; print at the specified
	UTC time</LI>

</UL>

<H3><A NAME="RELEASEJOB">Releasing Held Jobs</A></H3>

<P>Aside from the web interface, you can use the <B>lp</B> command
to release a held job:</P>

<PRE CLASS="command">
lp -i <em>job-id</em> -H resume
</PRE>

<P>where "job-id" is the job ID reported by the <B>lpstat</B>
command.</P>


<H3><A NAME="JOBPRIORITY">Setting the Job Priority</A></H3>

<P>The <CODE>-o job-priority=NNN</CODE> option tells CUPS to
assign a priority to your job from 1 (lowest) to 100 (highest),
which influences where the job appears in the print queue. Higher
priority jobs are printed before lower priority jobs, however
submitting a new job with a high priority will not interrupt an
already printing job.</P>


<H3><A NAME="OUTPUTORDER">Specifying the Output Order</A></H3>

<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>


<H3><A NAME="PAGERANGES">Selecting a Range of Pages</A></H3>

<P>The <CODE>-o page-ranges=pages</CODE> option selects a range
of pages for printing:</P>

<PRE CLASS="command">
lp -o page-ranges=1 filename
lp -o page-ranges=1-4 filename
lp -o page-ranges=1-4,7,9-12 filename
lpr -o page-ranges=1-4,7,9-12 filename
</PRE>

<P>As shown above, the <CODE>pages</CODE> value can be a single page, a
range of pages, or a collection of page numbers and ranges separated by
commas. The pages will always be printed in ascending order, regardless
of the order of the pages in the <CODE>page-ranges</CODE> option.

<P>The default is to print all pages.

<blockquote><b>Note:</b>

<p>The page numbers used by <code>page-ranges</code> refer to the output
pages and not the document's page numbers. Options like <code>number-up</code>
can make the output page numbering not match the document page numbers.</p>

</blockquote>


<H3><A NAME="NUMBERUP">N-Up Printing</A></H3>

<P>The <CODE>-o number-up=value</CODE> option selects N-Up
printing. N-Up printing places multiple document pages on a
single printed page. CUPS supports 1, 2, 4, 6, 9, and 16-Up
formats; the default format is 1-Up:</P>

<PRE CLASS="command">
lp -o number-up=1 filename
lp -o number-up=2 filename
lp -o number-up=4 filename
lpr -o number-up=16 filename
</PRE>

<P>The <CODE>-o page-border=value</CODE> option chooses the
border to draw around each page:</P>

<UL>
	<LI><CODE>-o page-border=double</CODE>; draw two hairline borders around each page</LI>
	<LI><CODE>-o page-border=double-thick</CODE>; draw two 1pt borders around each page</LI>
	<LI><CODE>-o page-border=none</CODE>; do not draw a border (default)</LI>
	<LI><CODE>-o page-border=single</CODE>; draw one hairline border around each page</LI>
	<LI><CODE>-o page-border=single-thick</CODE>; draw one 1pt border around each page</LI>
</UL>

<P>The <CODE>-o number-up-layout=value</CODE> option chooses the
layout of the pages on each output page:</P>

<UL>
	<LI><CODE>-o number-up-layout=btlr</CODE>; Bottom to top, left to right</LI>
	<LI><CODE>-o number-up-layout=btrl</CODE>; Bottom to top, right to left</LI>
	<LI><CODE>-o number-up-layout=lrbt</CODE>; Left to right, bottom to top</LI>
	<LI><CODE>-o number-up-layout=lrtb</CODE>; Left to right, top to bottom (default)</LI>
	<LI><CODE>-o number-up-layout=rlbt</CODE>; Right to left, bottom to top</LI>
	<LI><CODE>-o number-up-layout=rltb</CODE>; Right to left, top to bottom</LI>
	<LI><CODE>-o number-up-layout=tblr</CODE>; Top to bottom, left to right</LI>
	<LI><CODE>-o number-up-layout=tbrl</CODE>; Top to bottom, right to left</LI>
</UL>

<H3><A NAME="FIT_TO_PAGE">Scaling to Fit</A></H3>

<P>The <CODE>-o fit-to-page</CODE> option specifies that the document
should be scaled to fit on the page:</P>

<PRE CLASS="command">
lp -o fit-to-page filename
lpr -o fit-to-page filename
</PRE>

<P>The default is to use the size specified in the file.</P>

<BLOCKQUOTE><B>Note:</B>

<P>This feature depends upon an accurate size in
the print file. If no size is given in the file, the page may be
scaled incorrectly!

</BLOCKQUOTE>

<H3><A NAME="OUTPUTORDER">Printing in Reverse Order</A></H3>

<P>The <CODE>-o outputorder=reverse</CODE> option will print the
pages in reverse order:</P>

<PRE CLASS="command">
lp -o outputorder=reverse filename
lpr -o outputorder=reverse filename
</PRE>

<P>Similarly, the <CODE>-o outputorder=normal</CODE> option will
print starting with page 1:</P>

<PRE CLASS="command">
lp -o outputorder=normal filename
lpr -o outputorder=normal filename
</PRE>

<P>The default is <CODE>-o outputorder=normal</CODE> for
printers that print face down and <CODE>-o outputorder=reverse</CODE>
for printers that print face up.

<H3><A NAME="MIRROR">Printing Mirrored Pages</A></H3>

<P>The <CODE>-o mirror</CODE> option flips each page along the
vertical axis to produce a mirrored image:</P>

<PRE CLASS="command">
lp -o mirror filename
lpr -o mirror filename
</PRE>

<P>This is typically used when printing on T-shirt transfer
media or sometimes on transparencies.</P>

</BODY>
</HTML>
Commit	Line	Data
4744bd90	1	<HTML>
	2	<!-- SECTION: Getting Started -->
	3	<HEAD>
b94498cf	4	<TITLE>Command-Line Printing and Options</TITLE>
178cb736	5	<LINK REL="STYLESHEET" TYPE="text/css" HREF="../cups-printable.css">
4744bd90	6	</HEAD>
	7	<BODY>
	8
178cb736 MS	9	<H1 CLASS="title">Command-Line Printing and Options</H1>
178cb736 MS	10
4744bd90	11	<P>CUPS provides both the System V (<A
	12	HREF="man-lp.html">lp(1)</A>) and Berkeley (<A
	13	HREF="man-lpr.html">lpr(1)</A>) printing commands for printing
	14	files. In addition, it supported a large number of standard and
	15	printer-specific options that allow you to control how and where
	16	files are printed.</P>
	17
	18
	19	<H2 CLASS="title"><A NAME="BASICS">Printing Files</A></H2>
	20
	21	<P>CUPS understands many different types of files directly,
	22	including text, PostScript, PDF, and image files. This allows you
	23	to print from inside your applications or at the command-line,
	24	whichever is most convenient! Type either of the following
	25	commands to print a file to the default (or only) printer on the
	26	system:</P>
	27
	28	<PRE CLASS="command">
	29	lp filename
	30	lpr filename
	31	</PRE>
	32
	33	<H3><A NAME="PRINTER">Choosing a Printer</A></H3>
	34
	35	<P>Many systems will have more than one printer available to the
	36	user. These printers can be attached to the local system via a
	37	parallel, serial, or USB port, or available over the network. Use
	38	the <A HREF="man-lpstat.html">lpstat(1)</A> command to see a list
	39	of available printers:</P>
	40
	41	<PRE CLASS="command">
	42	lpstat -p -d
	43	</PRE>
	44
	45	<P>The <CODE>-p</CODE> option specifies that you want to see a
	46	list of printers, and the <CODE>-d</CODE> option reports the
	47	current default printer or class.</P>
	48
	49	<P>Use the <CODE>-d</CODE> option with the <B>lp</B> command to
	50	print to a specific printer:</P>
	51
	52	<PRE CLASS="command">
	53	lp -d printer filename
	54	</PRE>
	55
	56	<P>or the <CODE>-P</CODE> option with the <B>lpr</B> command:</P>
	57
	58	<PRE CLASS="command">
	59	lpr -P printer filename
	60	</PRE>
	61
	62	<H3><A NAME="DEFAULT">Setting the Default Printer</A></H3>
	63
	64	<P>If you normally use a particular printer, you can tell CUPS to
	65	use it by default using the <A
	66	HREF="man-lpoptions.html">lpoptions(1)</A> command:</P>
	67
	68	<PRE CLASS="command">
	69	lpoptions -d printer
	70	</PRE>
	71
	72	<H3><A NAME="PIPE">Printing the Output of a Program</A></H3>
	73
	74	<P>Both the <B>lp</B> and <B>lpr</B> commands support printing
75	from the standard input:</P>
76
77	<PRE CLASS="command">
78	program \| lp
79	program \| lp -d printer
80	program \| lpr
81	program \| lpr -P printer
82	</PRE>
83
84	<P>If the program does not provide any output, then nothing will
85	be queued for printing.</P>
86
87	<H3><A NAME="WITHOPTIONS">Specifying Printer Options</A></H3>
88
89	<P>For many types of files, the default printer options may be
90	sufficient for your needs. However, there may be times when you
91	need to change the options for a particular file you are
92	printing.</P>
93
94	<P>The <B>lp</B> and <B>lpr</B> commands allow you to pass
95	printer options using the <CODE>-o</CODE> option:</P>
96
97	<PRE CLASS="command">
3e7fe0ca MS	98	lp -o landscape -o fit-to-page -o media=A4 filename.jpg
3e7fe0ca MS	99	lpr -o landscape -o fit-to-page -o media=A4 filename.jpg
4744bd90	100	</PRE>
	101
	102	<P>The available printer options vary depending on the printer.
	103	The standard options are described in the "<A
	104	HREF="#OPTIONS">Standard Printing Options</A>" section
b86bc4cf	105	below. Printer-specific options are also available and can be
	106	listed using the <B>lpoptions</B> command:</P>
	107
	108	<PRE CLASS="command">
	109	lpoptions -p printer -l
	110	</PRE>
4744bd90	111
f42414bf	112	<H3><A NAME="INSTANCES">Creating Saved Options</A></H3>
	113
	114	<P>Saved options are supported in CUPS through <em>printer
	115	instances</em>. Printer instances are, as their name implies, copies
	116	of a printer that have certain options associated with them. Use the
	117	<B>lpoptions</B> command to create a printer instance:</P>
	118
	119	<PRE CLASS="command">
	120	lpoptions -p printer/instance -o name=value ...
	121	</PRE>
	122
	123	<P>The <CODE>-p printer/instance</CODE> option provides the name of
	124	the instance, which is always the printer name, a slash, and the
	125	instance name which can contain any printable characters except
	126	space and slash. The remaining options are then associated with the
	127	instance instead of the main queue. For example, the following
	128	command creates a duplex instance of the LaserJet queue:</P>
	129
	130	<PRE CLASS="command">
	131	lpoptions -p LaserJet/duplex -o sides=two-sided-long-edge
	132	</PRE>
	133
	134	<P>Instances <em>do not</em> inherit lpoptions from the main
	135	queue.</P>
	136
4744bd90	137	<H3><A NAME="COPIES">Printing Multiple Copies</A></H3>
	138
	139	<P>Both the <B>lp</B> and <B>lpr</B> commands have options for
	140	printing more than one copy of a file:</P>
	141
	142	<PRE CLASS="command">
7ff4fea9 MS	143	lp -n <EM>num-copies</EM> filename
7ff4fea9 MS	144	lpr -#<EM>num-copies</EM> filename
4744bd90	145	</PRE>
	146
	147	<P>Copies are normally <EM>not</EM> collated for you. Use the
40df01c1	148	<CODE>-o collate=true</CODE> option to get collated copies:</P>
4744bd90	149
4744bd90	150	<PRE CLASS="command">
40df01c1 MS	151	lp -n <EM>num-copies</EM> -o collate=true filename
40df01c1 MS	152	lpr -#<EM>num-copies</EM> -o collate=true filename
4744bd90	153	</PRE>
	154
	155
	156	<H2 CLASS="title"><A NAME="CANCEL">Canceling a Print Job</A></H2>
	157
	158	<P>The <A HREF="man-cancel.html">cancel(1)</A> and <A
	159	HREF="man-lprm.html">lprm(1)</A> commands cancel a print job:</P>
	160
	161	<PRE CLASS="command">
7ff4fea9 MS	162	cancel <EM>job-id</EM>
7ff4fea9 MS	163	lprm <EM>job-id</EM>
4744bd90	164	</PRE>
4744bd90	165
7ff4fea9	166	<P>The <EM>job-id</EM> is the number that was reported to you by
4744bd90	167	the <B>lp</B> command. You can also get the job ID using the <A
	168	HREF="man-lpq.html">lpq(1)</A> or <A
	169	HREF="man-lpstat.html">lpstat</A> commands:</P>
	170
	171	<PRE CLASS="command">
	172	lpq
	173	lpstat
	174	</PRE>
	175
	176
b94498cf	177	<H2 CLASS="title"><A NAME="LPMOVE">Moving a Print Job</A></H2>
	178
	179	<P>The <A HREF="man-lpmove.html">lpmove(8)</A> command moves a print
	180	job to a new printer or class:</P>
	181
	182	<PRE CLASS="command">
7ff4fea9	183	lpmove <EM>job-id</EM> <i>destination</i>
b94498cf	184	</PRE>
b94498cf	185
7ff4fea9	186	<P>The <EM>job-id</EM> is the number that was reported to you by
b94498cf	187	the <B>lp</B> or <B>lpstat</B> commands. <i>Destination</i> is the
	188	name of a printer or class that you want to actually print the job.
	189
	190	<BLOCKQUOTE><B>Note:</B>
	191
	192	<P>The <B>lpmove</B> command is located in the system command
	193	directory (typically <VAR>/usr/sbin</VAR> or <VAR>/usr/local/sbin</VAR>),
	194	and so may not be in your command path. Specify the full path to the
	195	command if you get a "command not found" error, for example:
	196
	197	<PRE CLASS="command">
	198	/usr/sbin/lpmove foo-123 bar
	199	</PRE>
	200
	201	</BLOCKQUOTE>
	202
	203
4744bd90	204	<H2 CLASS="title"><A NAME="OPTIONS">Standard Printing Options</A></H2>
	205
	206	<P>The following options apply when printing all types of
	207	files.</P>
	208
	209	<H3><A NAME="MEDIA">Selecting the Media Size, Type, and Source</A></H3>
	210
	211	<P>The <CODE>-o media=xyz</CODE> option sets the media size,
	212	type, and/or source:</P>
	213
	214	<PRE CLASS="command">
	215	lp -o media=Letter filename
	216	lp -o media=Letter,MultiPurpose filename
	217	lpr -o media=Letter,Transparency filename
	218	lpr -o media=Letter,MultiPurpose,Transparency filename
	219	</PRE>
	220
	221	<P>The available media sizes, types, and sources depend on the
	222	printer, but most support the following options (case is not
	223	significant):</P>
	224
	225	<UL>
	226
	227	<LI><CODE>Letter</CODE> - US Letter (8.5x11 inches, or 216x279mm)
	228
	229	<LI><CODE>Legal</CODE> - US Legal (8.5x14 inches, or 216x356mm)
	230
	231	<LI><CODE>A4</CODE> - ISO A4 (8.27x11.69 inches, or 210x297mm)
	232
	233	<LI><CODE>COM10</CODE> - US #10 Envelope (9.5x4.125 inches, or
	234	241x105mm)
	235
	236	<LI><CODE>DL</CODE> - ISO DL Envelope (8.66x4.33 inches, or 220x110mm)
	237
	238	<LI><CODE>Transparency</CODE> - Transparency media type or source
	239
	240	<LI><CODE>Upper</CODE> - Upper paper tray
	241
	242	<LI><CODE>Lower</CODE> - Lower paper tray
	243
	244	<LI><CODE>MultiPurpose</CODE> - Multi-purpose paper tray
	245
	246	<LI><CODE>LargeCapacity</CODE> - Large capacity paper tray
	247
	248	</UL>
	249
	250	<P>The actual options supported are defined in the printer's PPD
	251	file in the <CODE>PageSize</CODE>, <CODE>InputSlot</CODE>, and
	252	<CODE>MediaType</CODE> options. You can list them using the
	253	<B>lpoptions(1)</B> command:</P>
	254
	255	<PRE CLASS="command">
	256	lpoptions -p printer -l
	257	</PRE>
	258
b86bc4cf	259	<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>
	260
	261	<PRE CLASS="command">
7ff4fea9 MS	262	lp -o media=Custom.<EM>WIDTH</EM>x<EM>LENGTH</EM> filename
	263	lp -o media=Custom.<EM>WIDTH</EM>x<EM>LENGTH</EM>in filename
	264	lp -o media=Custom.<EM>WIDTH</EM>x<EM>LENGTH</EM>cm filename
	265	lp -o media=Custom.<EM>WIDTH</EM>x<EM>LENGTH</EM>mm filename
b86bc4cf	266	</PRE>
	267
	268	<P>where "WIDTH" and "LENGTH" are the width and length of the media in points, inches, centimeters, or millimeters, respectively.</P>
	269
	270
4744bd90	271	<H3><A NAME="ORIENTATION">Setting the Orientation</A></H3>
	272
	273	<P>The <CODE>-o landscape</CODE> option will rotate the page 90
	274	degrees to print in landscape orientation:</P>
	275
	276	<PRE CLASS="command">
	277	lp -o landscape filename
	278	lpr -o landscape filename
	279	</PRE>
	280
	281	<P>The <CODE>-o orientation-requested=N</CODE> option rotates the
	282	page depending on the value of N:</P>
	283
	284	<UL>
	285
	286	<LI><CODE>-o orientation-requested=3</CODE> - portrait
	287	orientation (no rotation)</LI>
	288
	289	<LI><CODE>-o orientation-requested=4</CODE> - landscape
	290	orientation (90 degrees)</LI>
	291
	292	<LI><CODE>-o orientation-requested=5</CODE> - reverse
	293	landscape or seascape orientation (270 degrees)</LI>
	294
	295	<LI><CODE>-o orientation-requested=6</CODE> - reverse
	296	portrait or upside-down orientation (180 degrees)</LI>
	297
	298	</UL>
	299
7ff4fea9	300
4744bd90	301	<H3><A NAME="SIDES">Printing On Both Sides of the Paper</A></H3>
	302
	303	<P>The <CODE>-o sides=two-sided-short-edge</CODE> and <CODE>-o
	304	sides=two-sided-long-edge</CODE> options will enable two-sided
	305	printing on the printer if the printer supports it. The <CODE>-o
	306	sides=two-sided-short-edge</CODE> option is suitable for
	307	landscape pages, while the <CODE>-o
	308	sides=two-sided-long-edge</CODE> option is suitable for portrait
	309	pages:</P>
	310
	311	<PRE CLASS="command">
	312	lp -o sides=two-sided-short-edge filename
	313	lp -o sides=two-sided-long-edge filename
	314	lpr -o sides=two-sided-long-edge filename
	315	</PRE>
	316
	317	<P>The default is to print single-sided:</P>
	318
	319	<PRE CLASS="command">
	320	lp -o sides=one-sided filename
	321	lpr -o sides=one-sided filename
	322	</PRE>
	323
7ff4fea9	324
4744bd90	325	<H3><A NAME="JOBSHEETS">Selecting the Banner Page(s)</A></H3>
4744bd90	326
eac3a0a0	327	<P>The <CODE>-o job-sheets=start,end</CODE> option sets the banner
4744bd90	328	page(s) to use for a job:</P>
	329
	330	<PRE CLASS="command">
	331	lp -o job-sheets=none filename
	332	lp -o job-sheets=standard filename
	333	lpr -o job-sheets=classified,classified filename
	334	</PRE>
	335
	336	<P>If only one banner file is specified, it will be printed
	337	before the files in the job. If a second banner file is
	338	specified, it is printed after the files in the job.</P>
	339
	340	<P>The available banner pages depend on the local system
	341	configuration; CUPS includes the following banner files:</P>
	342
	343	<UL>
	344
	345	<LI><CODE>none</CODE> - Do not produce a banner page.
	346
	347	<LI><CODE>classified</CODE> - A banner page with a "classified"
	348	label at the top and bottom.
	349
	350	<LI><CODE>confidential</CODE> - A banner page with a
	351	"confidential" label at the top and bottom.
	352
	353	<LI><CODE>secret</CODE> - A banner page with a "secret" label
	354	at the top and bottom.
	355
	356	<LI><CODE>standard</CODE> - A banner page with no label at the
	357	top and bottom.
	358
	359	<LI><CODE>topsecret</CODE> - A banner page with a "top secret"
	360	label at the top and bottom.
	361
	362	<LI><CODE>unclassified</CODE> - A banner page with an
	363	"unclassified" label at the top and bottom.
	364
	365	</UL>
	366
b86bc4cf	367
7ff4fea9 MS	368	<H3><A NAME="JOBHOLDUNTIL">Holding Jobs for Later Printing</A></H3>
	369
	370	<P>The <CODE>-o job-hold-until=when</CODE> option tells CUPS to
	371	delay printing until the "when" time, which can be one of the
	372	following:</P>
	373
	374	<UL>
	375
	376	<LI><CODE>-o job-hold-until=indefinite</CODE>; print only
	377	after released by the user or an administrator</LI>
	378
	379	<LI><CODE>-o job-hold-until=day-time</CODE>; print from
	380	6am to 6pm local time</LI>
	381
	382	<LI><CODE>-o job-hold-until=night</CODE>; print from
	383	6pm to 6am local time</LI>
	384
	385	<LI><CODE>-o job-hold-until=second-shift</CODE>; print from
	386	4pm to 12am local time</LI>
	387
	388	<LI><CODE>-o job-hold-until=third-shift</CODE>; print from
	389	12am to 8am local time</LI>
	390
	391	<LI><CODE>-o job-hold-until=weekend</CODE>; print on Saturday
	392	or Sunday</LI>
	393
	394	<LI><CODE>-o job-hold-until=HH:MM</CODE>; print at the specified
	395	UTC time</LI>
	396
	397	</UL>
	398
	399	<H3><A NAME="RELEASEJOB">Releasing Held Jobs</A></H3>
	400
	401	<P>Aside from the web interface, you can use the <B>lp</B> command
	402	to release a held job:</P>
	403
	404	<PRE CLASS="command">
	405	lp -i <em>job-id</em> -H resume
	406	</PRE>
	407
	408	<P>where "job-id" is the job ID reported by the <B>lpstat</B>
	409	command.</P>
	410
	411
	412	<H3><A NAME="JOBPRIORITY">Setting the Job Priority</A></H3>
	413
	414	<P>The <CODE>-o job-priority=NNN</CODE> option tells CUPS to
	415	assign a priority to your job from 1 (lowest) to 100 (highest),
	416	which influences where the job appears in the print queue. Higher
	417	priority jobs are printed before lower priority jobs, however
	418	submitting a new job with a high priority will not interrupt an
c8fef167	419	already printing job.</P>
7ff4fea9 MS	420
7ff4fea9 MS	421
b86bc4cf	422	<H3><A NAME="OUTPUTORDER">Specifying the Output Order</A></H3>
	423
	424	<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>
	425
	426
4744bd90	427	<H3><A NAME="PAGERANGES">Selecting a Range of Pages</A></H3>
	428
	429	<P>The <CODE>-o page-ranges=pages</CODE> option selects a range
	430	of pages for printing:</P>
	431
	432	<PRE CLASS="command">
	433	lp -o page-ranges=1 filename
	434	lp -o page-ranges=1-4 filename
	435	lp -o page-ranges=1-4,7,9-12 filename
	436	lpr -o page-ranges=1-4,7,9-12 filename
	437	</PRE>
	438
	439	<P>As shown above, the <CODE>pages</CODE> value can be a single page, a
	440	range of pages, or a collection of page numbers and ranges separated by
	441	commas. The pages will always be printed in ascending order, regardless
	442	of the order of the pages in the <CODE>page-ranges</CODE> option.
	443
	444	<P>The default is to print all pages.
	445
52f6f666 MS	446	<blockquote><b>Note:</b>
	447
	448	<p>The page numbers used by <code>page-ranges</code> refer to the output
	449	pages and not the document's page numbers. Options like <code>number-up</code>
	450	can make the output page numbering not match the document page numbers.</p>
	451
	452	</blockquote>
	453
	454
4744bd90	455	<H3><A NAME="NUMBERUP">N-Up Printing</A></H3>
	456
	457	<P>The <CODE>-o number-up=value</CODE> option selects N-Up
	458	printing. N-Up printing places multiple document pages on a
	459	single printed page. CUPS supports 1, 2, 4, 6, 9, and 16-Up
	460	formats; the default format is 1-Up:</P>
	461
	462	<PRE CLASS="command">
	463	lp -o number-up=1 filename
	464	lp -o number-up=2 filename
	465	lp -o number-up=4 filename
	466	lpr -o number-up=16 filename
	467	</PRE>
	468
	469	<P>The <CODE>-o page-border=value</CODE> option chooses the
	470	border to draw around each page:</P>
	471
	472	<UL>
	473	<LI><CODE>-o page-border=double</CODE>; draw two hairline borders around each page</LI>
	474	<LI><CODE>-o page-border=double-thick</CODE>; draw two 1pt borders around each page</LI>
	475	<LI><CODE>-o page-border=none</CODE>; do not draw a border (default)</LI>
	476	<LI><CODE>-o page-border=single</CODE>; draw one hairline border around each page</LI>
	477	<LI><CODE>-o page-border=single-thick</CODE>; draw one 1pt border around each page</LI>
	478	</UL>
	479
	480	<P>The <CODE>-o number-up-layout=value</CODE> option chooses the
	481	layout of the pages on each output page:</P>
	482
	483	<UL>
	484	<LI><CODE>-o number-up-layout=btlr</CODE>; Bottom to top, left to right</LI>
	485	<LI><CODE>-o number-up-layout=btrl</CODE>; Bottom to top, right to left</LI>
	486	<LI><CODE>-o number-up-layout=lrbt</CODE>; Left to right, bottom to top</LI>
	487	<LI><CODE>-o number-up-layout=lrtb</CODE>; Left to right, top to bottom (default)</LI>
	488	<LI><CODE>-o number-up-layout=rlbt</CODE>; Right to left, bottom to top</LI>
	489	<LI><CODE>-o number-up-layout=rltb</CODE>; Right to left, top to bottom</LI>
	490	<LI><CODE>-o number-up-layout=tblr</CODE>; Top to bottom, left to right</LI>
	491	<LI><CODE>-o number-up-layout=tbrl</CODE>; Top to bottom, right to left</LI>
	492	</UL>
	493
ed6e7faf	494	<H3><A NAME="FIT_TO_PAGE">Scaling to Fit</A></H3>
4744bd90	495
ed6e7faf	496	<P>The <CODE>-o fit-to-page</CODE> option specifies that the document
4744bd90	497	should be scaled to fit on the page:</P>
	498
	499	<PRE CLASS="command">
ed6e7faf MS	500	lp -o fit-to-page filename
ed6e7faf MS	501	lpr -o fit-to-page filename
4744bd90	502	</PRE>
	503
	504	<P>The default is to use the size specified in the file.</P>
	505
7ff4fea9 MS	506	<BLOCKQUOTE><B>Note:</B>
	507
	508	<P>This feature depends upon an accurate size in
4744bd90	509	the print file. If no size is given in the file, the page may be
7ff4fea9 MS	510	scaled incorrectly!
	511
	512	</BLOCKQUOTE>
	513
	514	<H3><A NAME="OUTPUTORDER">Printing in Reverse Order</A></H3>
	515
	516	<P>The <CODE>-o outputorder=reverse</CODE> option will print the
	517	pages in reverse order:</P>
	518
	519	<PRE CLASS="command">
	520	lp -o outputorder=reverse filename
	521	lpr -o outputorder=reverse filename
	522	</PRE>
	523
	524	<P>Similarly, the <CODE>-o outputorder=normal</CODE> option will
	525	print starting with page 1:</P>
	526
	527	<PRE CLASS="command">
	528	lp -o outputorder=normal filename
	529	lpr -o outputorder=normal filename
	530	</PRE>
	531
	532	<P>The default is <CODE>-o outputorder=normal</CODE> for
	533	printers that print face down and <CODE>-o outputorder=reverse</CODE>
	534	for printers that print face up.
	535
	536	<H3><A NAME="MIRROR">Printing Mirrored Pages</A></H3>
	537
	538	<P>The <CODE>-o mirror</CODE> option flips each page along the
c8fef167	539	vertical axis to produce a mirrored image:</P>
7ff4fea9 MS	540
	541	<PRE CLASS="command">
	542	lp -o mirror filename
	543	lpr -o mirror filename
	544	</PRE>
	545
	546	<P>This is typically used when printing on T-shirt transfer
	547	media or sometimes on transparencies.</P>
4744bd90	548
4744bd90	549	</BODY>
4744bd90	550	</HTML>