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
11

NAME

13       pr — print files
14

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

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

OPERANDS

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

STDIN

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

INPUT FILES

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

ENVIRONMENT VARIABLES

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

ASYNCHRONOUS EVENTS

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

STDOUT

212       The pr utility output shall be a paginated version of the original file
213       (or  files).  This pagination shall be accomplished using either <form-
214       feed> characters or a sequence of <newline> characters,  as  controlled
215       by  the  −F or −f option. Page headers shall be generated unless the −t
216       option is specified. The page headers shall be of the form:
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           date "+%b %e %H:%M %Y"
227
228       without the trailing <newline>, if the page being written is from stan‐
229       dard  input.  If  the page being written is not from standard input, in
230       the POSIX locale, the same format shall be  used,  but  the  time  used
231       shall  be  the  modification  time  of  the  file corresponding to file
232       instead of the current time. When the LC_TIME locale  category  is  not
233       set  to  the POSIX locale, a different format and order of presentation
234       of this field may be used.
235
236       If the standard input is used instead of a  file  operand,  the  <file>
237       field shall be replaced by a null string.
238
239       If  the  −h  option is specified, the <file> field shall be replaced by
240       the header argument.
241

STDERR

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

OUTPUT FILES

247       None.
248

EXTENDED DESCRIPTION

250       None.
251

EXIT STATUS

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

CONSEQUENCES OF ERRORS

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

APPLICATION USAGE

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

EXAMPLES

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

RATIONALE

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

FUTURE DIRECTIONS

327       None.
328

SEE ALSO

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