/usr.bin/pr/pr.1

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