logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

lp.1p (15092B)


  1. '\" et
  2. .TH LP "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. lp
  12. \(em send files to a printer
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. 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
  17. .fi
  18. .SH DESCRIPTION
  19. The
  20. .IR lp
  21. utility shall copy the input files to an output destination in an
  22. unspecified manner. The default output destination should be to a
  23. hardcopy device, such as a printer or microfilm recorder, that produces
  24. non-volatile, human-readable documents. If such a device is not
  25. available to the application, or if the system provides no such device,
  26. the
  27. .IR lp
  28. utility shall exit with a non-zero exit status.
  29. .P
  30. The actual writing to the output device may occur some time after the
  31. .IR lp
  32. utility successfully exits. During the portion of the writing that
  33. corresponds to each input file, the implementation shall guarantee
  34. exclusive access to the device.
  35. .P
  36. The
  37. .IR lp
  38. utility shall associate a unique
  39. .IR "request ID"
  40. with each request.
  41. .P
  42. Normally, a banner page is produced to separate and identify each print
  43. job. This page may be suppressed by implementation-defined
  44. conditions, such as an operator command or one of the
  45. .BR \-o
  46. .IR option
  47. values.
  48. .SH OPTIONS
  49. The
  50. .IR lp
  51. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  52. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  53. .P
  54. The following options shall be supported:
  55. .IP "\fB\-c\fP" 10
  56. Exit only after further access to any of the input files is no longer
  57. required. The application can then safely delete or modify the files
  58. without affecting the output operation. Normally, files are not
  59. copied, but are linked whenever possible. If the
  60. .BR \-c
  61. option is not given, then the user should be careful not to remove any
  62. of the files before the request has been printed in its entirety. It
  63. should also be noted that in the absence of the
  64. .BR \-c
  65. option, any changes made to the named files after the request is made
  66. but before it is printed may be reflected in the printed output.
  67. On some implementations,
  68. .BR \-c
  69. may be on by default.
  70. .IP "\fB\-d\ \fIdest\fR" 10
  71. Specify a string that names the destination (\c
  72. .IR dest ).
  73. If
  74. .IR dest
  75. is a printer, the request shall be printed only on that specific
  76. printer. If
  77. .IR dest
  78. is a class of printers, the request shall be printed on the first
  79. available printer that is a member of the class. Under certain
  80. conditions (printer unavailability, file space limitation, and so on),
  81. requests for specific destinations need not be accepted. Destination
  82. names vary between systems.
  83. .RS 10
  84. .P
  85. If
  86. .BR \-d
  87. is not specified, and neither the
  88. .IR LPDEST
  89. nor
  90. .IR PRINTER
  91. environment variable is set, an unspecified destination is used. The
  92. .BR \-d
  93. .IR dest
  94. option shall take precedence over
  95. .IR LPDEST ,
  96. which in turn shall take precedence over
  97. .IR PRINTER .
  98. Results are undefined when
  99. .IR dest
  100. contains a value that is not a valid destination name.
  101. .RE
  102. .IP "\fB\-m\fP" 10
  103. Send mail (see
  104. .IR "\fImailx\fR\^")
  105. after the files have been printed. By default, no mail is sent upon
  106. normal completion of the print request.
  107. .IP "\fB\-n\ \fIcopies\fR" 10
  108. Write
  109. .IR copies
  110. number of copies of the files, where
  111. .IR copies
  112. is a positive decimal integer. The methods for producing multiple
  113. copies and for arranging the multiple copies when multiple
  114. .IR file
  115. operands are used are unspecified, except that each file shall be
  116. output as an integral whole, not interleaved with portions of other
  117. files.
  118. .IP "\fB\-o\ \fIoption\fR" 10
  119. Specify printer-dependent or class-dependent
  120. .IR option s.
  121. Several such
  122. .IR option s
  123. may be collected by specifying the
  124. .BR \-o
  125. option more than once.
  126. .IP "\fB\-s\fP" 10
  127. Suppress messages from
  128. .IR lp .
  129. .IP "\fB\-t\ \fItitle\fR" 10
  130. Write
  131. .IR title
  132. on the banner page of the output.
  133. .IP "\fB\-w\fP" 10
  134. Write a message on the user's terminal after the files have been
  135. printed. If the user is not logged in, then mail shall be sent
  136. instead.
  137. .SH OPERANDS
  138. The following operand shall be supported:
  139. .IP "\fIfile\fR" 10
  140. A pathname of a file to be output. If no
  141. .IR file
  142. operands are specified, or if a
  143. .IR file
  144. operand is
  145. .BR '\-' ,
  146. the standard input shall be used. If a
  147. .IR file
  148. operand is used, but the
  149. .BR \-c
  150. option is not specified, the process performing the writing to the
  151. output device may have user and group permissions that differ from that
  152. of the process invoking
  153. .IR lp .
  154. .SH STDIN
  155. The standard input shall be used only if no
  156. .IR file
  157. operands are specified, or if a
  158. .IR file
  159. operand is
  160. .BR '\-' .
  161. See the INPUT FILES section.
  162. .SH "INPUT FILES"
  163. The input files shall be text files.
  164. .SH "ENVIRONMENT VARIABLES"
  165. The following environment variables shall affect the execution of
  166. .IR lp :
  167. .IP "\fILANG\fP" 10
  168. Provide a default value for the internationalization variables that are
  169. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  170. .IR "Section 8.2" ", " "Internationalization Variables"
  171. for the precedence of internationalization variables used to determine
  172. the values of locale categories.)
  173. .IP "\fILC_ALL\fP" 10
  174. If set to a non-empty string value, override the values of all the
  175. other internationalization variables.
  176. .IP "\fILC_CTYPE\fP" 10
  177. Determine the locale for the interpretation of sequences of bytes of
  178. text data as characters (for example, single-byte as opposed to
  179. multi-byte characters in arguments and input files).
  180. .IP "\fILC_MESSAGES\fP" 10
  181. .br
  182. Determine the locale that should be used to affect the format and
  183. contents of diagnostic messages written to standard error and
  184. informative messages written to standard output.
  185. .IP "\fILC_TIME\fP" 10
  186. Determine the format and contents of date and time strings displayed in
  187. the
  188. .IR lp
  189. banner page, if any.
  190. .IP "\fILPDEST\fP" 10
  191. Determine the destination. If the
  192. .IR LPDEST
  193. environment variable is not set, the
  194. .IR PRINTER
  195. environment variable shall be used. The
  196. .BR \-d
  197. .IR dest
  198. option takes precedence over
  199. .IR LPDEST .
  200. Results are undefined when
  201. .BR \-d
  202. is not specified and
  203. .IR LPDEST
  204. contains a value that is not a valid destination name.
  205. .IP "\fINLSPATH\fP" 10
  206. Determine the location of message catalogs for the processing of
  207. .IR LC_MESSAGES .
  208. .IP "\fIPRINTER\fP" 10
  209. Determine the output device or destination. If the
  210. .IR LPDEST
  211. and
  212. .IR PRINTER
  213. environment variables are not set, an unspecified output device is
  214. used. The
  215. .BR \-d
  216. .IR dest
  217. option and the
  218. .IR LPDEST
  219. environment variable shall take precedence over
  220. .IR PRINTER .
  221. Results are undefined when
  222. .BR \-d
  223. is not specified,
  224. .IR LPDEST
  225. is unset, and
  226. .IR PRINTER
  227. contains a value that is not a valid device or destination name.
  228. .IP "\fITZ\fP" 10
  229. Determine the timezone used to calculate date and time strings
  230. displayed in the
  231. .IR lp
  232. banner page, if any. If
  233. .IR TZ
  234. is unset or null, an unspecified default timezone shall be used.
  235. .SH "ASYNCHRONOUS EVENTS"
  236. Default.
  237. .SH STDOUT
  238. The
  239. .IR lp
  240. utility shall write a
  241. .IR "request ID"
  242. to the standard output, unless
  243. .BR \-s
  244. is specified. The format of the message is unspecified. The request
  245. ID can be used on systems supporting the historical
  246. .IR cancel
  247. and
  248. .IR lpstat
  249. utilities.
  250. .SH STDERR
  251. The standard error shall be used only for diagnostic messages.
  252. .SH "OUTPUT FILES"
  253. None.
  254. .SH "EXTENDED DESCRIPTION"
  255. None.
  256. .SH "EXIT STATUS"
  257. The following exit values shall be returned:
  258. .IP "\00" 6
  259. All input files were processed successfully.
  260. .IP >0 6
  261. No output device was available, or an error occurred.
  262. .SH "CONSEQUENCES OF ERRORS"
  263. Default.
  264. .LP
  265. .IR "The following sections are informative."
  266. .SH "APPLICATION USAGE"
  267. The
  268. .IR pr
  269. and
  270. .IR fold
  271. utilities can be used to achieve reasonable formatting for the
  272. implementation's default page size.
  273. .P
  274. A conforming application can use one of the
  275. .IR file
  276. operands only with the
  277. .BR \-c
  278. option or if the file is publicly readable and guaranteed to be
  279. available at the time of printing. This is because POSIX.1\(hy2008 gives
  280. the implementation the freedom to queue up the request for printing at
  281. some later time by a different process that might not be able to access
  282. the file.
  283. .SH EXAMPLES
  284. .IP " 1." 4
  285. To print file
  286. .IR file :
  287. .RS 4
  288. .sp
  289. .RS 4
  290. .nf
  291. lp -c \fIfile\fR
  292. .fi
  293. .P
  294. .RE
  295. .RE
  296. .IP " 2." 4
  297. To print multiple files with headers:
  298. .RS 4
  299. .sp
  300. .RS 4
  301. .nf
  302. pr \fIfile1 file2\fP | lp
  303. .fi
  304. .P
  305. .RE
  306. .RE
  307. .SH RATIONALE
  308. The
  309. .IR lp
  310. utility was designed to be a basic version of a utility that is already
  311. available in many historical implementations. The standard developers
  312. considered that it should be implementable simply as:
  313. .sp
  314. .RS 4
  315. .nf
  316. cat "$@" > /dev/lp
  317. .fi
  318. .P
  319. .RE
  320. .P
  321. after appropriate processing of options, if that is how the
  322. implementation chose to do it and if exclusive access could be granted
  323. (so that two users did not write to the device simultaneously).
  324. Although in the future the standard developers may add other options to
  325. this utility, it should always be able to execute with no options or
  326. operands and send the standard input to an unspecified output device.
  327. .P
  328. This volume of POSIX.1\(hy2017 makes no representations concerning the format of the printed
  329. output, except that it must be ``human-readable'' and ``non-volatile''.
  330. Thus, writing by default to a disk or tape drive or a display terminal
  331. would not qualify. (Such destinations are not prohibited when
  332. .BR \-d
  333. .IR dest ,
  334. .IR LPDEST ,
  335. or
  336. .IR PRINTER
  337. are used, however.)
  338. .P
  339. This volume of POSIX.1\(hy2017 is worded such that a ``print job'' consisting of multiple input
  340. files, possibly in multiple copies, is guaranteed to print so that any
  341. one file is not intermixed with another, but there is no statement that
  342. all the files or copies have to print out together.
  343. .P
  344. The
  345. .BR \-c
  346. option may imply a spooling operation, but this is not required. The
  347. utility can be implemented to wait until the printer is ready and then
  348. wait until it is finished. Because of that, there is no attempt to
  349. define a queuing mechanism (priorities, classes of output, and so on).
  350. .P
  351. On some historical systems, the request ID reported on the STDOUT
  352. can be used to later cancel or find the status of a request using
  353. utilities not defined in this volume of POSIX.1\(hy2017.
  354. .P
  355. Although the historical System V
  356. .IR lp
  357. and BSD
  358. .IR lpr
  359. utilities have provided similar functionality, they used different
  360. names for the environment variable specifying the destination printer.
  361. Since the name of the utility here is
  362. .IR lp ,
  363. .IR LPDEST
  364. (used by the System V
  365. .IR lp
  366. utility) was given precedence over
  367. .IR PRINTER
  368. (used by the BSD
  369. .IR lpr
  370. utility). Since environments of users frequently contain one or the
  371. other environment variable, the
  372. .IR lp
  373. utility is required to recognize both. If this was not done, many
  374. applications would send output to unexpected output devices when users
  375. moved from system to system.
  376. .P
  377. Some have commented that
  378. .IR lp
  379. has far too little functionality to make it worthwhile. Requests have
  380. proposed additional options or operands or both that added
  381. functionality. The requests included:
  382. .IP " *" 4
  383. Wording
  384. .IR requiring
  385. the output to be ``hardcopy''
  386. .IP " *" 4
  387. A requirement for multiple printers
  388. .IP " *" 4
  389. Options for supporting various page-description languages
  390. .P
  391. Given that a compliant system is not required to even have a printer,
  392. placing further restrictions upon the behavior of the printer is not
  393. useful. Since hardcopy format is so application-dependent, it is
  394. difficult, if not impossible, to select a reasonable subset of
  395. functionality that should be required on all compliant systems.
  396. .P
  397. The term \fIunspecified\fR is used in this section in lieu of
  398. \fIimplementation-defined\fR as most known implementations would not be
  399. able to make definitive statements in their conformance documents; the
  400. existence and usage of printers is very dependent on how the system
  401. administrator configures each individual system.
  402. .P
  403. Since the default destination, device type, queuing mechanisms, and
  404. acceptable forms of input are all unspecified, usage guidelines for
  405. what a conforming application can do are as follows:
  406. .IP " *" 4
  407. Use the command in a pipeline, or with
  408. .BR \-c ,
  409. so that there are no permission problems and the files can be safely
  410. deleted or modified.
  411. .IP " *" 4
  412. Limit output to text files of reasonable line lengths and printable
  413. characters and include no device-specific formatting information, such
  414. as a page description language. The meaning of ``reasonable'' in this
  415. context can only be answered as a quality-of-implementation issue, but
  416. it should be apparent from historical usage patterns in the industry
  417. and the locale. The
  418. .IR pr
  419. and
  420. .IR fold
  421. utilities can be used to achieve reasonable formatting for the default
  422. page size of the implementation.
  423. .P
  424. Alternatively, the application can arrange its installation in such a
  425. way that it requires the system administrator or operator to provide
  426. the appropriate information on
  427. .IR lp
  428. options and environment variable values.
  429. .P
  430. At a minimum, having this utility in this volume of POSIX.1\(hy2017 tells the industry that
  431. conforming applications require a means to print output and provides at
  432. least a command name and
  433. .IR LPDEST
  434. routing mechanism that can be used for discussions between vendors,
  435. application developers, and users. The use of ``should'' in the
  436. DESCRIPTION of
  437. .IR lp
  438. clearly shows the intent of the standard developers, even if they
  439. cannot mandate that all systems (such as laptops) have printers.
  440. .P
  441. This volume of POSIX.1\(hy2017 does not specify what the ownership of the process performing the
  442. writing to the output device may be. If
  443. .BR \-c
  444. is not used, it is unspecified whether the process performing the
  445. writing to the output device has permission to read
  446. .IR file
  447. if there are any restrictions in place on who may read
  448. .IR file
  449. until after it is printed. Also, if
  450. .BR \-c
  451. is not used, the results of deleting
  452. .IR file
  453. before it is printed are unspecified.
  454. .SH "FUTURE DIRECTIONS"
  455. None.
  456. .SH "SEE ALSO"
  457. .IR "\fImailx\fR\^"
  458. .P
  459. The Base Definitions volume of POSIX.1\(hy2017,
  460. .IR "Chapter 8" ", " "Environment Variables",
  461. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  462. .\"
  463. .SH COPYRIGHT
  464. Portions of this text are reprinted and reproduced in electronic form
  465. from IEEE Std 1003.1-2017, Standard for Information Technology
  466. -- Portable Operating System Interface (POSIX), The Open Group Base
  467. Specifications Issue 7, 2018 Edition,
  468. Copyright (C) 2018 by the Institute of
  469. Electrical and Electronics Engineers, Inc and The Open Group.
  470. In the event of any discrepancy between this version and the original IEEE and
  471. The Open Group Standard, the original IEEE and The Open Group Standard
  472. is the referee document. The original Standard can be obtained online at
  473. http://www.opengroup.org/unix/online.html .
  474. .PP
  475. Any typographical or formatting errors that appear
  476. in this page are most likely
  477. to have been introduced during the conversion of the source files to
  478. man page format. To report such errors, see
  479. https://www.kernel.org/doc/man-pages/reporting_bugs.html .