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

pr.1p (15949B)


  1. '\" et
  2. .TH PR "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. pr
  12. \(em print files
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. pr \fB[\fR+\fIpage\fB] [\fR-\fIcolumn\fB] [\fR-adFmrt\fB] [\fR-e\fB[\fIchar\fB][\fIgap\fB]] [\fR-h \fIheader\fB] [\fR-i\fB[\fIchar\fB][\fIgap\fB]]
  17. [\fR-l \fIlines\fB] [\fR-n\fB[\fIchar\fB][\fIwidth\fB]] [\fR-o \fIoffset\fB] [\fR-s\fB[\fIchar\fB]] [\fR-w \fIwidth\fB] [\fR-fp\fB]
  18. [\fIfile\fR...\fB]\fR
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. .IR pr
  23. utility is a printing and pagination filter. If multiple input files
  24. are specified, each shall be read, formatted, and written to standard
  25. output. By default, the input shall be separated into 66-line pages,
  26. each with:
  27. .IP " *" 4
  28. A 5-line header that includes the page number, date, time, and
  29. the pathname of the file
  30. .IP " *" 4
  31. A 5-line trailer consisting of blank lines
  32. .P
  33. If standard output is associated with a terminal, diagnostic messages
  34. shall be deferred until the
  35. .IR pr
  36. utility has completed processing.
  37. .P
  38. When options specifying multi-column output are specified, output text
  39. columns shall be of equal width; input lines that do not fit into a
  40. text column shall be truncated. By default, text columns shall be
  41. separated with at least one
  42. <blank>.
  43. .SH OPTIONS
  44. The
  45. .IR pr
  46. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  47. .IR "Section 12.2" ", " "Utility Syntax Guidelines",
  48. except that: the
  49. .IR page
  50. option has a
  51. .BR '\(pl'
  52. delimiter;
  53. .IR page
  54. and
  55. .IR column
  56. can be multi-digit numbers; some of the option-arguments are optional;
  57. and some of the option-arguments cannot be specified as separate
  58. arguments from the preceding option letter. In particular, the
  59. .BR \-s
  60. option does not allow the option letter to be separated from its
  61. argument, and the options
  62. .BR \-e ,
  63. .BR \-i ,
  64. and
  65. .BR \-n
  66. require that both arguments, if present, not be separated from the
  67. option letter.
  68. .P
  69. The following options shall be supported. In the following option
  70. descriptions,
  71. .IR column ,
  72. .IR lines ,
  73. .IR offset ,
  74. .IR page ,
  75. and
  76. .IR width
  77. are positive decimal integers;
  78. .IR gap
  79. is a non-negative decimal integer.
  80. .IP "\fB+\fIpage\fR" 10
  81. Begin output at page number
  82. .IR page
  83. of the formatted input.
  84. .IP "\fB\-\fIcolumn\fR" 10
  85. Produce multi-column output that is arranged in
  86. .IR column
  87. columns (the default shall be 1) and is written down each column in the
  88. order in which the text is received from the input file. This option
  89. should not be used with
  90. .BR \-m .
  91. The options
  92. .BR \-e
  93. and
  94. .BR \-i
  95. shall be assumed for multiple text-column output. Whether or not text
  96. columns are produced with identical vertical lengths is unspecified,
  97. but a text column shall never exceed the length of the page (see the
  98. .BR \-l
  99. option). When used with
  100. .BR \-t ,
  101. use the minimum number of lines to write the output.
  102. .IP "\fB\-a\fP" 10
  103. Modify the effect of the
  104. .BR \- \c
  105. .IR column
  106. option so that the columns are filled across the page in a round-robin
  107. order (for example, when
  108. .IR column
  109. is 2, the first input line heads column 1, the second heads column 2,
  110. the third is the second line in column 1, and so on).
  111. .IP "\fB\-d\fP" 10
  112. Produce output that is double-spaced; append an extra
  113. <newline>
  114. following every
  115. <newline>
  116. found in the input.
  117. .IP "\fB\-e[\fIchar\fB][\fIgap\fB]\fR" 10
  118. .br
  119. Expand each input
  120. <tab>
  121. to the next greater column position specified by the formula
  122. .IR n *\c
  123. .IR gap +1,
  124. where
  125. .IR n
  126. is an integer > 0. If
  127. .IR gap
  128. is zero or is omitted, it shall default to 8. All
  129. <tab>
  130. characters in the input shall be expanded into the appropriate number of
  131. <space>
  132. characters. If any non-digit character,
  133. .IR char ,
  134. is specified, it shall be used as the input
  135. <tab>.
  136. If the first character of the
  137. .BR \-e
  138. option-argument is a digit, the entire option-argument shall be assumed
  139. to be
  140. .IR gap .
  141. .IP "\fB\-f\fP" 10
  142. Use a
  143. <form-feed>
  144. for new pages, instead of the default behavior that uses a sequence of
  145. <newline>
  146. characters. Pause before beginning the first page if the standard output
  147. is associated with a terminal.
  148. .IP "\fB\-F\fP" 10
  149. Use a
  150. <form-feed>
  151. for new pages, instead of the default behavior that uses a sequence of
  152. <newline>
  153. characters.
  154. .IP "\fB\-h\ \fIheader\fR" 10
  155. Use the string
  156. .IR header
  157. to replace the contents of the
  158. .IR file
  159. operand in the page header.
  160. .IP "\fB\-i[\fIchar\fB][\fIgap\fB]\fR" 10
  161. In output, replace
  162. <space>
  163. characters with
  164. <tab>
  165. characters wherever one or more adjacent
  166. <space>
  167. characters reach column positions
  168. .IR gap +1,
  169. 2*
  170. .IR gap +1,
  171. 3*
  172. .IR gap +1,
  173. and so on. If
  174. .IR gap
  175. is zero or is omitted, default tab settings at every eighth column
  176. position shall be assumed. If any non-digit character,
  177. .IR char ,
  178. is specified, it shall be used as the output
  179. <tab>.
  180. If the first character of the
  181. .BR \-i
  182. option-argument is a digit, the entire option-argument shall be assumed
  183. to be
  184. .IR gap .
  185. .IP "\fB\-l\ \fIlines\fR" 10
  186. Override the 66-line default and reset the page length to
  187. .IR lines .
  188. If
  189. .IR lines
  190. is not greater than the sum of both the header and trailer depths (in
  191. lines), the
  192. .IR pr
  193. utility shall suppress both the header and trailer, as if the
  194. .BR \-t
  195. option were in effect.
  196. .IP "\fB\-m\fP" 10
  197. Merge files. Standard output shall be formatted so the
  198. .IR pr
  199. utility writes one line from each file specified by a
  200. .IR file
  201. operand, side by side into text columns of equal fixed widths, in terms
  202. of the number of column positions. Implementations shall support
  203. merging of at least nine
  204. .IR file
  205. operands.
  206. .IP "\fB\-n[\fIchar\fB][\fIwidth\fB]\fR" 10
  207. .br
  208. Provide
  209. .IR width -digit
  210. line numbering (default for
  211. .IR width
  212. shall be 5). The number shall occupy the first
  213. .IR width
  214. column positions of each text column of default output or each line of
  215. .BR \-m
  216. output. If
  217. .IR char
  218. (any non-digit character) is given, it shall be appended to the line
  219. number to separate it from whatever follows (default for
  220. .IR char
  221. is a
  222. <tab>).
  223. .IP "\fB\-o\ \fIoffset\fR" 10
  224. Each line of output shall be preceded by offset
  225. <space>
  226. characters. If the
  227. .BR \-o
  228. option is not specified, the default offset shall be zero. The space
  229. taken is in addition to the output line width (see the
  230. .BR \-w
  231. option below).
  232. .IP "\fB\-p\fP" 10
  233. Pause before beginning each page if the standard output is directed to
  234. a terminal (\c
  235. .IR pr
  236. shall write an
  237. <alert>
  238. to standard error and wait for a
  239. <carriage-return>
  240. to be read on
  241. .BR /dev/tty ).
  242. .IP "\fB\-r\fP" 10
  243. Write no diagnostic reports on failure to open files.
  244. .IP "\fB\-s[\fIchar\fB]\fR" 10
  245. Separate text columns by the single character
  246. .IR char
  247. instead of by the appropriate number of
  248. <space>
  249. characters (default for
  250. .IR char
  251. shall be
  252. <tab>).
  253. .IP "\fB\-t\fP" 10
  254. Write neither the five-line identifying header nor the five-line
  255. trailer usually supplied for each page. Quit writing after the last
  256. line of each file without spacing to the end of the page.
  257. .IP "\fB\-w\ \fIwidth\fR" 10
  258. Set the width of the line to
  259. .IR width
  260. column positions for multiple text-column output only. If the
  261. .BR \-w
  262. option is not specified and the
  263. .BR \-s
  264. option is not specified, the default width shall be 72. If the
  265. .BR \-w
  266. option is not specified and the
  267. .BR \-s
  268. option is specified, the default width shall be 512.
  269. .RS 10
  270. .P
  271. For single column output, input lines shall not be truncated.
  272. .RE
  273. .SH OPERANDS
  274. The following operand shall be supported:
  275. .IP "\fIfile\fR" 10
  276. A pathname of a file to be written. If no
  277. .IR file
  278. operands are specified, or if a
  279. .IR file
  280. operand is
  281. .BR '\-' ,
  282. the standard input shall be used.
  283. .SH STDIN
  284. The standard input shall be used only if no
  285. .IR file
  286. operands are specified, or if a
  287. .IR file
  288. operand is
  289. .BR '\-' .
  290. See the INPUT FILES section.
  291. .SH "INPUT FILES"
  292. The input files shall be text files.
  293. .P
  294. The file
  295. .BR /dev/tty
  296. shall be used to read responses required by the
  297. .BR \-p
  298. option.
  299. .SH "ENVIRONMENT VARIABLES"
  300. The following environment variables shall affect the execution of
  301. .IR pr :
  302. .IP "\fILANG\fP" 10
  303. Provide a default value for the internationalization variables that are
  304. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  305. .IR "Section 8.2" ", " "Internationalization Variables"
  306. the precedence of internationalization variables used to determine the
  307. values of locale categories.)
  308. .IP "\fILC_ALL\fP" 10
  309. If set to a non-empty string value, override the values of all the
  310. other internationalization variables.
  311. .IP "\fILC_CTYPE\fP" 10
  312. Determine the locale for the interpretation of sequences of bytes of
  313. text data as characters (for example, single-byte as opposed to
  314. multi-byte characters in arguments and input files) and which
  315. characters are defined as printable (character class
  316. .BR print ).
  317. Non-printable characters are still written to standard output, but are
  318. not counted for the purpose for column-width and line-length
  319. calculations.
  320. .IP "\fILC_MESSAGES\fP" 10
  321. .br
  322. Determine the locale that should be used to affect the format and
  323. contents of diagnostic messages written to standard error.
  324. .IP "\fILC_TIME\fP" 10
  325. Determine the format of the date and time for use in writing header
  326. lines.
  327. .IP "\fINLSPATH\fP" 10
  328. Determine the location of message catalogs for the processing of
  329. .IR LC_MESSAGES .
  330. .IP "\fITZ\fP" 10
  331. Determine the timezone used to calculate date and time strings written
  332. in header lines. If
  333. .IR TZ
  334. is unset or null, an unspecified default timezone shall be used.
  335. .SH "ASYNCHRONOUS EVENTS"
  336. If
  337. .IR pr
  338. receives an interrupt while writing to a terminal, it shall flush all
  339. accumulated error messages to the screen before terminating.
  340. .SH STDOUT
  341. The
  342. .IR pr
  343. utility output shall be a paginated version of the original file (or
  344. files). This pagination shall be accomplished using either
  345. <form-feed>
  346. characters or a sequence of
  347. <newline>
  348. characters, as controlled by the
  349. .BR \-F
  350. or
  351. .BR \-f
  352. option. Page headers shall be generated unless the
  353. .BR \-t
  354. option is specified. The page headers shall be of the form:
  355. .sp
  356. .RS 4
  357. .nf
  358. "\en\en%s %s Page %d\en\en\en", <\fIoutput of date\fP>, <\fIfile\fR>, <\fIpage number\fR>
  359. .fi
  360. .P
  361. .RE
  362. .P
  363. In the POSIX locale, the <\fIoutput\ of\ date\fR> field, representing
  364. the date and time of last modification of the input file (or the
  365. current date and time if the input file is standard input), shall be
  366. equivalent to the output of the following command as it would appear if
  367. executed at the given time:
  368. .sp
  369. .RS 4
  370. .nf
  371. date "+%b %e %H:%M %Y"
  372. .fi
  373. .P
  374. .RE
  375. .P
  376. without the trailing
  377. <newline>,
  378. if the page being written is from standard input. If the page being
  379. written is not from standard input, in the POSIX locale, the same
  380. format shall be used, but the time used shall be the modification time
  381. of the file corresponding to
  382. .IR file
  383. instead of the current time. When the
  384. .IR LC_TIME
  385. locale category is not set to the POSIX locale, a different format and
  386. order of presentation of this field may be used.
  387. .P
  388. If the standard input is used instead of a
  389. .IR file
  390. operand, the <\fIfile\fP> field shall be replaced by a null string.
  391. .P
  392. If the
  393. .BR \-h
  394. option is specified, the <\fIfile\fP> field shall be replaced by the
  395. .IR header
  396. argument.
  397. .SH STDERR
  398. The standard error shall be used for diagnostic messages and
  399. for alerting the terminal when
  400. .BR \-p
  401. is specified.
  402. .SH "OUTPUT FILES"
  403. None.
  404. .SH "EXTENDED DESCRIPTION"
  405. None.
  406. .SH "EXIT STATUS"
  407. The following exit values shall be returned:
  408. .IP "\00" 6
  409. Successful completion.
  410. .IP >0 6
  411. An error occurred.
  412. .SH "CONSEQUENCES OF ERRORS"
  413. Default.
  414. .LP
  415. .IR "The following sections are informative."
  416. .SH "APPLICATION USAGE"
  417. A conforming application must protect its first operand, if it starts
  418. with a
  419. <plus-sign>,
  420. by preceding it with the
  421. .BR \(dq--\(dq
  422. argument that denotes the end of the options. For example,
  423. .IR pr \(pl\c
  424. .IR x
  425. could be interpreted as an invalid page number or a
  426. .IR file
  427. operand.
  428. .SH EXAMPLES
  429. .IP " 1." 4
  430. Print a numbered list of all files in the current directory:
  431. .RS 4
  432. .sp
  433. .RS 4
  434. .nf
  435. ls -a | pr -n -h "Files in $(pwd)."
  436. .fi
  437. .P
  438. .RE
  439. .RE
  440. .IP " 2." 4
  441. Print
  442. .BR file1
  443. and
  444. .BR file2
  445. as a double-spaced, three-column listing headed by ``file list'':
  446. .RS 4
  447. .sp
  448. .RS 4
  449. .nf
  450. pr -3d -h "file list" file1 file2
  451. .fi
  452. .P
  453. .RE
  454. .RE
  455. .IP " 3." 4
  456. Write
  457. .BR file1
  458. on
  459. .BR file2 ,
  460. expanding tabs to columns 10, 19, 28, .\|.\|.:
  461. .RS 4
  462. .sp
  463. .RS 4
  464. .nf
  465. pr -e9 -t <file1 >file2
  466. .fi
  467. .P
  468. .RE
  469. .RE
  470. .SH RATIONALE
  471. This utility is one of those that does not follow the Utility Syntax
  472. Guidelines because of its historical origins. The standard developers
  473. could have added new options that obeyed the guidelines (and marked the
  474. old options obsolescent) or devised an entirely new utility; there are
  475. examples of both actions in this volume of POSIX.1\(hy2017. Because of its widespread use by
  476. historical applications, the standard developers decided to exempt this
  477. version of
  478. .IR pr
  479. from many of the guidelines.
  480. .P
  481. Implementations are required to accept option-arguments to the
  482. .BR \-h ,
  483. .BR \-l ,
  484. .BR \-o ,
  485. and
  486. .BR \-w
  487. options whether presented as part of the same argument or as a separate
  488. argument to
  489. .IR pr ,
  490. as suggested by the Utility Syntax Guidelines. The
  491. .BR \-n
  492. and
  493. .BR \-s
  494. options, however, are specified as in historical practice because they
  495. are frequently specified without their optional arguments. If a
  496. <blank>
  497. were allowed before the option-argument in these cases, a
  498. .IR file
  499. operand could mistakenly be interpreted as an option-argument in
  500. historical applications.
  501. .P
  502. The text about the minimum number of lines in multi-column output was
  503. included to ensure that a best effort is made in balancing the length
  504. of the columns. There are known historical implementations in which,
  505. for example, 60-line files are listed by
  506. .IR pr
  507. \-2 as one column of 56 lines and a second of 4. Although this is not
  508. a problem when a full page with headers and trailers is produced, it
  509. would be relatively useless when used with
  510. .BR \-t .
  511. .P
  512. Historical implementations of the
  513. .IR pr
  514. utility have differed in the action taken for the
  515. .BR \-f
  516. option. BSD uses it as described here for the
  517. .BR \-F
  518. option; System V uses it to change trailing
  519. <newline>
  520. characters on each page to a
  521. <form-feed>
  522. and, if standard output is a TTY device, sends an
  523. <alert>
  524. to standard error and reads a line from
  525. .BR /dev/tty
  526. before the first page. There were strong arguments from both sides of
  527. this issue concerning historical practice and as a result the
  528. .BR \-F
  529. option was added. XSI-conformant systems support the System V
  530. historical actions for the
  531. .BR \-f
  532. option.
  533. .P
  534. The <\fIoutput\ of\ date\fP> field in the
  535. .BR \-l
  536. format is specified only for the POSIX locale. As noted, the format can
  537. be different in other locales. No mechanism for defining this is
  538. present in this volume of POSIX.1\(hy2017, as the appropriate vehicle is a message catalog;
  539. that is, the format should be specified as a ``message''.
  540. .SH "FUTURE DIRECTIONS"
  541. None.
  542. .SH "SEE ALSO"
  543. .IR "\fIexpand\fR\^",
  544. .IR "\fIlp\fR\^"
  545. .P
  546. The Base Definitions volume of POSIX.1\(hy2017,
  547. .IR "Chapter 8" ", " "Environment Variables",
  548. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  549. .\"
  550. .SH COPYRIGHT
  551. Portions of this text are reprinted and reproduced in electronic form
  552. from IEEE Std 1003.1-2017, Standard for Information Technology
  553. -- Portable Operating System Interface (POSIX), The Open Group Base
  554. Specifications Issue 7, 2018 Edition,
  555. Copyright (C) 2018 by the Institute of
  556. Electrical and Electronics Engineers, Inc and The Open Group.
  557. In the event of any discrepancy between this version and the original IEEE and
  558. The Open Group Standard, the original IEEE and The Open Group Standard
  559. is the referee document. The original Standard can be obtained online at
  560. http://www.opengroup.org/unix/online.html .
  561. .PP
  562. Any typographical or formatting errors that appear
  563. in this page are most likely
  564. to have been introduced during the conversion of the source files to
  565. man page format. To report such errors, see
  566. https://www.kernel.org/doc/man-pages/reporting_bugs.html .