path: root/usr/src/man/man1/lp.1

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions and the original IEEE and The Open Group
.\" Standard, the original IEEE and The Open Group Standard is the referee
.\" document.  The original Standard can be obtained online at
.\" http://www.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved
.\"
.TH LP 1 "Feb 25, 2017"
.SH NAME
lp \- submit print request
.SH SYNOPSIS
.LP
.nf
\fBlp\fR [\fB-c\fR] [\fB-m\fR] [\fB-p\fR] [\fB-s\fR] [\fB-w\fR] [\fB-d\fR \fIdestination\fR] [\fB-f\fR \fIform-name\fR]
     [\fB-H\fR \fIspecial-handling\fR] [\fB-n\fR \fInumber\fR] [\fB-o\fR \fIoption\fR]
     [\fB-P\fR \fIpage-list\fR] [\fB-q\fR \fIpriority-level\fR]
     [\fB-S\fR \fIcharacter-set\fR | \fIprint-wheel\fR] [\fB-t\fR \fItitle\fR]
     [\fB-T\fR \fIcontent-type\fR [\fB-r\fR]] [\fB-y\fR \fImode-list\fR] [\fIfile\fR]...
.fi

.LP
.nf
\fBlp\fR \fB-i\fR \fIrequest-ID\fR... [\fB-c\fR] [\fB-m\fR] [\fB-p\fR] [\fB-s\fR] [\fB-w\fR]
     [\fB-d\fR \fIdestination\fR] [\fB-f\fR \fIform-name\fR] [\fB-H\fR \fIspecial-handling\fR]
     [\fB-n\fR \fInumber\fR] [\fB-o\fR \fIoption\fR] [\fB-P\fR \fIpage-list\fR]
     [\fB-q\fR \fIpriority-level\fR] [\fB-S\fR \fIcharacter-set\fR | \fIprint-wheel\fR]
     [\fB-t\fR \fItitle\fR] [\fB-T\fR \fIcontent-type\fR [\fB-r\fR]] [\fB-y\fR \fImode-list\fR]
.fi

.SH DESCRIPTION
.LP
The \fBlp\fR utility submits print requests to a destination. There are two
formats of the \fBlp\fR command.
.sp
.LP
The first form of \fBlp\fR prints files (\fIfile\fR) and associated information
(collectively called a \fIprint request\fR). If \fIfile\fR is not specified,
\fBlp\fR assumes the standard input. Use a hyphen (\fB\(mi\fR) with \fIfile\fR
to specify the standard input. Files are printed in the order in which they
appear on the command line.
.sp
.LP
The second form of \fBlp\fR changes print request options. This form of
\fBlp\fR can only be used with print services and protocols that support job
modification. The LP print service allows print requests to be modified when
they are in a queue local to the system that the lp commands was executed on.
The Internet Print Protocol (IPP) allows job modification on remote ipp print
services.
.sp
.LP
The print request identified by \fIrequest-ID\fR is changed according to the
printing options specified. The printing options available are the same as
those with the first form of the \fBlp\fR. If the request has finished printing
when the \fBlp\fR command is executed, the change is rejected. If the request
is in the process of printing, it is stopped and restarted from the beginning
(unless the \fB-P\fR option has been given).
.sp
.LP
The print client commands locate destination information using the "printers"
database in the name service switch. See \fBnsswitch.conf\fR(4),
\fBprinters\fR(4), and \fBprinters.conf\fR(4) for details.
.SH OPTIONS
.LP
Printers that have a 4.\fIx\fR or \fBBSD-based print server\fR are not
configured to handle \fBBSD\fR protocol extensions. \fBlp\fR handles print
requests sent to such destinations differently (see NOTES).
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-c\fR\fR
.ad
.RS 23n
Copies \fIfile\fR before printing.
.sp
Unless \fB-c\fR is specified, users should not remove any \fIfile\fR before the
print request has completely printed. Changes made to \fIfile\fR after the
print request is made but before it is printed might be reflected in the
printed output. \fIfile\fR is linked (as opposed to copied).
.RE

.sp
.ne 2
.na
\fB\fB-d\fR \fIdestination\fR\fR
.ad
.RS 23n
Prints \fIfile\fR on a specific destination. The \fB-d\fR option is used to set
the destination only when the job is first created. (\fBNote:\fR To move
existing jobs to a different destination, see \fBlpmove\fR(1M).)
\fIdestination\fR can be either a printer or a class of printers (see
\fBlpadmin\fR(1M)). Specify \fIdestination\fR using atomic, URI-style
(\fIscheme\fR://\fIendpoint\fR), or POSIX-style
(\fIserver\fR\fB:\fR\fIdestination\fR) names. See \fBprinters.conf\fR(4) for
more information.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR \fIform-name\fR\fR
.ad
.RS 23n
Prints \fIfile\fR on \fIform-name\fR. The \fBLP\fR print service ensures that
the form is mounted on the printer. The print request is rejected if the
printer does not support \fIform-name\fR, if \fIform-name\fR is not defined for
the system, or if the user is not allowed to use \fIform-name\fR (see
\fBlpforms\fR(1M)).
.RE

.sp
.ne 2
.na
\fB\fB-H\fR \fIspecial-handling\fR\fR
.ad
.RS 23n
Prints the print request according to the value of \fIspecial-handling\fR. The
following \fIspecial-handling\fR values are acceptable:
.sp
.ne 2
.na
\fB\fBhold\fR\fR
.ad
.RS 13n
Do not print the print request until notified. If printing has already begun,
stop it. Other print requests are placed ahead of a request that has been put
on hold (\fIheld print request\fR) until the print request is resumed.
.RE

.sp
.ne 2
.na
\fB\fBresume\fR\fR
.ad
.RS 13n
Resume a held print request. If the print request had begun to print when held,
it is the next print request printed, unless it is superseded by an
\fIimmediate\fR print request.
.RE

.sp
.ne 2
.na
\fB\fBimmediate\fR\fR
.ad
.RS 13n
Print the print request next. If more than one print request is assigned, the
most recent print request is printed next. If a print request is currently
printing on the desired printer, a \fBhold\fR request must be issued to allow
the immediate request to print. The \fBimmediate\fR request is only available
to \fBLP\fR administrators.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-i\fR \fIrequest-ID\fR\fR
.ad
.RS 23n
Changes options for the print request identified by \fIrequest-ID\fR. There
must be a space between \fB-i\fR and \fIrequest-ID\fR.
.sp
This option applies to jobs that are in a local queue on a print server. This
also applies to remote queues on when the remote print server supports IPP with
job modification.
.RE

.sp
.ne 2
.na
\fB\fB-m\fR\fR
.ad
.RS 23n
Sends mail after \fIfile\fR has printed (see \fBmail\fR(1)). By default, no
mail is sent upon normal completion of a print request.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR \fInumber\fR\fR
.ad
.RS 23n
Prints a specific number of copies of \fIfile\fR. Specify \fInumber\fR as a
digit. The default for \fInumber\fR is \fB1\fR.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR \fIoption\fR\fR
.ad
.RS 23n
Specifies printer-dependent \fIoptions\fR. Specify several options by
specifying \fB-o\fR \fIoption\fR multiple times (\fB-o\fR \fIoption\fR \fB-o\fR
\fIoption\fR \fB-o\fR \fIoption\fR ). Printer-dependent options can also be
specified using the \fB-o\fR keyletter once, followed by a list of options
enclosed in double quotes (\fB-o\fR"\fIoption\fR \fIoption option\fR").
.sp
\fIoption\fRs take the following forms:
.sp
.ne 2
.na
\fB\fIkey\fR\fB=\fR\fIvalue\fR\fR
.ad
.RS 13n
Associates information with the request for use by the backend print service.
The keys and values that can be used are specific to the backend print service
and queue configuration.
.RE

.sp
.ne 2
.na
\fB\fB[no]key\fR\fR
.ad
.RS 13n
 Associates boolean information with the request for use by the backend print
service. The keys that can be used are specific to the backend print service
and queue configuration.
.RE

The following options are commonly used with the LP print service:
.sp
.ne 2
.na
\fB\fBnobanner\fR\fR
.ad
.sp .6
.RS 4n
Does not print a banner page with the request. This option can be disallowed by
the \fBLP\fR administrator.
.sp
On a system that is configured with Trusted Extensions, use of this option
requires the \fBsolaris.print.nobanner\fR authorization.
.RE

.sp
.ne 2
.na
\fB\fBnofilebreak\fR\fR
.ad
.sp .6
.RS 4n
Prints multiple files without inserting a form feed between them.
.RE

.sp
.ne 2
.na
\fB\fBnolabels\fR\fR
.ad
.sp .6
.RS 4n
On a system that is configured with Trusted Extensions, specifies suppression
of page header and footer labels. Use of this option requires the
\fBsolaris.print.unlabeled\fR authorization.
.RE

.sp
.ne 2
.na
\fB\fBlength=\fR\fInumber\fR\fBi\fR | \fInumber\fR\fBc\fR | \fInumber\fR\fR
.ad
.sp .6
.RS 4n
Prints the print request with pages of a specific length in inches,
centimeters, or number of lines. Append the letter \fBi\fR for inches or
\fBc\fR for centimeters to \fInumber\fR. Indicate the number of lines by
specifying \fInumber\fR alone. \fBlength=66\fR indicates a page length of
\fB66\fR lines. \fBlength=11i\fR indicates a page length of \fB11\fR inches.
\fBlength=27.94c\fR indicates a page length of \fB27.94\fR centimeters.
.sp
This option can not be used with the \fB-f\fR option.
.RE

.sp
.ne 2
.na
\fB\fBwidth=\fR\fInumber\fR\fBi\fR | \fInumber\fR\fBc\fR | \fInumber\fR\fR
.ad
.sp .6
.RS 4n
Prints the print request with pages of a specific width in inches, centimeters,
or number of columns. Append the letter \fBi\fR for inches or \fBc\fR for
centimeters to \fInumber\fR. Indicate the number of columns by specifying
\fInumber\fR alone. \fBwidth=65\fR indicates a page width of \fB65\fR columns.
\fBwidth=6.5i\fR indicates a page width of \fB6.5\fR inches. \fBwidth=10c\fR
indicates a page width of \fB10\fR centimeters.
.sp
This option can not be used with the \fB-f\fR option.
.RE

.sp
.ne 2
.na
\fB\fBlpi=\fR\fInumber\fR\fR
.ad
.sp .6
.RS 4n
Prints the print request with the line pitch set to \fInumber\fR lines in an
inch. Use \fInumber\fR to specify the number of lines in an inch.
.sp
This option can not be used with the \fB-f\fR option.
.RE

.sp
.ne 2
.na
\fB\fBcpi=\fR\fIn\fR|\fBpica\fR|\fBelite\fR|\fBcompressed\fR\fR
.ad
.sp .6
.RS 4n
Prints the print request with the character pitch set to \fInumber\fR
characters in an inch. Use \fInumber\fR to specify the number of characters in
an inch. Use \fBpica\fR to set character pitch to pica (\fB10\fR characters per
inch), or \fBelite\fR to set character pitch to elite (\fB12\fR characters per
inch) Use \fBcompressed\fR to set character pitch to as many characters as the
printer can handle. There is no standard number of characters per inch for all
printers; see the \fBterminfo\fR database (see \fBterminfo\fR(4)) for the
default character pitch for your printer. This option can not be used with the
\fB-f\fR option.
.RE

.sp
.ne 2
.na
\fB\fBstty=\fR\fIstty-option-list\fR\fR
.ad
.sp .6
.RS 4n
Prints the request using a list of options valid for the \fBstty\fR command
(see \fBstty\fR(1). Enclose the list in single quotes (\fB`'\fR) if it contains
blanks.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-P\fR \fIpage-list\fR\fR
.ad
.RS 23n
Prints the pages specified in \fIpage-list\fR in ascending order. Specify
\fIpage-list\fR as a of range of numbers, single page number, or a combination
of both.
.sp
The \fB-P\fR option can only be used if there is a filter available to handle
it; otherwise, the print request is rejected.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR\fR
.ad
.RS 23n
Enables notification on completion of the print request. Delivery of the
notification is dependent on additional software.
.RE

.sp
.ne 2
.na
\fB\fB-q\fR \fIpriority-level\fR\fR
.ad
.RS 23n
Assigns the print request a priority in the print queue. Specify
\fIpriority-level\fR as an integer between from \fB0\fR and \fB39\fR. Use
\fB0\fR to indicate the highest priority; \fB39\fR to indicate the lowest
priority. If no priority is specified, the default priority for a print service
is assigned by the \fBLP\fR administrator. The \fBLP\fR administrator can also
assign a default priority to individual users.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.RS 23n
Suppresses the display of messages sent from \fBlp\fR.
.RE

.sp
.ne 2
.na
\fB\fB-S\fR \fIcharacter-set\fR \fB|\fR\fR
.ad
.br
.na
\fB\fB-S\fR \fIprint-wheel\fR\fR
.ad
.RS 23n
Prints the request using the \fIcharacter-set\fR or \fIprint-wheel\fR. If a
form was requested and requires a character set or print wheel other than the
one specified with the \fB-S\fR option, the request is rejected. Printers using
mountable print wheels or font cartridges use the print wheel or font cartridge
mounted at the time of the print request, unless the \fB-S\fR option is
specified.
.sp
Printers Using Print Wheels: If \fBprint\fR \fIwheel\fR is not one listed by
the \fBLP\fR administrator as acceptable for the printer the request is
rejected unless the print wheel is already mounted on the printer.
.sp
Printers Using Selectable or Programmable Character Sets: If the \fB-S\fR
option is not specified, \fBlp\fR uses the standard character set. If
\fIcharacter-set\fR is not defined in the \fBterminfo\fR database for the
printer (see \fBterminfo\fR(4)), or is not an alias defined by the \fBLP\fR
administrator, the request is rejected.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR \fItitle\fR\fR
.ad
.RS 23n
Prints a title on the banner page of the output. Enclose \fItitle\fR in quotes
if it contains blanks. If \fItitle\fR is not not specified, the name of the
file is printed on the banner page.
.RE

.sp
.ne 2
.na
\fB\fB\fR\fB-T\fR\fIcontent-type\fR [\fB-r\fR]\fR
.ad
.RS 23n
Prints the request on a printer that can support the specified
\fIcontent-type\fR. If no printer accepts this type directly, a filter is used
to convert the content into an acceptable type. If the \fB-r\fR option is
specified, a filter is not used. If \fB-r\fR is specified, and no printer
accepts the \fIcontent-type\fR directly, the request is rejected. If the
\fIcontent-type\fR is not acceptable to any printer, either directly or with a
filter, the request is rejected.
.RE

.sp
.ne 2
.na
\fB\fB-w\fR\fR
.ad
.RS 23n
Writes a message on the user's terminal after the \fIfile\fRs have been
printed. If the user is not logged in, then mail is sent instead.
.RE

.sp
.ne 2
.na
\fB\fB-y\fR \fImode-list\fR\fR
.ad
.RS 23n
Prints the request according to the printing modes listed in \fImode-list\fR.
The allowed values for \fImode-list\fR are locally defined.
.sp
This option can be used only if there is a filter available to handle it;
otherwise, the print request is rejected.
.RE

.SH OPERANDS
.LP
The following operand is supported:
.sp
.ne 2
.na
\fB\fIfile\fR\fR
.ad
.RS 8n
The name of the file to be printed. Specify \fIfile\fR as a pathname or as a
hyphen (\fB\(mi\fR) to indicate the standard input. If \fIfile\fR is not
specified, \fBlp\fR uses the standard input.
.RE

.SH USAGE
.LP
See \fBlargefile\fR(5) for the description of the behavior of \fBlp\fR when
encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
.SH ENVIRONMENT VARIABLES
.LP
See \fBenviron\fR(5) for descriptions of the following environment variables
that affect the execution of \fBlp\fR: \fBLANG\fR, \fBLC_ALL\fR,
\fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, \fBNLSPATH\fR, and \fBPATH\fR.
.sp
.ne 2
.na
\fB\fBLC_TIME\fR\fR
.ad
.RS 11n
Determine the format and contents of date and time strings displayed in the
\fBlp\fR banner page, if any.
.RE

.sp
.ne 2
.na
\fB\fBLPDEST\fR\fR
.ad
.RS 11n
Determine the destination. If the \fBLPDEST\fR environment variable is not set,
the \fBPRINTER\fR environment variable shall be used. The \fB-d\fR \fIdest\fR
option takes precedence over \fBLPDEST\fR. Results are undefined when \fB-d\fR
is not specified and \fBLPDEST\fR contains a value that is not a valid
destination name.
.RE

.sp
.ne 2
.na
\fB\fBPRINTER\fR\fR
.ad
.RS 11n
Determine the output device or destination. If the \fBLPDEST\fR and
\fBPRINTER\fR environment variables are not set, an unspecified output device
is used. The \fB-d\fR \fIdest\fR option and the \fBLPDEST\fR environment
variable shall take precedence over \fBPRINTER\fR. Results are undefined when
\fB-d\fR is not specified, \fBLPDEST\fR is unset, and \fBPRINTER\fR contains a
value that is not a valid device or destination name.
.RE

.sp
.ne 2
.na
\fB\fBTZ\fR\fR
.ad
.RS 11n
Determine the timezone used to calculate date and time strings displayed in the
\fBlp\fR banner page, if any. If \fBTZ\fR is unset or null, an unspecified
default timezone shall be used.
.RE

.SH EXIT STATUS
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 12n
Successful completion.
.RE

.sp
.ne 2
.na
\fBnon-zero\fR
.ad
.RS 12n
An error occurred.
.RE

.SH FILES
.ne 2
.na
\fB\fB/etc/printers.conf\fR\fR
.ad
.RS 24n
System printer configuration database
.RE

.sp
.ne 2
.na
\fB\fB$HOME/.printers\fR\fR
.ad
.RS 24n
User-configurable printer database
.RE

.sp
.ne 2
.na
\fB\fBou=printers\fR\fR
.ad
.RS 24n
LDAP version of \fB/etc/printers.conf\fR
.RE

.sp
.ne 2
.na
\fB\fBprinters.conf.byname\fR\fR
.ad
.RS 24n
\fBNIS\fR version of \fB/etc/printers.conf\fR
.RE

.SH ATTRIBUTES
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
CSI	Enabled. See \fBNOTES\fR.
_
Interface Stability	Standard
.TE

.SH SEE ALSO
.LP
\fBcancel\fR(1), \fBenable\fR(1), \fBlpq\fR(1B), \fBlpr\fR(1B), \fBlprm\fR(1B),
\fBlpstat\fR(1), \fBmail\fR(1), \fBpostprint\fR(1), \fBpr\fR(1), \fBstty\fR(1),
\fBaccept\fR(1M), \fBlpadmin\fR(1M), \fBlpfilter\fR(1M), \fBlpforms\fR(1M),
\fBlpmove\fR(1M), \fBlpsched\fR(1M), \fBlpshut\fR(1M), \fBlpsystem\fR(1M),
\fBlpusers\fR(1M), \fBnsswitch.conf\fR(4), \fBprinters\fR(4),
\fBprinters.conf\fR(4), \fBterminfo\fR(4), \fBattributes\fR(5),
\fBenviron\fR(5), \fBlargefile\fR(5), \fBstandards\fR(5)
.SH NOTES
.LP
\fBCSI\fR-capability assumes that printer names are composed of \fBASCII\fR
characters.
.sp
.LP
Print jobs are assumed to contain one type of data. That type of data is either
specified on the command line or autodetected (simple, PostScript) based on the
contents of the first file in the job.
.sp
.LP
When using the BSD printing protocol to send print requests to a remote print
service, functionality is limited.
.sp
.LP
Printers that have a 4.\fIx\fR or BSD-based print server are not configured to
handle BSD protocol extensions. \fBlp\fR handles print requests sent to such
printers in the following ways:
.RS +4
.TP
1.
Print requests with more than 52 filenames are truncated to 52 files.
.RE
.RS +4
.TP
2.
The \fB-f\fR, \fB-H\fR, \fB-o\fR, \fB-P\fR, \fB-p\fR, \fB-q\fR, \fB-S\fR,
\fB-T\fR, and \fB-y\fR options might require a protocol extension to pass to a
print server. If \fBlp\fR cannot handle the print request, it displays a
warning message.
.sp
\fBLP\fR administrators enable protocol extensions by setting a printer's
\fBprinter-uri-supported\fR (or \fBbsdaddr\fR) entry in
\fB/etc/printers.conf\fR. Changing the \fBprinter-uri-supported\fR entry in
\fB/etc/printers.conf\fR to:
.sp
.in +2
.nf
\fBprinter-uri-supported=lpd\e://\fR\fIserver\fR\fB/\fR\fIprinters\fR\fB/\fR\fIdestination\fR\fB#Solaris\fR
.fi
.in -2
.sp

.sp
.in +2
.nf
\fBbsdaddr=\fR\fIserver\fR\fB,\fR\fIdestination\fR\fB,Solaris\fR
.fi
.in -2
.sp

Adding \fBSolaris\fR to either of these values causes the \fBlp\fR command to
generate a set of BSD print protocol extensions that can be processed by a
Solaris print server.
.RE
.sp
.LP
As a result of several limitations in the BSD print protocol, it is recommended
that the IPP protocol be used for communication with print servers.
.sp
.LP
When IPP is in use, the user is prompted for a passphrase if the remote print
service is configured to require authentication.