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