LP(1)                      POSIX Programmer's Manual                     LP(1)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       lp -- send files to a printer

SSYYNNOOPPSSIISS
       lp [[-c]] [[-d _d_e_s_t]] [[-n _c_o_p_i_e_s]] [[-msw]] [[-o _o_p_t_i_o_n]]... [[-t _t_i_t_l_e]] [[_f_i_l_e...]]

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

       The actual writing to the output device may occur some time after the
       _l_p 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 _l_p utility shall associate a unique _r_e_q_u_e_s_t _I_D 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 --oo _o_p_t_i_o_n values.

OOPPTTIIOONNSS
       The _l_p utility shall conform to the Base Definitions volume of
       POSIX.1-2017, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s.

       The following options shall be supported:

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

       --dd _d_e_s_t   Specify a string that names the destination (_d_e_s_t).  If _d_e_s_t
                 is a printer, the request shall be printed only on that
                 specific printer. If _d_e_s_t 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 --dd is not specified, and neither the _L_P_D_E_S_T nor _P_R_I_N_T_E_R
                 environment variable is set, an unspecified destination is
                 used. The --dd _d_e_s_t option shall take precedence over _L_P_D_E_S_T,
                 which in turn shall take precedence over _P_R_I_N_T_E_R.  Results
                 are undefined when _d_e_s_t contains a value that is not a valid
                 destination name.

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

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

       --oo _o_p_t_i_o_n Specify printer-dependent or class-dependent _o_p_t_i_o_ns.
                 Several such _o_p_t_i_o_ns may be collected by specifying the --oo
                 option more than once.

       --ss        Suppress messages from _l_p.

       --tt _t_i_t_l_e  Write _t_i_t_l_e on the banner page of the output.

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

OOPPEERRAANNDDSS
       The following operand shall be supported:

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

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

IINNPPUUTT FFIILLEESS
       The input files shall be text files.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of _l_p:

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2017, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s for the precedence of internationalization
                 variables used to determine the values of locale categories.)

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

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

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

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

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

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

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

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

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

SSTTDDOOUUTT
       The _l_p utility shall write a _r_e_q_u_e_s_t _I_D to the standard output, unless
       --ss is specified. The format of the message is unspecified. The request
       ID can be used on systems supporting the historical _c_a_n_c_e_l and _l_p_s_t_a_t
       utilities.

SSTTDDEERRRR
       The standard error shall be used only for diagnostic messages.

OOUUTTPPUUTT FFIILLEESS
       None.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       None.

EEXXIITT SSTTAATTUUSS
       The following exit values shall be returned:

        0    All input files were processed successfully.

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

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       Default.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       The _p_r and _f_o_l_d utilities can be used to achieve reasonable formatting
       for the implementation's default page size.

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

EEXXAAMMPPLLEESS
        1. To print file _f_i_l_e:


               lp -c _f_i_l_e

        2. To print multiple files with headers:


               pr _f_i_l_e_1 _f_i_l_e_2 | lp

RRAATTIIOONNAALLEE
       The _l_p 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-2017 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 --dd _d_e_s_t, _L_P_D_E_S_T, or _P_R_I_N_T_E_R are used, however.)

       This volume of POSIX.1-2017 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 --cc 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-2017.

       Although the historical System V _l_p and BSD _l_p_r 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 _l_p, _L_P_D_E_S_T (used by the System V _l_p utility) was given
       precedence over _P_R_I_N_T_E_R (used by the BSD _l_p_r utility). Since
       environments of users frequently contain one or the other environment
       variable, the _l_p 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 _l_p 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 _r_e_q_u_i_r_i_n_g 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 _u_n_s_p_e_c_i_f_i_e_d is used in this section in lieu of _i_m_p_l_e_m_e_n_t_a_t_i_o_n_-
       _d_e_f_i_n_e_d 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 --cc, 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 _p_r and _f_o_l_d 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 _l_p options and environment variable
       values.

       At a minimum, having this utility in this volume of POSIX.1-2017 tells
       the industry that conforming applications require a means to print
       output and provides at least a command name and _L_P_D_E_S_T routing
       mechanism that can be used for discussions between vendors, application
       developers, and users. The use of ``should'' in the DESCRIPTION of _l_p
       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-2017 does not specify what the ownership of the
       process performing the writing to the output device may be. If --cc is
       not used, it is unspecified whether the process performing the writing
       to the output device has permission to read _f_i_l_e if there are any
       restrictions in place on who may read _f_i_l_e until after it is printed.
       Also, if --cc is not used, the results of deleting _f_i_l_e before it is
       printed are unspecified.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _m_a_i_l_x

       The Base Definitions volume of POSIX.1-2017, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t
       _V_a_r_i_a_b_l_e_s, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s

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

       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 .



IEEE/The Open Group                  2017                                LP(1)
