add UNLEASHED_OBJ to unleashed.mk
[unleashed/tickless.git] / share / man / man1 / pr.1
blob419f40324c30450d15b35338e3941a47400890d3
1 '\" te
2 .\" Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
3 .\" Copyright 1989 AT&T
4 .\" Portions Copyright (c) 1995, Sun Microsystems, Inc.  All Rights Reserved
5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
6 .\" http://www.opengroup.org/bookstore/.
7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
8 .\"  This notice shall appear on any product containing this material.
9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
12 .TH PR 1 "Oct 25, 2017"
13 .SH NAME
14 pr \- print files
15 .SH SYNOPSIS
16 .LP
17 .nf
18 \fB/usr/bin/pr\fR [+ \fIpage\fR] [\fB-column\fR | \fB-c\fR \fIcolumn\fR] [\fB-adFmrt\fR]
19      [\fB-e\fR [\fIchar\fR] [\fIgap\fR]] [\fB-h\fR \fIheader\fR] [\fB-i\fR [\fIchar\fR] [\fIgap\fR]]
20      [\fB-l\fR \fIlines\fR] [\fB-n\fR [\fIchar\fR] [\fIwidth\fR]] [\fB-o\fR \fIoffset\fR]
21      [\fB-s\fR [\fIchar\fR]] [\fB-w\fR \fIwidth\fR] [\fB-fp\fR] [\fIfile\fR]...
22 .fi
24 .SH DESCRIPTION
25 .sp
26 .LP
27 The \fBpr\fR utility is a printing and pagination filter. If multiple input
28 files are specified, each is read, formatted, and written to standard output.
29 By default, the input is separated into 66-line pages, each with:
30 .RS +4
31 .TP
32 .ie t \(bu
33 .el o
34 a 5-line header that includes the page number, date, time and the path name of
35 the file
36 .RE
37 .RS +4
38 .TP
39 .ie t \(bu
40 .el o
41 a 5-line trailer consisting of blank lines
42 .RE
43 .sp
44 .LP
45 If standard output is associated with a terminal, diagnostic messages will be
46 deferred until the \fBpr\fR utility has completed processing.
47 .sp
48 .LP
49 When options specifying multi-column output are specified, output text columns
50 will be of equal width; input lines that do not fit into a text column will be
51 truncated. By default, text columns are separated with at least one blank
52 character.
53 .SH OPTIONS
54 .sp
55 .LP
56 The following options are supported. In the following option descriptions,
57 \fIcolumn\fR, \fIlines\fR, \fIoffset\fR, \fIpage\fR, and \fIwidth\fR are
58 positive decimal integers; \fIgap\fR is a non-negative decimal integer. Some of
59 the option-arguments are optional, and some of the option-arguments cannot be
60 specified as separate arguments from the preceding option letter. In
61 particular, the \fB-s\fR option does not allow the option letter to be
62 separated from its argument, and the options \fB-e\fR, \fB-i\fR, and \fB-n\fR
63 require that both arguments, if present, not be separated from the option
64 letter.
65 .sp
66 .LP
67 The following options are supported:
68 .sp
69 .ne 2
70 .na
71 \fB\fB+\fR\fIpage\fR\fR
72 .ad
73 .RS 29n
74 Begins output at page number \fIpage\fR of the formatted input.
75 .RE
77 .sp
78 .ne 2
79 .na
80 \fB\fB-\fR\fIcolumn\fR\fR
81 .ad
82 .RS 29n
83 Produces multi-column output that is arranged in \fIcolumn\fR columns (default
84 is \fB1\fR) and is written down each column in the order in which the text is
85 received from the input file. This option should not be used with \fB-m\fR. The
86 \fB-e\fR and \fB-i\fR options will be assumed for multiple text-column output.
87 Whether or not text columns are produced with identical vertical lengths is
88 unspecified, but a text column will never exceed the length of the page (see
89 the \fB-l\fR option). When used with \fB-t\fR, use the minimum number of lines
90 to write the output.
91 .RE
93 .sp
94 .ne 2
95 .na
96 \fB\fB-a\fR\fR
97 .ad
98 .RS 29n
99 Modifies the effect of the \fB-\fR\fIcolumn\fR option so that the columns are
100 filled across the page in a round-robin order (for example, when \fIcolumn\fR
101 is 2, the first input line heads column 1, the second heads column 2, the third
102 is the second line in column 1, and so forth).
106 .ne 2
108 \fB\fB-d\fR\fR
110 .RS 29n
111 Produces output that is double-spaced; append an extra \fBNEWLINE\fR character
112 following every \fBNEWLINE\fR character found in the input.
116 .ne 2
118 \fB\fB\fR\fB-e\fR\fB\|[\|\fR\fIchar\fR\fB\|][\|\fR\fIgap\fR\fB\|]\fR\fR
120 .RS 29n
121 Expands each input \fBTAB\fR character to the next greater column position
122 specified by the formula \fIn\fR \fI*gap+1\fR, where \fIn\fR is an integer
123 \fB>0\fR. If \fIgap\fR is \fB0\fR or is omitted, it defaults to \fB8\fR. All
124 \fBTAB\fR characters in the input will be expanded into the appropriate number
125 of \fBSPACE\fR characters.  If any non-digit character, \fIchar\fR, is
126 specified, it will be used as the input tab character.
130 .ne 2
132 \fB\fB-f\fR\fR
134 .RS 29n
135 Uses a \fBFORMFEED\fR character for new pages, instead of the default behavior
136 that uses a sequence of \fBNEWLINE\fR characters. Pauses before beginning the
137 first page if the standard output is associated with a terminal.
141 .ne 2
143 \fB\fB-h\fR \fIheader\fR\fR
145 .RS 29n
146 Uses the string \fIheader\fR to replace the contents of the \fIfile\fR operand
147 in the page header.
151 .ne 2
153 \fB\fB-l\fR \fIlines\fR\fR
155 .RS 29n
156 Overrides the 66-line default and reset the page length to \fIlines\fR. If
157 \fIlines\fR is not greater than the sum of both the header and trailer depths
158 (in lines), \fBpr\fR will suppress both the header and trailer, as if the
159 \fB-t\fR option were in effect.
163 .ne 2
165 \fB\fB-m\fR\fR
167 .RS 29n
168 Merges files. Standard output will be formatted so \fBpr\fR writes one line
169 from each file specified by \fIfile\fR, side by side into text columns of equal
170 fixed widths, in terms of the number of column positions. Implementations
171 support merging of at least nine \fIfile\fRs.
175 .ne 2
177 \fB\fB-n\|[\|\fR\fIchar\fR\fB\|][\|\fR\fIwidth\fR\fB\|]\fR\fR
179 .RS 29n
180 Provides \fIwidth\fR-digit line numbering (default for \fIwidth\fR is \fB5\fR).
181 The number will occupy the first \fIwidth\fR column positions of each text
182 column of default output or each line of \fB-m\fR output. If \fIchar\fR (any
183 non-digit character) is given, it will be appended to the line number to
184 separate it from whatever follows (default for \fIchar\fR is a \fBTAB\fR
185 character).
189 .ne 2
191 \fB\fB-o\fR \fIoffset\fR\fR
193 .RS 29n
194 Each line of output will be preceded by offset <space>s. If the \fB-o\fR option
195 is not specified, the default offset is \fB0\fR. The space taken will be in
196 addition to the output line width (see \fB-w\fR option below).
200 .ne 2
202 \fB\fB-p\fR\fR
204 .RS 29n
205 Pauses before beginning each page if the standard output is directed to a
206 terminal (\fBpr\fR will write an \fBALERT\fR character to standard error and
207 wait for a carriage-return character to be read on \fB/dev/tty\fR).
211 .ne 2
213 \fB\fB-r\fR\fR
215 .RS 29n
216 Writes no diagnostic reports on failure to open files.
220 .ne 2
222 \fB\fB-s\fR \fB[\fR\fIchar\fR\fB]\fR\fR
224 .RS 29n
225 Separates text columns by the single character \fIchar\fR instead of by the
226 appropriate number of \fBSPACE\fR characters (default for \fIchar\fR is the
227 \fBTAB\fR character).
231 .ne 2
233 \fB\fB-t\fR\fR
235 .RS 29n
236 Writes neither the five-line identifying header nor the five-line trailer
237 usually supplied for each page. Quits writing after the last line of each file
238 without spacing to the end of the page.
242 .ne 2
244 \fB\fB-w\fR \fIwidth\fR\fR
246 .RS 29n
247 Sets the width of the line to \fIwidth\fR column positions for multiple
248 text-column output only. If the \fB-w\fR option is not specified and the
249 \fB-s\fR option is not specified, the default width is \fB72\fR. If the
250 \fB-w\fR option is not specified and the \fB-s\fR option is specified, the
251 default width is \fB512\fR.
253 For single column output, input lines will not be truncated.
256 The following options are supported:
258 .ne 2
260 \fB\fB-F\fR\fR
262 .RS 27n
263 Uses a \fBFORMFEED\fR character for new pages, instead of the default behavior
264 that uses a sequence of \fBNEWLINE\fR characters.
268 .ne 2
270 \fB\fB\fR\fB-i\fR\fB\|[\|\fR\fIchar\fR\fB\|][\|\fR\fIgap\fR\fB\|]\fR\fR
272 .RS 27n
273 In output, replaces multiple \fBSPACE\fR characters with \fBTAB\fR characters
274 wherever two or more adjacent \fBSPACE\fR characters reach column positions
275 \fIgap+1\fR, \fI2*gap+1\fR, \fI3*gap+1\fR, and so forth. If \fIgap\fR is
276 \fB0\fR or is omitted, default \fBTAB\fR settings at every eighth column
277 position are assumed. If any non-digit character, \fIchar\fR, is specified, it
278 will be used as the output \fBTAB\fR character.
281 .SH OPERANDS
284 The following operand is supported:
286 .ne 2
288 \fB\fIfile\fR\fR
290 .RS 8n
291 A path name of a file to be written. If no \fIfile\fR operands are specified,
292 or if a \fIfile\fR operand is \fB\(mi\fR, the standard input will be used.
295 .SH EXAMPLES
297 \fBExample 1 \fRPrinting a numbered list of all files in the current directory
299 .in +2
301 example% \fBls -a | pr -n -h "Files in $(pwd)."\fR
303 .in -2
307 \fBExample 2 \fRPrinting files in columns
310 This example prints \fBfile1\fR and \fBfile2\fR as a double-spaced,
311 three-column listing headed by \fBfile list\fR:
314 .in +2
316 example% \fBpr -3d -h "file list" file1 file2\fR
318 .in -2
322 \fBExample 3 \fRWriting files with expanded column tabs
325 The following example writes \fBfile1\fR on \fBfile2\fR, expanding tabs to
326 columns \fB10\fR, \fB19\fR, \fB28\fR, ...
329 .in +2
331 example% \fBpr -e9 -t <file1 >file2\fR
333 .in -2
336 .SH ENVIRONMENT VARIABLES
339 See \fBenviron\fR(5) for descriptions of the following environment variables
340 that affect the execution of \fBpr\fR: \fBLANG\fR, \fBLC_ALL\fR,
341 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, \fBLC_TIME\fR, \fBTZ\fR, and \fBNLSPATH\fR.
342 .SH EXIT STATUS
345 The following exit values are returned:
347 .ne 2
349 \fB\fB0\fR\fR
351 .RS 6n
352 Successful completion.
356 .ne 2
358 \fB\fB>0\fR\fR
360 .RS 6n
361 An error occurred.
364 .SH ATTRIBUTES
367 See \fBattributes\fR(5) for descriptions of the following attributes:
368 .SS "/usr/bin/pr"
373 box;
374 c | c
375 l | l .
376 ATTRIBUTE TYPE  ATTRIBUTE VALUE
378 CSI     Enabled
380 Interface Stability     Committed
382 Standard        See \fBstandards\fR(5).
385 .SH SEE ALSO
388 \fBexpand\fR(1), \fBlp\fR(1), \fBattributes\fR(5), \fBenviron\fR(5),
389 \fBstandards\fR(5)