path: root/man1p/lp.1p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "LP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" lp 
.SH NAME
lp \- send files to a printer
.SH SYNOPSIS
.LP
\fBlp\fP \fB[\fP\fB-c\fP\fB][\fP\fB-d\fP \fIdest\fP\fB][\fP\fB-n\fP
\fIcopies\fP\fB][\fP\fB-msw\fP\fB][\fP\fB-o\fP \fIoption\fP\fB]\fP\fB...\fP
\fB[\fP\fB-t\fP
\fItitle\fP\fB][\fP\fIfile\fP\fB...\fP\fB]\fP
.SH DESCRIPTION
.LP
The \fIlp\fP 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 \fIlp\fP utility
shall exit with a non-zero exit status.
.LP
The actual writing to the output device may occur some time after
the \fIlp\fP utility successfully exits. During the portion
of the writing that corresponds to each input file, the implementation
shall guarantee exclusive access to the device.
.LP
The \fIlp\fP utility shall associate a unique \fIrequest ID\fP with
each request.
.LP
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 \fB-o\fP \fIoption\fP values.
.SH OPTIONS
.LP
The \fIlp\fP utility shall conform to the Base Definitions volume
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
.LP
The following options shall be supported:
.TP 7
\fB-c\fP
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
\fB-c\fP 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
\fB-c\fP 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, \fB-c\fP may be on by
default.
.TP 7
\fB-d\ \fP \fIdest\fP
Specify a string that names the destination ( \fIdest\fP). If \fIdest\fP
is a printer, the request shall be printed only on
that specific printer. If \fIdest\fP 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. 
.LP
If \fB-d\fP is not specified, and neither the \fILPDEST\fP nor \fIPRINTER\fP
environment variable is set, an unspecified
destination is used. The \fB-d\fP \fIdest\fP option shall take precedence
over \fILPDEST ,\fP which in turn shall take
precedence over \fIPRINTER .\fP Results are undefined when \fIdest\fP
contains a value that is not a valid destination name.
.TP 7
\fB-m\fP
Send mail (see \fImailx\fP ) after the files have been printed. By
default, no mail is sent upon
normal completion of the print request.
.TP 7
\fB-n\ \fP \fIcopies\fP
Write \fIcopies\fP number of copies of the files, where \fIcopies\fP
is a positive decimal integer. The methods for producing
multiple copies and for arranging the multiple copies when multiple
\fIfile\fP operands are used are unspecified, except that each
file shall be output as an integral whole, not interleaved with portions
of other files.
.TP 7
\fB-o\ \fP \fIoption\fP
Specify printer-dependent or class-dependent \fIoption\fPs. Several
such \fIoption\fPs may be collected by specifying the
\fB-o\fP option more than once.
.TP 7
\fB-s\fP
Suppress messages from \fIlp\fP.
.TP 7
\fB-t\ \fP \fItitle\fP
Write \fItitle\fP on the banner page of the output.
.TP 7
\fB-w\fP
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.
.sp
.SH OPERANDS
.LP
The following operand shall be supported:
.TP 7
\fIfile\fP
A pathname of a file to be output. If no \fIfile\fP operands are specified,
or if a \fIfile\fP operand is \fB'-'\fP , the
standard input shall be used. If a \fIfile\fP operand is used, but
the \fB-c\fP 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 \fIlp\fP.
.sp
.SH STDIN
.LP
The standard input shall be used only if no \fIfile\fP operands are
specified, or if a \fIfile\fP operand is \fB'-'\fP .
See the INPUT FILES section.
.SH INPUT FILES
.LP
The input files shall be text files.
.SH ENVIRONMENT VARIABLES
.LP
The following environment variables shall affect the execution of
\fIlp\fP:
.TP 7
\fILANG\fP
Provide a default value for the internationalization variables that
are unset or null. (See the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
for
the precedence of internationalization variables used to determine
the values of locale categories.)
.TP 7
\fILC_ALL\fP
If set to a non-empty string value, override the values of all the
other internationalization variables.
.TP 7
\fILC_CTYPE\fP
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).
.TP 7
\fILC_MESSAGES\fP
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.
.TP 7
\fILC_TIME\fP
Determine the format and contents of date and time strings displayed
in the \fIlp\fP banner page, if any.
.TP 7
\fILPDEST\fP
Determine the destination. If the \fILPDEST\fP environment variable
is not set, the \fIPRINTER\fP environment variable shall
be used. The \fB-d\fP \fIdest\fP option takes precedence over \fILPDEST
\&.\fP Results are undefined when \fB-d\fP is not
specified and \fILPDEST\fP contains a value that is not a valid destination
name.
.TP 7
\fINLSPATH\fP
Determine the location of message catalogs for the processing of \fILC_MESSAGES
\&.\fP 
.TP 7
\fIPRINTER\fP
Determine the output device or destination. If the \fILPDEST\fP and
\fIPRINTER\fP environment variables are not set, an
unspecified output device is used. The \fB-d\fP \fIdest\fP option
and the \fILPDEST\fP environment variable shall take
precedence over \fIPRINTER .\fP Results are undefined when \fB-d\fP
is not specified, \fILPDEST\fP is unset, and \fIPRINTER\fP
contains a value that is not a valid device or destination name.
.TP 7
\fITZ\fP
Determine the timezone used to calculate date and time strings displayed
in the \fIlp\fP banner page, if any. If \fITZ\fP is
unset or null, an unspecified default timezone shall be used.
.sp
.SH ASYNCHRONOUS EVENTS
.LP
Default.
.SH STDOUT
.LP
The \fIlp\fP utility shall write a \fIrequest ID\fP to the standard
output, unless \fB-s\fP is specified. The format of the
message is unspecified. The request ID can be used on systems supporting
the historical \fIcancel\fP and \fIlpstat\fP
utilities.
.SH STDERR
.LP
The standard error shall be used only for diagnostic messages.
.SH OUTPUT FILES
.LP
None.
.SH EXTENDED DESCRIPTION
.LP
None.
.SH EXIT STATUS
.LP
The following exit values shall be returned:
.TP 7
\ 0
All input files were processed successfully.
.TP 7
>0
No output device was available, or an error occurred.
.sp
.SH CONSEQUENCES OF ERRORS
.LP
Default.
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
The \fIpr\fP and \fIfold\fP utilities can be used to
achieve reasonable formatting for the implementation's default page
size.
.LP
A conforming application can use one of the \fIfile\fP operands only
with the \fB-c\fP option or if the file is publicly
readable and guaranteed to be available at the time of printing. This
is because IEEE\ Std\ 1003.1-2001 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 \fIfile\fP:
.sp
.RS
.nf

\fBlp -c\fP \fIfile\fP
.fi
.RE
.LP
.IP " 2." 4
To print multiple files with headers:
.sp
.RS
.nf

\fBpr\fP \fIfile1 file2\fP \fB| lp
\fP
.fi
.RE
.LP
.SH RATIONALE
.LP
The \fIlp\fP 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
.nf

\fBcat "$@" > /dev/lp
\fP
.fi
.RE
.LP
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.
.LP
This volume of IEEE\ Std\ 1003.1-2001 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 \fB-d\fP \fIdest\fP,
\fILPDEST ,\fP or \fIPRINTER\fP are used,
however.)
.LP
This volume of IEEE\ Std\ 1003.1-2001 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.
.LP
The \fB-c\fP 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).
.LP
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 IEEE\ Std\ 1003.1-2001.
.LP
Although the historical System V \fIlp\fP and BSD \fIlpr\fP 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 \fIlp\fP,
\fILPDEST\fP (used by the System V \fIlp\fP utility) was given precedence
over \fIPRINTER\fP (used by the BSD \fIlpr\fP
utility). Since environments of users frequently contain one or the
other environment variable, the \fIlp\fP 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.
.LP
Some have commented that \fIlp\fP 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 " *" 3
Wording \fIrequiring\fP the output to be "hardcopy"
.LP
.IP " *" 3
A requirement for multiple printers
.LP
.IP " *" 3
Options for supporting various page-description languages
.LP
.LP
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.
.LP
The term \fIunspecified\fP is used in this section in lieu of \fIimplementation-defined\fP
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.
.LP
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 " *" 3
Use the command in a pipeline, or with \fB-c\fP, so that there are
no permission problems and the files can be safely deleted
or modified.
.LP
.IP " *" 3
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 \fIpr\fP and \fIfold\fP
utilities can be used to achieve
reasonable formatting for the default page size of the implementation.
.LP
.LP
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 \fIlp\fP options and environment
variable values.
.LP
At a minimum, having this utility in this volume of IEEE\ Std\ 1003.1-2001
tells the industry that conforming
applications require a means to print output and provides at least
a command name and \fILPDEST\fP routing mechanism that can be
used for discussions between vendors, application writers, and users.
The use of "should" in the DESCRIPTION of \fIlp\fP clearly
shows the intent of the standard developers, even if they cannot mandate
that all systems (such as laptops) have printers.
.LP
This volume of IEEE\ Std\ 1003.1-2001 does not specify what the ownership
of the process performing the writing to the
output device may be. If \fB-c\fP is not used, it is unspecified whether
the process performing the writing to the output device
has permission to read \fIfile\fP if there are any restrictions in
place on who may read \fIfile\fP until after it is printed.
Also, if \fB-c\fP is not used, the results of deleting \fIfile\fP
before it is printed are unspecified.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fImailx\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. 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.opengroup.org/unix/online.html .