mirror of https://github.com/mkerrisk/man-pages
389 lines
14 KiB
Groff
389 lines
14 KiB
Groff
.\" 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 .
|