xref: /dragonfly/usr.bin/pr/pr.1 (revision 1de703da)
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.2 2003/06/17 04:29:30 dillon 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
100The
101.Nm
102utility is a printing and pagination filter for text files.
103When multiple input files are specified, each is read, formatted,
104and written to standard output.
105By default, the input is separated into 66-line pages, each with
106.Bl -bullet
107.It
108A 5-line header with the page number, date, time, and
109the pathname of the file.
110.It
111A 5-line trailer consisting of blank lines.
112.El
113.Pp
114If standard output is associated with a terminal,
115diagnostic messages are suppressed until the
116.Nm
117utility has completed processing.
118.Pp
119When multiple column output is specified,
120text columns are of equal width.
121By default text columns are separated by at least one
122.Em <blank> .
123Input lines that do not fit into a text column are truncated.
124Lines are not truncated under single column output.
125.Sh OPTIONS
126In the following option descriptions, column, lines, offset, page, and
127width are positive decimal integers and gap is a nonnegative decimal integer.
128.Bl -tag -width 4n
129.It Ar \&+page
130Begin output at page number
131.Ar page
132of the formatted input.
133.It Fl Ar column
134Produce output that is
135.Ar columns
136wide (default is 1) that is written vertically
137down each column in the order in which the text
138is received from the input file.
139The options
140.Fl e
141and
142.Fl i
143are assumed.
144This option should not be used with
145.Fl m .
146When used with
147.Fl t ,
148the minimum number of lines is used to display the output.
149(To columnify and reshape text files more generally and without additional
150formatting, see the
151.Xr rs 1
152utility.)
153.It Fl a
154Modify the effect of the
155.Fl column
156option 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
1581, the second heads column 2, the third is the second line
159in column 1, etc.).
160This option requires the use of the
161.Fl column
162option.
163.It Fl d
164Produce output that is double spaced.
165An extra
166.Em <newline>
167character is output following every
168.Em <newline>
169found in the input.
170.It Fl e Xo
171.Op Ar char Ns
172.Op Ar gap
173.Xc
174Expand each input
175.Em <tab>
176to the next greater column
177position specified by the formula
178.Ar n*gap+1 ,
179where
180.Em n
181is an integer > 0.
182If
183.Ar gap
184is zero or is omitted the default is 8.
185All
186.Em <tab>
187characters in the input are expanded into the appropriate
188number of
189.Em <space>s .
190If any nondigit character,
191.Ar char ,
192is specified, it is used as the input tab character.
193.It Fl F
194Use a
195.Em <form-feed>
196character for new pages,
197instead of the default behavior that uses a
198sequence of
199.Em <newline>
200characters.
201.It Fl f
202Same as
203.Fl F
204but pause before beginning the first page if standard output is a terminal.
205.It Fl h Ar header
206Use the string
207.Ar header
208to replace the
209.Ar file name
210in the header line.
211.It Fl i Xo
212.Op Ar char Ns
213.Op Ar gap
214.Xc
215In output, replace multiple
216.Em <space>s
217with
218.Em <tab>s
219whenever two or more
220adjacent
221.Em <space>s
222reach column positions
223.Ar gap+1 ,
224.Ar 2*gap+1 ,
225etc.
226If
227.Ar gap
228is zero or omitted, default
229.Em <tab>
230settings at every eighth column position
231is used.
232If any nondigit character,
233.Ar char ,
234is specified, it is used as the output
235.Em <tab>
236character.
237.It Fl L Ar locale
238Use
239.Ar locale
240specified as argument instead of one found in environment.
241Use "C" to reset locale to default.
242.It Fl l Ar lines
243Override the 66 line default and reset the page length to
244.Ar lines .
245If
246.Ar lines
247is not greater than the sum of both the header and trailer
248depths (in lines), the
249.Nm
250utility suppresses output of both the header and trailer, as if the
251.Fl t
252option were in effect.
253.It Fl m
254Merge the contents of multiple files.
255One line from each file specified by a file operand is
256written side by side into text columns of equal fixed widths, in
257terms of the number of column positions.
258The number of text columns depends on the number of
259file operands successfully opened.
260The maximum number of files merged depends on page width and the
261per process open file limit.
262The options
263.Fl e
264and
265.Fl i
266are assumed.
267.It Fl n Xo
268.Op Ar char Ns
269.Op Ar width
270.Xc
271Provide
272.Ar width
273digit line numbering.
274The default for
275.Ar width ,
276if not specified, is 5.
277The number occupies the first
278.Ar width
279column positions of each text column or each line of
280.Fl m
281output.
282If
283.Ar char
284(any nondigit character) is given, it is appended to the line number to
285separate it from whatever follows.
286The default for
287.Ar char
288is a
289.Em <tab> .
290Line numbers longer than
291.Ar width
292columns are truncated.
293.It Fl o Ar offset
294Each line of output is preceded by
295.Ar offset
296.Em <spaces>s .
297If the
298.Fl o
299option is not specified, the default is zero.
300The space taken is in addition to the output line width.
301.It Fl p
302Pause before each page if the standard output is a terminal.
303.Nm
304will write an alert character to standard error and wait for a carriage
305return to be read on the terminal.
306.It Fl r
307Write no diagnostic reports on failure to open a file.
308.It Fl s Ar char
309Separate text columns by the single character
310.Ar char
311instead of by the appropriate number of
312.Em <space>s
313(default for
314.Ar char
315is the
316.Em <tab>
317character).
318.It Fl t
319Print neither the five-line identifying
320header nor the five-line trailer usually supplied for each page.
321Quit printing after the last line of each file without spacing to the
322end of the page.
323.It Fl w Ar width
324Set the width of the line to
325.Ar width
326column positions for multiple text-column output only.
327If the
328.Fl w
329option is not specified and the
330.Fl s
331option is not specified, the default width is 72.
332If the
333.Fl w
334option is not specified and the
335.Fl s
336option is specified, the default width is 512.
337.It Ar file
338A pathname of a file to be printed.
339If no
340.Ar file
341operands are specified, or if a
342.Ar file
343operand is
344.Sq Fl ,
345the standard input is used.
346The standard input is used only if no
347.Ar file
348operands are specified, or if a
349.Ar file
350operand is
351.Sq Fl .
352.El
353.Pp
354The
355.Fl s
356option does not allow the option letter to be separated from its
357argument, and the options
358.Fl e ,
359.Fl i ,
360and
361.Fl n
362require that both arguments, if present, not be separated from the option
363letter.
364.Sh ERRORS
365If
366.Nm
367receives an interrupt while printing to a terminal, it
368flushes all accumulated error messages to the screen before
369terminating.
370.Sh DIAGNOSTICS
371The
372.Nm
373utility exits 0 on success, and 1 if an error occurs.
374.Pp
375Error messages are written to standard error during the printing
376process (if output is redirected) or after all successful
377file printing is complete (when printing to a terminal).
378.Sh SEE ALSO
379.Xr cat 1 ,
380.Xr more 1 ,
381.Xr rs 1
382.Sh STANDARDS
383The
384.Nm
385utility is
386.St -p1003.1-2001
387compatible.
388.Sh HISTORY
389A
390.Nm
391command appeared in
392.At v1 .
393