1PR(1P)                     POSIX Programmer's Manual                    PR(1P)
2
3
4

PROLOG

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

NAME

12       pr — print files
13

SYNOPSIS

15       pr [+page] [-column] [-adFmrt] [-e[char][gap]] [-h header] [-i[char][gap]]
16           [-l lines] [-n[char][width]] [-o offset] [-s[char]] [-w width] [-fp]
17           [file...]
18

DESCRIPTION

20       The pr utility is a printing and pagination filter. If  multiple  input
21       files  are  specified,  each  shall  be read, formatted, and written to
22       standard output. By default, the input shall be separated into  66-line
23       pages, each with:
24
25        *  A  5-line header that includes the page number, date, time, and the
26           pathname of the file
27
28        *  A 5-line trailer consisting of blank lines
29
30       If standard output is associated with a terminal,  diagnostic  messages
31       shall be deferred until the pr utility has completed processing.
32
33       When  options specifying multi-column output are specified, output text
34       columns shall be of equal width; input lines that do  not  fit  into  a
35       text column shall be truncated. By default, text columns shall be sepa‐
36       rated with at least one <blank>.
37

OPTIONS

39       The pr  utility  shall  conform  to  the  Base  Definitions  volume  of
40       POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines, except that: the
41       page option has a '+' delimiter; page and  column  can  be  multi-digit
42       numbers;  some  of  the  option-arguments are optional; and some of the
43       option-arguments cannot be specified as  separate  arguments  from  the
44       preceding  option  letter.  In particular, the -s option does not allow
45       the option letter to be separated from its argument,  and  the  options
46       -e,  -i,  and  -n require that both arguments, if present, not be sepa‐
47       rated from the option letter.
48
49       The following options shall  be  supported.  In  the  following  option
50       descriptions, column, lines, offset, page, and width are positive deci‐
51       mal integers; gap is a non-negative decimal integer.
52
53       +page     Begin output at page number page of the formatted input.
54
55       -column   Produce multi-column output that is arranged in  column  col‐
56                 umns (the default shall be 1) and is written down each column
57                 in the order in which the text is  received  from  the  input
58                 file. This option should not be used with -m.  The options -e
59                 and -i shall be  assumed  for  multiple  text-column  output.
60                 Whether  or not text columns are produced with identical ver‐
61                 tical lengths is unspecified, but a text column  shall  never
62                 exceed  the length of the page (see the -l option). When used
63                 with -t, use the minimum number of lines to write the output.
64
65       -a        Modify the effect of the -column option so that  the  columns
66                 are  filled across the page in a round-robin order (for exam‐
67                 ple, when column is 2, the first input line heads  column  1,
68                 the  second  heads  column 2, the third is the second line in
69                 column 1, and so on).
70
71       -d        Produce output that is double-spaced; append an  extra  <new‐
72                 line> following every <newline> found in the input.
73
74       -e[char][gap]
75                 Expand  each  input <tab> to the next greater column position
76                 specified by the formula n*gap+1, where n is an integer >  0.
77                 If  gap  is  zero  or  is omitted, it shall default to 8. All
78                 <tab> characters in the input  shall  be  expanded  into  the
79                 appropriate  number  of  <space> characters. If any non-digit
80                 character, char, is specified, it shall be used as the  input
81                 <tab>.  If the first character of the -e option-argument is a
82                 digit, the entire option-argument shall be assumed to be gap.
83
84       -f        Use a <form-feed> for  new  pages,  instead  of  the  default
85                 behavior  that uses a sequence of <newline> characters. Pause
86                 before beginning the first page if  the  standard  output  is
87                 associated with a terminal.
88
89       -F        Use  a  <form-feed>  for  new  pages,  instead of the default
90                 behavior that uses a sequence of <newline> characters.
91
92       -h header Use the string header to replace the contents of the file op‐
93                 erand in the page header.
94
95       -i[char][gap]
96                 In  output,  replace <space> characters with <tab> characters
97                 wherever one or more adjacent <space> characters reach column
98                 positions  gap+1,  2*  gap+1,  3* gap+1, and so on. If gap is
99                 zero or is omitted, default tab settings at every eighth col‐
100                 umn  position  shall  be assumed. If any non-digit character,
101                 char, is specified, it shall be used as the output <tab>.  If
102                 the first character of the -i option-argument is a digit, the
103                 entire option-argument shall be assumed to be gap.
104
105       -l lines  Override the 66-line default and reset  the  page  length  to
106                 lines.   If  lines  is  not  greater than the sum of both the
107                 header and trailer depths (in lines), the  pr  utility  shall
108                 suppress  both  the  header  and trailer, as if the -t option
109                 were in effect.
110
111       -m        Merge files. Standard output shall be  formatted  so  the  pr
112                 utility  writes  one  line from each file specified by a file
113                 operand, side by  side  into  text  columns  of  equal  fixed
114                 widths, in terms of the number of column positions. Implemen‐
115                 tations shall support merging of at least nine file operands.
116
117       -n[char][width]
118                 Provide width-digit line numbering (default for  width  shall
119                 be  5).  The number shall occupy the first width column posi‐
120                 tions of each text column of default output or each  line  of
121                 -m  output.  If  char  (any non-digit character) is given, it
122                 shall be appended to the line  number  to  separate  it  from
123                 whatever follows (default for char is a <tab>).
124
125       -o offset Each line of output shall be preceded by offset <space> char‐
126                 acters. If the -o option is not specified, the default offset
127                 shall  be  zero. The space taken is in addition to the output
128                 line width (see the -w option below).
129
130       -p        Pause before beginning each page if the  standard  output  is
131                 directed to a terminal (pr shall write an <alert> to standard
132                 error  and  wait  for  a  <carriage-return>  to  be  read  on
133                 /dev/tty).
134
135       -r        Write no diagnostic reports on failure to open files.
136
137       -s[char]  Separate text columns by the single character char instead of
138                 by the appropriate number of <space> characters (default  for
139                 char shall be <tab>).
140
141       -t        Write  neither the five-line identifying header nor the five-
142                 line trailer usually supplied for  each  page.  Quit  writing
143                 after  the  last line of each file without spacing to the end
144                 of the page.
145
146       -w width  Set the width of the line to width column positions for  mul‐
147                 tiple text-column output only. If the -w option is not speci‐
148                 fied and the -s option is not specified,  the  default  width
149                 shall  be  72.  If  the -w option is not specified and the -s
150                 option is specified, the default width shall be 512.
151
152                 For single column output, input lines shall not be truncated.
153

OPERANDS

155       The following operand shall be supported:
156
157       file      A pathname of a file to be written. If no file  operands  are
158                 specified,  or  if  a file operand is '-', the standard input
159                 shall be used.
160

STDIN

162       The standard input shall be used only if no file  operands  are  speci‐
163       fied, or if a file operand is '-'.  See the INPUT FILES section.
164

INPUT FILES

166       The input files shall be text files.
167
168       The  file  /dev/tty  shall be used to read responses required by the -p
169       option.
170

ENVIRONMENT VARIABLES

172       The following environment variables shall affect the execution of pr:
173
174       LANG      Provide a default value for  the  internationalization  vari‐
175                 ables  that are unset or null. (See the Base Definitions vol‐
176                 ume of POSIX.1‐2017, Section 8.2, Internationalization  Vari‐
177                 ables  the  precedence of internationalization variables used
178                 to determine the values of locale categories.)
179
180       LC_ALL    If set to a non-empty string value, override  the  values  of
181                 all the other internationalization variables.
182
183       LC_CTYPE  Determine  the  locale for the interpretation of sequences of
184                 bytes of text data as characters (for example, single-byte as
185                 opposed  to  multi-byte  characters  in  arguments  and input
186                 files) and which characters are defined as printable (charac‐
187                 ter class print).  Non-printable characters are still written
188                 to standard output, but are not counted for the  purpose  for
189                 column-width and line-length calculations.
190
191       LC_MESSAGES
192                 Determine the locale that should be used to affect the format
193                 and contents  of  diagnostic  messages  written  to  standard
194                 error.
195
196       LC_TIME   Determine  the format of the date and time for use in writing
197                 header lines.
198
199       NLSPATH   Determine the location of message catalogs for the processing
200                 of LC_MESSAGES.
201
202       TZ        Determine  the  timezone  used  to  calculate  date  and time
203                 strings written in header lines. If TZ is unset or  null,  an
204                 unspecified default timezone shall be used.
205

ASYNCHRONOUS EVENTS

207       If pr receives an interrupt while writing to a terminal, it shall flush
208       all accumulated error messages to the screen before terminating.
209

STDOUT

211       The pr utility output shall be a paginated version of the original file
212       (or  files).  This pagination shall be accomplished using either <form-
213       feed> characters or a sequence of <newline> characters,  as  controlled
214       by  the  -F or -f option. Page headers shall be generated unless the -t
215       option is specified. The page headers shall be of the form:
216
217
218           "\n\n%s %s Page %d\n\n\n", <output of date>, <file>, <page number>
219
220       In the POSIX locale, the <output of date> field, representing the  date
221       and  time  of  last modification of the input file (or the current date
222       and time if the input file is standard input), shall be  equivalent  to
223       the  output  of the following command as it would appear if executed at
224       the given time:
225
226
227           date "+%b %e %H:%M %Y"
228
229       without the trailing <newline>, if the page being written is from stan‐
230       dard  input.  If  the page being written is not from standard input, in
231       the POSIX locale, the same format shall be  used,  but  the  time  used
232       shall  be  the  modification  time  of  the  file corresponding to file
233       instead of the current time. When the LC_TIME locale  category  is  not
234       set  to  the POSIX locale, a different format and order of presentation
235       of this field may be used.
236
237       If the standard input is used instead of a  file  operand,  the  <file>
238       field shall be replaced by a null string.
239
240       If  the  -h  option is specified, the <file> field shall be replaced by
241       the header argument.
242

STDERR

244       The standard error shall be used for diagnostic messages and for alert‐
245       ing the terminal when -p is specified.
246

OUTPUT FILES

248       None.
249

EXTENDED DESCRIPTION

251       None.
252

EXIT STATUS

254       The following exit values shall be returned:
255
256        0    Successful completion.
257
258       >0    An error occurred.
259

CONSEQUENCES OF ERRORS

261       Default.
262
263       The following sections are informative.
264

APPLICATION USAGE

266       A  conforming  application must protect its first operand, if it starts
267       with a <plus-sign>, by preceding it with the "--" argument that denotes
268       the  end  of  the options. For example, pr+x could be interpreted as an
269       invalid page number or a file operand.
270

EXAMPLES

272        1. Print a numbered list of all files in the current directory:
273
274
275               ls -a | pr -n -h "Files in $(pwd)."
276
277        2. Print file1 and file2  as  a  double-spaced,  three-column  listing
278           headed by ``file list'':
279
280
281               pr -3d -h "file list" file1 file2
282
283        3. Write file1 on file2, expanding tabs to columns 10, 19, 28, ...:
284
285
286               pr -e9 -t <file1 >file2
287

RATIONALE

289       This  utility  is  one of those that does not follow the Utility Syntax
290       Guidelines because of its historical origins. The  standard  developers
291       could have added new options that obeyed the guidelines (and marked the
292       old options obsolescent) or devised an entirely new utility; there  are
293       examples of both actions in this volume of POSIX.1‐2017. Because of its
294       widespread use by  historical  applications,  the  standard  developers
295       decided to exempt this version of pr from many of the guidelines.
296
297       Implementations  are required to accept option-arguments to the -h, -l,
298       -o, and -w options whether presented as part of the same argument or as
299       a  separate  argument  to pr, as suggested by the Utility Syntax Guide‐
300       lines. The -n and -s options, however, are specified as  in  historical
301       practice  because  they are frequently specified without their optional
302       arguments. If a <blank> were  allowed  before  the  option-argument  in
303       these  cases,  a  file  operand  could  mistakenly be interpreted as an
304       option-argument in historical applications.
305
306       The text about the minimum number of lines in multi-column  output  was
307       included  to  ensure that a best effort is made in balancing the length
308       of the columns. There are known historical  implementations  in  which,
309       for  example,  60-line  files  are  listed by pr -2 as one column of 56
310       lines and a second of 4. Although this is not a  problem  when  a  full
311       page with headers and trailers is produced, it would be relatively use‐
312       less when used with -t.
313
314       Historical implementations of the  pr  utility  have  differed  in  the
315       action  taken  for the -f option. BSD uses it as described here for the
316       -F option; System V uses it to change trailing <newline> characters  on
317       each  page  to  a  <form-feed> and, if standard output is a TTY device,
318       sends an <alert> to standard error  and  reads  a  line  from  /dev/tty
319       before  the  first page. There were strong arguments from both sides of
320       this issue concerning historical practice and as a result the -F option
321       was  added.  XSI-conformant  systems  support  the  System V historical
322       actions for the -f option.
323
324       The <output of date> field in the -l format is specified only  for  the
325       POSIX  locale.  As noted, the format can be different in other locales.
326       No  mechanism  for  defining  this  is  present  in  this   volume   of
327       POSIX.1‐2017, as the appropriate vehicle is a message catalog; that is,
328       the format should be specified as a ``message''.
329

FUTURE DIRECTIONS

331       None.
332

SEE ALSO

334       expand, lp
335
336       The Base Definitions volume of  POSIX.1‐2017,  Chapter  8,  Environment
337       Variables, Section 12.2, Utility Syntax Guidelines
338
340       Portions  of  this text are reprinted and reproduced in electronic form
341       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
342       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
343       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
344       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
345       event of any discrepancy between this version and the original IEEE and
346       The  Open Group Standard, the original IEEE and The Open Group Standard
347       is the referee document. The original Standard can be  obtained  online
348       at http://www.opengroup.org/unix/online.html .
349
350       Any  typographical  or  formatting  errors that appear in this page are
351       most likely to have been introduced during the conversion of the source
352       files  to  man page format. To report such errors, see https://www.ker
353       nel.org/doc/man-pages/reporting_bugs.html .
354
355
356
357IEEE/The Open Group                  2017                               PR(1P)
Impressum