'\" et
.TH LP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.

.SH NAME
lp
\(em send files to a printer
.SH SYNOPSIS
.LP
.nf
lp \fB[\fR\(mic\fB] [\fR\(mid \fIdest\fB] [\fR\(min \fIcopies\fB] [\fR\(mimsw\fB] [\fR\(mio \fIoption\fB]\fR... \fB[\fR\(mit \fItitle\fB] [\fIfile\fR...\fB]\fR
.fi
.SH DESCRIPTION
The
.IR lp
utility shall copy the input files to an output destination in an
unspecified manner. The default output destination should be to a
hardcopy device, such as a printer or microfilm recorder, that produces
non-volatile, human-readable documents. If such a device is not
available to the application, or if the system provides no such device,
the
.IR lp
utility shall exit with a non-zero exit status.
.P
The actual writing to the output device may occur some time after the
.IR lp
utility successfully exits. During the portion of the writing that
corresponds to each input file, the implementation shall guarantee
exclusive access to the device.
.P
The
.IR lp
utility shall associate a unique
.IR "request ID"
with each request.
.P
Normally, a banner page is produced to separate and identify each print
job. This page may be suppressed by implementation-defined
conditions, such as an operator command or one of the
.BR \(mio
.IR option
values.
.SH OPTIONS
The
.IR lp
utility shall conform to the Base Definitions volume of POSIX.1\(hy2008,
.IR "Section 12.2" ", " "Utility Syntax Guidelines".
.P
The following options shall be supported:
.IP "\fB\(mic\fP" 10
Exit only after further access to any of the input files is no longer
required. The application can then safely delete or modify the files
without affecting the output operation. Normally, files are not
copied, but are linked whenever possible. If the
.BR \(mic
option is not given, then the user should be careful not to remove any
of the files before the request has been printed in its entirety. It
should also be noted that in the absence of the
.BR \(mic
option, any changes made to the named files after the request is made
but before it is printed may be reflected in the printed output.
On some implementations,
.BR \(mic
may be on by default.
.IP "\fB\(mid\ \fIdest\fR" 10
Specify a string that names the destination (\c
.IR dest ).
If
.IR dest
is a printer, the request shall be printed only on that specific
printer. If
.IR dest
is a class of printers, the request shall be printed on the first
available printer that is a member of the class. Under certain
conditions (printer unavailability, file space limitation, and so on),
requests for specific destinations need not be accepted. Destination
names vary between systems.
.RS 10 
.P
If
.BR \(mid
is not specified, and neither the
.IR LPDEST
nor
.IR PRINTER
environment variable is set, an unspecified destination is used. The
.BR \(mid
.IR dest
option shall take precedence over
.IR LPDEST ,
which in turn shall take precedence over
.IR PRINTER .
Results are undefined when
.IR dest
contains a value that is not a valid destination name.
.RE
.IP "\fB\(mim\fP" 10
Send mail (see
.IR "\fImailx\fR\^")
after the files have been printed. By default, no mail is sent upon
normal completion of the print request.
.IP "\fB\(min\ \fIcopies\fR" 10
Write
.IR copies
number of copies of the files, where
.IR copies
is a positive decimal integer. The methods for producing multiple
copies and for arranging the multiple copies when multiple
.IR file
operands are used are unspecified, except that each file shall be
output as an integral whole, not interleaved with portions of other
files.
.IP "\fB\(mio\ \fIoption\fR" 10
Specify printer-dependent or class-dependent
.IR option s.
Several such
.IR option s
may be collected by specifying the
.BR \(mio
option more than once.
.IP "\fB\(mis\fP" 10
Suppress messages from
.IR lp .
.IP "\fB\(mit\ \fItitle\fR" 10
Write
.IR title
on the banner page of the output.
.IP "\fB\(miw\fP" 10
Write a message on the user's terminal after the files have been
printed. If the user is not logged in, then mail shall be sent
instead.
.SH OPERANDS
The following operand shall be supported:
.IP "\fIfile\fR" 10
A pathname of a file to be output. If no
.IR file
operands are specified, or if a
.IR file
operand is
.BR '\(mi' ,
the standard input shall be used. If a
.IR file
operand is used, but the
.BR \(mic
option is not specified, the process performing the writing to the
output device may have user and group permissions that differ from that
of the process invoking
.IR lp .
.SH STDIN
The standard input shall be used only if no
.IR file
operands are specified, or if a
.IR file
operand is
.BR '\(mi' .
See the INPUT FILES section.
.SH "INPUT FILES"
The input files shall be text files.
.SH "ENVIRONMENT VARIABLES"
The following environment variables shall affect the execution of
.IR lp :
.IP "\fILANG\fP" 10
Provide a default value for the internationalization variables that are
unset or null. (See the Base Definitions volume of POSIX.1\(hy2008,
.IR "Section 8.2" ", " "Internationalization Variables"
for the precedence of internationalization variables used to determine
the values of locale categories.)
.IP "\fILC_ALL\fP" 10
If set to a non-empty string value, override the values of all the
other internationalization variables.
.IP "\fILC_CTYPE\fP" 10
Determine the locale for the interpretation of sequences of bytes of
text data as characters (for example, single-byte as opposed to
multi-byte characters in arguments and input files).
.IP "\fILC_MESSAGES\fP" 10
.br
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard error and
informative messages written to standard output.
.IP "\fILC_TIME\fP" 10
Determine the format and contents of date and time strings displayed in
the
.IR lp
banner page, if any.
.IP "\fILPDEST\fP" 10
Determine the destination. If the
.IR LPDEST
environment variable is not set, the
.IR PRINTER
environment variable shall be used. The
.BR \(mid
.IR dest
option takes precedence over
.IR LPDEST .
Results are undefined when
.BR \(mid
is not specified and
.IR LPDEST
contains a value that is not a valid destination name.
.IP "\fINLSPATH\fP" 10
Determine the location of message catalogs for the processing of
.IR LC_MESSAGES .
.IP "\fIPRINTER\fP" 10
Determine the output device or destination. If the
.IR LPDEST
and
.IR PRINTER
environment variables are not set, an unspecified output device is
used. The
.BR \(mid
.IR dest
option and the
.IR LPDEST
environment variable shall take precedence over
.IR PRINTER .
Results are undefined when
.BR \(mid
is not specified,
.IR LPDEST
is unset, and
.IR PRINTER
contains a value that is not a valid device or destination name.
.IP "\fITZ\fP" 10
Determine the timezone used to calculate date and time strings
displayed in the
.IR lp
banner page, if any. If
.IR TZ
is unset or null, an unspecified default timezone shall be used.
.SH "ASYNCHRONOUS EVENTS"
Default.
.SH STDOUT
The
.IR lp
utility shall write a
.IR "request ID"
to the standard output, unless
.BR \(mis
is specified. The format of the message is unspecified. The request
ID can be used on systems supporting the historical
.IR cancel
and
.IR lpstat
utilities.
.SH STDERR
The standard error shall be used only for diagnostic messages.
.SH "OUTPUT FILES"
None.
.SH "EXTENDED DESCRIPTION"
None.
.SH "EXIT STATUS"
The following exit values shall be returned:
.IP "\00" 6
All input files were processed successfully.
.IP >0 6
No output device was available, or an error occurred.
.SH "CONSEQUENCES OF ERRORS"
Default.
.LP
.IR "The following sections are informative."
.SH "APPLICATION USAGE"
The
.IR pr
and
.IR fold
utilities can be used to achieve reasonable formatting for the
implementation's default page size.
.P
A conforming application can use one of the
.IR file
operands only with the
.BR \(mic
option or if the file is publicly readable and guaranteed to be
available at the time of printing. This is because POSIX.1\(hy2008 gives
the implementation the freedom to queue up the request for printing at
some later time by a different process that might not be able to access
the file.
.SH EXAMPLES
.IP " 1." 4
To print file
.IR file :
.RS 4 
.sp
.RS 4
.nf
\fB
lp \(mic \fIfile\fR
.fi \fR
.P
.RE
.RE
.IP " 2." 4
To print multiple files with headers:
.RS 4 
.sp
.RS 4
.nf
\fB
pr \fIfile1 file2\fP | lp
.fi \fR
.P
.RE
.RE
.SH RATIONALE
The
.IR lp
utility was designed to be a basic version of a utility that is already
available in many historical implementations. The standard developers
considered that it should be implementable simply as:
.sp
.RS 4
.nf
\fB
cat "$@" > /dev/lp
.fi \fR
.P
.RE
.P
after appropriate processing of options, if that is how the
implementation chose to do it and if exclusive access could be granted
(so that two users did not write to the device simultaneously).
Although in the future the standard developers may add other options to
this utility, it should always be able to execute with no options or
operands and send the standard input to an unspecified output device.
.P
This volume of POSIX.1\(hy2008 makes no representations concerning the format of the printed
output, except that it must be ``human-readable'' and ``non-volatile''.
Thus, writing by default to a disk or tape drive or a display terminal
would not qualify. (Such destinations are not prohibited when
.BR \(mid
.IR dest ,
.IR LPDEST ,
or
.IR PRINTER
are used, however.)
.P
This volume of POSIX.1\(hy2008 is worded such that a ``print job'' consisting of multiple input
files, possibly in multiple copies, is guaranteed to print so that any
one file is not intermixed with another, but there is no statement that
all the files or copies have to print out together.
.P
The
.BR \(mic
option may imply a spooling operation, but this is not required. The
utility can be implemented to wait until the printer is ready and then
wait until it is finished. Because of that, there is no attempt to
define a queuing mechanism (priorities, classes of output, and so on).
.P
On some historical systems, the request ID reported on the STDOUT
can be used to later cancel or find the status of a request using
utilities not defined in this volume of POSIX.1\(hy2008.
.P
Although the historical System V
.IR lp
and BSD
.IR lpr
utilities have provided similar functionality, they used different
names for the environment variable specifying the destination printer.
Since the name of the utility here is
.IR lp ,
.IR LPDEST
(used by the System V
.IR lp
utility) was given precedence over
.IR PRINTER
(used by the BSD
.IR lpr
utility). Since environments of users frequently contain one or the
other environment variable, the
.IR lp
utility is required to recognize both. If this was not done, many
applications would send output to unexpected output devices when users
moved from system to system.
.P
Some have commented that
.IR lp
has far too little functionality to make it worthwhile. Requests have
proposed additional options or operands or both that added
functionality. The requests included:
.IP " *" 4
Wording
.IR requiring
the output to be ``hardcopy''
.IP " *" 4
A requirement for multiple printers
.IP " *" 4
Options for supporting various page-description languages
.P
Given that a compliant system is not required to even have a printer,
placing further restrictions upon the behavior of the printer is not
useful. Since hardcopy format is so application-dependent, it is
difficult, if not impossible, to select a reasonable subset of
functionality that should be required on all compliant systems.
.P
The term \fIunspecified\fR is used in this section in lieu of
\fIimplementation-defined\fR as most known implementations would not be
able to make definitive statements in their conformance documents; the
existence and usage of printers is very dependent on how the system
administrator configures each individual system.
.P
Since the default destination, device type, queuing mechanisms, and
acceptable forms of input are all unspecified, usage guidelines for
what a conforming application can do are as follows:
.IP " *" 4
Use the command in a pipeline, or with
.BR \(mic ,
so that there are no permission problems and the files can be safely
deleted or modified.
.IP " *" 4
Limit output to text files of reasonable line lengths and printable
characters and include no device-specific formatting information, such
as a page description language. The meaning of ``reasonable'' in this
context can only be answered as a quality-of-implementation issue, but
it should be apparent from historical usage patterns in the industry
and the locale. The
.IR pr
and
.IR fold
utilities can be used to achieve reasonable formatting for the default
page size of the implementation.
.P
Alternatively, the application can arrange its installation in such a
way that it requires the system administrator or operator to provide
the appropriate information on
.IR lp
options and environment variable values.
.P
At a minimum, having this utility in this volume of POSIX.1\(hy2008 tells the industry that
conforming applications require a means to print output and provides at
least a command name and
.IR LPDEST
routing mechanism that can be used for discussions between vendors,
application developers, and users. The use of ``should'' in the
DESCRIPTION of
.IR lp
clearly shows the intent of the standard developers, even if they
cannot mandate that all systems (such as laptops) have printers.
.P
This volume of POSIX.1\(hy2008 does not specify what the ownership of the process performing the
writing to the output device may be. If
.BR \(mic
is not used, it is unspecified whether the process performing the
writing to the output device has permission to read
.IR file
if there are any restrictions in place on who may read
.IR file
until after it is printed. Also, if
.BR \(mic
is not used, the results of deleting
.IR file
before it is printed are unspecified.
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "\fImailx\fR\^"
.P
The Base Definitions volume of POSIX.1\(hy2008,
.IR "Chapter 8" ", " "Environment Variables",
.IR "Section 12.2" ", " "Utility Syntax Guidelines"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, Copyright (C) 2013 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
event of any discrepancy between this version 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.unix.org/online.html .

Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .