Ubuntu Manpage: lp - send files to a printer

NAME

       lp - send files to a printer

SYNOPSIS

       lp [-c][-d dest][-n copies][-msw][-o option]...  [-t title][file...]

DESCRIPTION

       The  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 lp utility shall exit with a non-zero exit status.

       The actual writing to the output device may occur some time after  the  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.

       The lp utility shall associate a unique request ID with each request.

       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 -o option values.

OPTIONS

The lp utility shall conform to the Base Definitions volume of IEEE Std 1003.1-2001, Section 12.2,
Utility Syntax Guidelines.

The following options shall be supported:

-c 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 -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 -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, -c may be on by default.

-d dest
Specify a string that names the destination ( dest). If dest is a printer, the request shall be
printed only on that specific printer. If 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.

If -d is not specified, and neither the LPDEST nor PRINTER environment variable is set, an unspecified
destination is used. The -d dest option shall take precedence over LPDEST , which in turn shall take
precedence over PRINTER . Results are undefined when dest contains a value that is not a valid
destination name.

-m Send mail (see mailx ) after the files have been printed. By default, no mail is sent upon normal
completion of the print request.

-n copies
Write copies number of copies of the files, where copies is a positive decimal integer. The
methods for producing multiple copies and for arranging the multiple copies when multiple file
operands are used are unspecified, except that each file shall be output as an integral whole, not
interleaved with portions of other files.

-o option
Specify printer-dependent or class-dependent options. Several such options may be collected by
specifying the -o option more than once.

-s Suppress messages from lp.

-t title
Write title on the banner page of the output.

-w 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.

OPERANDS

       The following operand shall be supported:

       file   A  pathname of a file to be output. If no file operands are specified, or if a file operand is '-'
              , the standard input shall be used. If a file operand is used, but the -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 lp.

STDIN

       The standard input shall be used only if no file operands are specified, or if a file operand  is  '-'  .
       See the INPUT FILES section.

INPUT FILES

       The input files shall be text files.

ENVIRONMENT VARIABLES

The following environment variables shall affect the execution of lp:

LANG 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.)

LC_ALL If set to a non-empty string value, override the values of all the other internationalization
variables.

LC_CTYPE
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).

LC_MESSAGES
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.

LC_TIME
Determine the format and contents of date and time strings displayed in the lp banner page, if
any.

LPDEST Determine the destination. If the LPDEST environment variable is not set, the PRINTER environment
variable shall be used. The -d dest option takes precedence over LPDEST . Results are undefined
when -d is not specified and LPDEST contains a value that is not a valid destination name.

NLSPATH
Determine the location of message catalogs for the processing of LC_MESSAGES .

PRINTER
Determine the output device or destination. If the LPDEST and PRINTER environment variables are
not set, an unspecified output device is used. The -d dest option and the LPDEST environment
variable shall take precedence over PRINTER . Results are undefined when -d is not specified,
LPDEST is unset, and PRINTER contains a value that is not a valid device or destination name.

TZ Determine the timezone used to calculate date and time strings displayed in the lp banner page, if
any. If TZ is unset or null, an unspecified default timezone shall be used.

ASYNCHRONOUS EVENTS

       Default.

STDOUT

       The lp utility shall write a request ID to the standard output, unless -s is specified. The format of the
       message is unspecified. The request ID can be used on systems supporting the historical cancel and lpstat
       utilities.

STDERR

       The standard error shall be used only for diagnostic messages.

OUTPUT FILES

       None.

EXTENDED DESCRIPTION

       None.

EXIT STATUS

       The following exit values shall be returned:

        0     All input files were processed successfully.

       >0     No output device was available, or an error occurred.

CONSEQUENCES OF ERRORS

       Default.

       The following sections are informative.

APPLICATION USAGE

       The pr and fold utilities can be used to achieve reasonable formatting for the  implementation's  default
       page size.

       A  conforming  application  can  use  one  of the file operands only with the -c 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.

EXAMPLES

        1. To print file file:

           lp -c file

        2. To print multiple files with headers:

           pr file1 file2 | lp

RATIONALE

       The 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:

              cat "$@" > /dev/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.

       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 -d dest, LPDEST
       , or PRINTER are used, however.)

       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.

       The -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).

       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.

       Although the historical System V lp and BSD 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 lp, LPDEST (used by the System V lp utility) was given precedence over PRINTER  (used  by
       the  BSD  lpr  utility).  Since  environments  of  users  frequently contain one or the other environment
       variable, the 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.

       Some  have  commented  that  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:

        * Wording requiring the output to be "hardcopy"

        * A requirement for multiple printers

        * Options for supporting various page-description languages

       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.

       The  term  unspecified  is  used  in  this  section  in  lieu  of  implementation-defined  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.

       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:

        * Use  the command in a pipeline, or with -c, so that there are no permission problems and the files can
          be safely deleted or modified.

        * 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 pr and fold utilities can be used to
          achieve reasonable formatting for the default page size of the implementation.

       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 lp options and environment variable
       values.

       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 LPDEST
       routing mechanism that can be used for discussions between vendors, application writers, and users.   The
       use  of  "should"  in  the DESCRIPTION of lp clearly shows the intent of the standard developers, even if
       they cannot mandate that all systems (such as laptops) have printers.

       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 -c is not used, it is unspecified whether the process performing
       the writing to the output device has permission to read file if there are any restrictions  in  place  on
       who  may  read  file  until  after  it is printed.  Also, if -c is not used, the results of deleting file
       before it is printed are unspecified.

FUTURE DIRECTIONS

       None.

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 .