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