diff options
Diffstat (limited to '')
| -rw-r--r-- | upstream/mageia-cauldron/man1p/lp.1p | 482 |
1 files changed, 482 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1p/lp.1p b/upstream/mageia-cauldron/man1p/lp.1p new file mode 100644 index 00000000..48f4fa48 --- /dev/null +++ b/upstream/mageia-cauldron/man1p/lp.1p @@ -0,0 +1,482 @@ +'\" 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 . |