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