xenial (1) lp.1posix.gz

Provided by: manpages-posix_2013a-1_all bug

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.

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 POSIX.1‐2008, 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 POSIX.1‐2008, 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 POSIX.1‐2008
       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 POSIX.1‐2008 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 POSIX.1‐2008 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 POSIX.1‐2008.

       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 POSIX.1‐2008 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 developers, 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 POSIX.1‐2008 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.

SEE ALSO

       mailx

       The  Base  Definitions  volume  of  POSIX.1‐2008, Chapter 8, Environment Variables, Section 12.2, Utility
       Syntax Guidelines

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2013 Edition,
       Standard  for  Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electrical and Electronics Engineers,  Inc
       and  The  Open Group.  (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

       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 .