lp.1p (15092B)
- '\" et
- .TH LP "1P" 2017 "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-c\fB] [\fR-d \fIdest\fB] [\fR-n \fIcopies\fB] [\fR-msw\fB] [\fR-o \fIoption\fB]\fR... \fB[\fR-t \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 \-o
- .IR option
- values.
- .SH OPTIONS
- The
- .IR lp
- utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 12.2" ", " "Utility Syntax Guidelines".
- .P
- The following options shall be supported:
- .IP "\fB\-c\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 \-c
- 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 \-c
- 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 \-c
- may be on by default.
- .IP "\fB\-d\ \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 \-d
- is not specified, and neither the
- .IR LPDEST
- nor
- .IR PRINTER
- environment variable is set, an unspecified destination is used. The
- .BR \-d
- .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\-m\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\-n\ \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\-o\ \fIoption\fR" 10
- Specify printer-dependent or class-dependent
- .IR option s.
- Several such
- .IR option s
- may be collected by specifying the
- .BR \-o
- option more than once.
- .IP "\fB\-s\fP" 10
- Suppress messages from
- .IR lp .
- .IP "\fB\-t\ \fItitle\fR" 10
- Write
- .IR title
- on the banner page of the output.
- .IP "\fB\-w\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 '\-' ,
- the standard input shall be used. If a
- .IR file
- operand is used, but the
- .BR \-c
- 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 '\-' .
- 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\(hy2017,
- .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 \-d
- .IR dest
- option takes precedence over
- .IR LPDEST .
- Results are undefined when
- .BR \-d
- 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 \-d
- .IR dest
- option and the
- .IR LPDEST
- environment variable shall take precedence over
- .IR PRINTER .
- Results are undefined when
- .BR \-d
- 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 \-s
- 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 \-c
- 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
- lp -c \fIfile\fR
- .fi
- .P
- .RE
- .RE
- .IP " 2." 4
- To print multiple files with headers:
- .RS 4
- .sp
- .RS 4
- .nf
- pr \fIfile1 file2\fP | lp
- .fi
- .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
- cat "$@" > /dev/lp
- .fi
- .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\(hy2017 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 \-d
- .IR dest ,
- .IR LPDEST ,
- or
- .IR PRINTER
- are used, however.)
- .P
- This volume of POSIX.1\(hy2017 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 \-c
- 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\(hy2017.
- .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 \-c ,
- 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\(hy2017 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\(hy2017 does not specify what the ownership of the process performing the
- writing to the output device may be. If
- .BR \-c
- 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 \-c
- 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\(hy2017,
- .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-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 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 .
- .PP
- 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 .