| blob | 16388668498e308f4dda8a86d06ac8b990f7e887 |
1 .\" Copyright (c) 1991 Keith Muller.
2 .\" Copyright (c) 1993
3 .\" The Regents of the University of California. All rights reserved.
4 .\"
5 .\" This code is derived from software contributed to Berkeley by
6 .\" Keith Muller of the University of California, San Diego.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. All advertising materials mentioning features or use of this software
17 .\" must display the following acknowledgement:
18 .\" This product includes software developed by the University of
19 .\" California, Berkeley and its contributors.
20 .\" 4. 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 .\" @(#)pr.1 8.3 (Berkeley) 4/18/94
37 .\" $FreeBSD: src/usr.bin/pr/pr.1,v 1.9.2.9 2002/07/15 07:29:05 keramida Exp $
38 .\" $DragonFly: src/usr.bin/pr/pr.1,v 1.4 2006/03/01 08:01:09 swildner Exp $
39 .\"
40 .Dd September 20, 2001
41 .Dt PR 1
42 .Os
43 .Sh NAME
44 .Nm pr
45 .Nd print files
46 .Sh SYNOPSIS
47 .Nm
48 .Bk -words
49 .Op Ar \&+page
50 .Ek
51 .Bk -words
52 .Op Fl Ar column
53 .Ek
54 .Op Fl adFfmprt
55 .Bk -words
56 .Oo
57 .Op Fl e
58 .Op Ar char
59 .Op Ar gap
60 .Oc
61 .Ek
62 .Bk -words
63 .Op Fl L Ar locale
64 .Ek
65 .Bk -words
66 .Op Fl h Ar header
67 .Ek
68 .Bk -words
69 .Oo
70 .Op Fl i
71 .Op Ar char
72 .Op Ar gap
73 .Oc
74 .Ek
75 .Bk -words
76 .Op Fl l Ar lines
77 .Ek
78 .Bk -words
79 .Op Fl o Ar offset
80 .Ek
81 .Bk -words
82 .Oo
83 .Op Fl s
84 .Op Ar char
85 .Oc
86 .Ek
87 .Bk -words
88 .Oo
89 .Op Fl n
90 .Op Ar char
91 .Op Ar width
92 .Oc
93 .Ek
94 .Bk -words
95 .Op Fl w Ar width
96 .Ek
97 .Op -
98 .Op Ar
99 .Sh DESCRIPTION
100 The
101 .Nm
102 utility is a printing and pagination filter for text files.
103 When multiple input files are specified, each is read, formatted,
104 and written to standard output.
105 By default, the input is separated into 66-line pages, each with
106 .Bl -bullet
107 .It
108 A 5-line header with the page number, date, time, and
109 the pathname of the file.
110 .It
111 A 5-line trailer consisting of blank lines.
112 .El
113 .Pp
114 If standard output is associated with a terminal,
115 diagnostic messages are suppressed until the
116 .Nm
117 utility has completed processing.
118 .Pp
119 When multiple column output is specified,
120 text columns are of equal width.
121 By default text columns are separated by at least one
122 .Em <blank> .
123 Input lines that do not fit into a text column are truncated.
124 Lines are not truncated under single column output.
125 .Sh OPTIONS
126 In the following option descriptions, column, lines, offset, page, and
127 width are positive decimal integers and gap is a nonnegative decimal integer.
128 .Bl -tag -width 4n
129 .It Ar \&+page
130 Begin output at page number
131 .Ar page
132 of the formatted input.
133 .It Fl Ar column
134 Produce output that is
135 .Ar columns
136 wide (default is 1) that is written vertically
137 down each column in the order in which the text
138 is received from the input file.
139 The options
140 .Fl e
141 and
142 .Fl i
143 are assumed.
144 This option should not be used with
145 .Fl m .
146 When used with
147 .Fl t ,
148 the minimum number of lines is used to display the output.
149 (To columnify and reshape text files more generally and without additional
150 formatting, see the
151 .Xr rs 1
152 utility.)
153 .It Fl a
154 Modify the effect of the
155 .Fl column
156 option so that the columns are filled across the page in a round-robin order
157 (e.g., when column is 2, the first input line heads column
158 1, the second heads column 2, the third is the second line
159 in column 1, etc.).
160 This option requires the use of the
161 .Fl column
162 option.
163 .It Fl d
164 Produce output that is double spaced.
165 An extra
166 .Em <newline>
167 character is output following every
168 .Em <newline>
169 found in the input.
170 .It Fl e Xo
171 .Op Ar char Ns
172 .Op Ar gap
173 .Xc
174 Expand each input
175 .Em <tab>
176 to the next greater column
177 position specified by the formula
178 .Ar n*gap+1 ,
179 where
180 .Em n
181 is an integer > 0.
182 If
183 .Ar gap
184 is zero or is omitted the default is 8.
185 All
186 .Em <tab>
187 characters in the input are expanded into the appropriate
188 number of
189 .Em <space>s .
190 If any nondigit character,
191 .Ar char ,
192 is specified, it is used as the input tab character.
193 .It Fl F
194 Use a
195 .Em <form-feed>
196 character for new pages,
197 instead of the default behavior that uses a
198 sequence of
199 .Em <newline>
200 characters.
201 .It Fl f
202 Same as
203 .Fl F
204 but pause before beginning the first page if standard output is a terminal.
205 .It Fl h Ar header
206 Use the string
207 .Ar header
208 to replace the
209 .Ar file name
210 in the header line.
211 .It Fl i Xo
212 .Op Ar char Ns
213 .Op Ar gap
214 .Xc
215 In output, replace multiple
216 .Em <space>s
217 with
218 .Em <tab>s
219 whenever two or more
220 adjacent
221 .Em <space>s
222 reach column positions
223 .Ar gap+1 ,
224 .Ar 2*gap+1 ,
225 etc.
226 If
227 .Ar gap
228 is zero or omitted, default
229 .Em <tab>
230 settings at every eighth column position
231 is used.
232 If any nondigit character,
233 .Ar char ,
234 is specified, it is used as the output
235 .Em <tab>
236 character.
237 .It Fl L Ar locale
238 Use
239 .Ar locale
240 specified as argument instead of one found in environment.
241 Use "C" to reset locale to default.
242 .It Fl l Ar lines
243 Override the 66 line default and reset the page length to
244 .Ar lines .
245 If
246 .Ar lines
247 is not greater than the sum of both the header and trailer
248 depths (in lines), the
249 .Nm
250 utility suppresses output of both the header and trailer, as if the
251 .Fl t
252 option were in effect.
253 .It Fl m
254 Merge the contents of multiple files.
255 One line from each file specified by a file operand is
256 written side by side into text columns of equal fixed widths, in
257 terms of the number of column positions.
258 The number of text columns depends on the number of
259 file operands successfully opened.
260 The maximum number of files merged depends on page width and the
261 per process open file limit.
262 The options
263 .Fl e
264 and
265 .Fl i
266 are assumed.
267 .It Fl n Xo
268 .Op Ar char Ns
269 .Op Ar width
270 .Xc
271 Provide
272 .Ar width
273 digit line numbering.
274 The default for
275 .Ar width ,
276 if not specified, is 5.
277 The number occupies the first
278 .Ar width
279 column positions of each text column or each line of
280 .Fl m
281 output.
282 If
283 .Ar char
284 (any nondigit character) is given, it is appended to the line number to
285 separate it from whatever follows.
286 The default for
287 .Ar char
288 is a
289 .Em <tab> .
290 Line numbers longer than
291 .Ar width
292 columns are truncated.
293 .It Fl o Ar offset
294 Each line of output is preceded by
295 .Ar offset
296 .Em <spaces>s .
297 If the
298 .Fl o
299 option is not specified, the default is zero.
300 The space taken is in addition to the output line width.
301 .It Fl p
302 Pause before each page if the standard output is a terminal.
303 .Nm
304 will write an alert character to standard error and wait for a carriage
305 return to be read on the terminal.
306 .It Fl r
307 Write no diagnostic reports on failure to open a file.
308 .It Fl s Ar char
309 Separate text columns by the single character
310 .Ar char
311 instead of by the appropriate number of
312 .Em <space>s
313 (default for
314 .Ar char
315 is the
316 .Em <tab>
317 character).
318 .It Fl t
319 Print neither the five-line identifying
320 header nor the five-line trailer usually supplied for each page.
321 Quit printing after the last line of each file without spacing to the
322 end of the page.
323 .It Fl w Ar width
324 Set the width of the line to
325 .Ar width
326 column positions for multiple text-column output only.
327 If the
328 .Fl w
329 option is not specified and the
330 .Fl s
331 option is not specified, the default width is 72.
332 If the
333 .Fl w
334 option is not specified and the
335 .Fl s
336 option is specified, the default width is 512.
337 .It Ar file
338 A pathname of a file to be printed.
339 If no
340 .Ar file
341 operands are specified, or if a
342 .Ar file
343 operand is
344 .Sq Fl ,
345 the standard input is used.
346 The standard input is used only if no
347 .Ar file
348 operands are specified, or if a
349 .Ar file
350 operand is
351 .Sq Fl .
352 .El
353 .Pp
354 The
355 .Fl s
356 option does not allow the option letter to be separated from its
357 argument, and the options
358 .Fl e ,
359 .Fl i ,
360 and
361 .Fl n
362 require that both arguments, if present, not be separated from the option
363 letter.
364 .Sh DIAGNOSTICS
365 The
366 .Nm
367 utility exits 0 on success, and 1 if an error occurs.
368 .Pp
369 Error messages are written to standard error during the printing
370 process (if output is redirected) or after all successful
371 file printing is complete (when printing to a terminal).
372 .Pp
373 If
374 .Nm
375 receives an interrupt while printing to a terminal, it
376 flushes all accumulated error messages to the screen before
377 terminating.
378 .Sh SEE ALSO
379 .Xr cat 1 ,
380 .Xr more 1 ,
381 .Xr rs 1
382 .Sh STANDARDS
383 The
384 .Nm
385 utility is
386 .St -p1003.1-2001
387 compatible.
388 .Sh HISTORY
389 A
390 .Nm
391 command appeared in
392 .At v1 .