| blob | c0997f906770790bf5d2465d19e4082419167cde |
1 .\" $NetBSD: pr.1,v 1.22 2012/08/01 02:36:17 ginsbach Exp $
2 .\"
3 .\" Copyright (c) 1991 Keith Muller.
4 .\" Copyright (c) 1993
5 .\" The Regents of the University of California. All rights reserved.
6 .\" Copyright (c) 1994-1995, 1997, 1999-2003, 2009, 2012
7 .\" The NetBSD Foundation, Inc.
8 .\"
9 .\" This code is derived from software contributed to Berkeley by
10 .\" Keith Muller of the University of California, San Diego.
11 .\"
12 .\" Redistribution and use in source and binary forms, with or without
13 .\" modification, are permitted provided that the following conditions
14 .\" are met:
15 .\" 1. Redistributions of source code must retain the above copyright
16 .\" notice, this list of conditions and the following disclaimer.
17 .\" 2. Redistributions in binary form must reproduce the above copyright
18 .\" notice, this list of conditions and the following disclaimer in the
19 .\" documentation and/or other materials provided with the distribution.
20 .\" 3. Neither the name of the University nor the names of its contributors
21 .\" may be used to endorse or promote products derived from this software
22 .\" without specific prior written permission.
23 .\"
24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 .\" SUCH DAMAGE.
35 .\"
36 .\" from: @(#)pr.1 8.1 (Berkeley) 6/6/93
37 .\"
38 .Dd July 31, 2012
39 .Dt PR 1
40 .Os
41 .Sh NAME
42 .Nm pr
43 .Nd print files
44 .Sh SYNOPSIS
45 .Nm
46 .Op Ar \&+page
47 .Op Fl Ar column
48 .Op Fl adFfmprt
49 .Oo
50 .Fl e Ns Oo Ar char Oc Ns Op Ar gap
51 .Oc
52 .Op Fl h Ar header
53 .Oo
54 .Fl i Ns Oo Ar char Oc Ns Op Ar gap
55 .Oc
56 .Op Fl l Ar lines
57 .Oo
58 .Fl n Ns Oo Ar char Oc Ns Op Ar width
59 .Oc
60 .Op Fl o Ar offset
61 .Oo
62 .Fl s Ns Op Ar char
63 .Oc
64 .Op Fl T Ar timefmt
65 .Op Fl w Ar width
66 .Op -
67 .Op Ar file ...
68 .Sh DESCRIPTION
69 The
70 .Nm
71 utility is a printing and pagination filter for text files.
72 When multiple input files are specified, each is read, formatted,
73 and written to standard output.
74 By default, the input is separated into 66-line pages, each with
75 .Bl -bullet
76 .It
77 A 5-line header with the page number, date, time, and
78 the pathname of the file.
79 .It
80 A 5-line trailer consisting of blank lines.
81 .El
82 .Pp
83 If standard output is associated with a terminal,
84 diagnostic messages are suppressed until the
85 .Nm
86 utility has completed processing.
87 .Pp
88 When multiple column output is specified,
89 text columns are of equal width.
90 By default text columns are separated by at least one
91 .Aq Em blank .
92 Input lines that do not fit into a text column are truncated.
93 Lines are not truncated under single column output.
94 .Sh OPTIONS
95 In the following option descriptions, column, lines, offset, page, and
96 width are positive decimal integers and gap is a nonnegative decimal integer.
97 .Bl -tag -width 4n
98 .It Ar \&+page
99 Begin output at page number
100 .Ar page
101 of the formatted input.
102 .It Fl Ar column
103 Produce output that is
104 .Ar columns
105 wide (default is 1) that is written vertically
106 down each column in the order in which the text
107 is received from the input file.
108 The options
109 .Fl e
110 and
111 .Fl i
112 are assumed.
113 This option should not be used with
114 .Fl m .
115 When used with
116 .Fl t ,
117 the minimum number of lines is used to display the output.
118 .It Fl a
119 Modify the effect of the
120 .Fl column
121 option so that the columns are filled across the page in a round-robin order
122 (e.g., when column is 2, the first input line heads column
123 1, the second heads column 2, the third is the second line
124 in column 1, etc.).
125 This option requires the use of the
126 .Fl column
127 option.
128 .It Fl d
129 Produce output that is double spaced.
130 An extra
131 .Aq Em newline
132 character is output following every
133 .Aq newline
134 found in the input.
135 .It Fl e Ns Oo Ar char Oc Ns Op Ar gap
136 Expand each input
137 .Aq tab
138 to the next greater column
139 position specified by the formula
140 .Ar n*gap+1 ,
141 where
142 .Em n
143 is an integer \*[Gt] 0.
144 If
145 .Ar gap
146 is zero or is omitted the default is 8.
147 All
148 .Aq Em tab
149 characters in the input are expanded into the appropriate
150 number of
151 .Ao Em space Ac Ns s .
152 If any nondigit character,
153 .Ar char ,
154 is specified, it is used as the input tab character.
155 If the first character of
156 .Ar char
157 is a digit then
158 .Ar char
159 is treated as
160 .Ar gap .
161 .It Fl F
162 Use a
163 .Aq Em form-feed
164 character for new pages,
165 instead of the default behavior that uses a
166 sequence of
167 .Aq Em newline
168 characters.
169 .It Fl f
170 Same as
171 .Fl F .
172 Additionally pause before beginning the first page
173 if the standard output is associated with a terminal.
174 .It Fl h Ar header
175 Use the string
176 .Ar header
177 to replace the
178 .Ar file name
179 in the header line.
180 .It Fl i Ns Oo Ar char Oc Ns Op Ar gap
181 In output, replace multiple
182 .Ao space Ac Ns s
183 with
184 .Ao tab Ac Ns s
185 whenever two or more
186 adjacent
187 .Ao space Ac Ns s
188 reach column positions
189 .Ar gap+1 ,
190 .Ar 2*gap+1 ,
191 etc.
192 If
193 .Ar gap
194 is zero or omitted, default
195 .Aq Em tab
196 settings at every eighth column position
197 is used.
198 If any nondigit character,
199 .Ar char ,
200 is specified, it is used as the output
201 .Aq Em tab
202 character.
203 If the first character of
204 .Ar char
205 is a digit then
206 .Ar char
207 is treated as
208 .Ar gap .
209 .It Fl l Ar lines
210 Override the 66 line default and reset the page length to
211 .Ar lines .
212 If
213 .Ar lines
214 is not greater than the sum of both the header and trailer
215 depths (in lines), the
216 .Nm
217 utility suppresses output of both the header and trailer, as if the
218 .Fl t
219 option were in effect.
220 .It Fl m
221 Merge the contents of multiple files.
222 One line from each file specified by a file operand is
223 written side by side into text columns of equal fixed widths, in
224 terms of the number of column positions.
225 The number of text columns depends on the number of
226 file operands successfully opened.
227 The maximum number of files merged depends on page width and the
228 per process open file limit.
229 The options
230 .Fl e
231 and
232 .Fl i
233 are assumed.
234 .It Fl n Ns Oo Ar char Oc Ns Op Ar width
235 Provide
236 .Ar width
237 digit line numbering.
238 The default for
239 .Ar width ,
240 if not specified, is 5.
241 The number occupies the first
242 .Ar width
243 column positions of each text column or each line of
244 .Fl m
245 output.
246 If
247 .Ar char
248 (any nondigit character) is given, it is appended to the line number to
249 separate it from whatever follows.
250 The default for
251 .Ar char
252 is a
253 .Aq Em tab .
254 Line numbers longer than
255 .Ar width
256 columns are truncated.
257 .It Fl o Ar offset
258 Each line of output is preceded by
259 .Ar offset
260 .Ao Em space Ac Ns s .
261 If the
262 .Fl o
263 option is not specified, the default is zero.
264 The space taken is in addition to the output line width.
265 .It Fl p
266 Pause before beginning each page if the
267 standard output is associated with a terminal.
268 .Nm
269 will write an
270 .Aq Em alert
271 to standard error and wait for a
272 .Aq Em carriage-return
273 to be read on
274 .Pa /dev/tty .
275 .It Fl r
276 Write no diagnostic reports on failure to open a file.
277 .It Fl s Ns Op Ar char
278 Separate text columns by the single character
279 .Ar char
280 instead of by the appropriate number of
281 .Ao Em space Ac Ns s
282 (default for
283 .Ar char
284 is the
285 .Aq Em tab
286 character).
287 .It Fl T
288 Specify an
289 .Xr strftime 3
290 format string to be used to format the date and time information in the page
291 header.
292 .It Fl t
293 Print neither the five-line identifying
294 header nor the five-line trailer usually supplied for each page.
295 Quit printing after the last line of each file without spacing to the
296 end of the page.
297 .It Fl w Ar width
298 Set the width of the line to
299 .Ar width
300 column positions for multiple text-column output only.
301 If the
302 .Fl w
303 option is not specified and the
304 .Fl s
305 option is not specified, the default width is 72.
306 If the
307 .Fl w
308 option is not specified and the
309 .Fl s
310 option is specified, the default width is 512.
311 .It Ar file
312 A pathname of a file to be printed.
313 If no
314 .Ar file
315 operands are specified, or if a
316 .Ar file
317 operand is
318 .Sq Fl ,
319 the standard input is used.
320 The standard input is used only if no
321 .Ar file
322 operands are specified, or if a
323 .Ar file
324 operand is
325 .Sq Fl .
326 .El
327 .Pp
328 The
329 .Fl s
330 option does not allow the option letter to be separated from its
331 argument, and the options
332 .Fl e ,
333 .Fl i ,
334 and
335 .Fl n
336 require that both arguments, if present, not be separated from the option
337 letter.
338 .Sh ERRORS
339 If
340 .Nm
341 receives an interrupt while printing to a terminal, it
342 flushes all accumulated error messages to the screen before
343 terminating.
344 .Pp
345 The
346 .Nm
347 utility exits 0 on success, and 1 if an error occurs.
348 .Pp
349 Error messages are written to standard error during the printing
350 process (if output is redirected) or after all successful
351 file printing is complete (when printing to a terminal).
352 .Sh SEE ALSO
353 .Xr cat 1 ,
354 .Xr more 1 ,
355 .Xr strftime 3
356 .Sh STANDARDS
357 The
358 .Nm
359 utility is
360 .St -p1003.1-2008
361 compatible.