1.\" $OpenBSD: pr.1,v 1.20 2009/08/16 09:41:08 sobrado 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.\" 36.Dd $Mdocdate: August 16 2009 $ 37.Dt PR 1 38.Os 39.Sh NAME 40.Nm pr 41.Nd print files 42.Sh SYNOPSIS 43.Nm pr 44.Bk -words 45.Op Ar +page 46.Op Fl Ar column 47.Op Fl adFfmrt 48.Xo Oo 49.Fl e 50.Op Ar char 51.Op Ar gap 52.Oc 53.Xc 54.Op Fl h Ar header 55.Xo Oo 56.Fl i 57.Op Ar char 58.Op Ar gap 59.Oc 60.Xc 61.Op Fl l Ar lines 62.Xo Oo 63.Fl n 64.Op Ar char 65.Op Ar width 66.Oc 67.Xc 68.Op Fl o Ar offset 69.Xo Oo 70.Fl s 71.Op Ar char 72.Oc 73.Xc 74.Op Fl w Ar width 75.Op - 76.Op Ar 77.Ek 78.Sh DESCRIPTION 79The 80.Nm pr 81utility is a printing and pagination filter for text files. 82When multiple input files are specified, each is read, formatted, 83and written to standard output. 84By default, the input is separated into 66-line pages, each with 85.Bl -bullet -offset indent 86.It 87A 5-line header with the page number, date, time, and 88the pathname of the file. 89.It 90A 5-line trailer consisting of blank lines. 91.El 92.Pp 93Optionally, the trailer can be replaced by a 94.Em <form-feed> 95where this is more appropriate for the output device being used and 96.Em <tab> Ns s 97can be expanded to input relative 98.Em <spaces> Ns s 99or 100.Em <space> Ns s 101can be contracted to output relative 102.Em <tab> Ns s . 103The 104.Nm pr 105utility also interprets 106.Em <form-feed> Ns s 107in the input as the logical end of pages. 108.Pp 109When multiple column output is specified, 110text columns are of equal width. 111By default text columns are separated by at least one 112.Em <blank> . 113Input lines that do not fit into a text column are truncated, except 114in the default single columns output mode. 115.Pp 116If standard output is associated with a terminal, 117diagnostic messages are suppressed until the 118.Nm pr 119utility has completed processing. 120.Pp 121In the following option descriptions, 122.Em column , 123.Em lines , 124.Em offset , 125.Em page , 126and 127.Em width 128are positive decimal integers and 129.Em gap 130is a non-negative decimal integer. 131.Pp 132The options are as follows: 133.Bl -tag -width Ds 134.It Ar \&+page 135Begin output at page number 136.Ar page 137of the formatted input. 138.It Fl Ar column 139Produce output that is 140.Ar column Ns s 141wide (default is 1) that is written vertically 142down each column in the order in which the text 143is received from the input file. 144The options 145.Fl e 146and 147.Fl i 148are assumed. 149This option should not be used with 150.Fl m . 151When used with 152.Fl t , 153the minimum number of lines is used to display the output. 154.It Fl a 155Modify the effect of the 156.Fl Ar column 157option so that the columns are filled across the page in a round-robin order 158(e.g., when column is 2, the first input line heads column 1591, the second heads column 2, the third is the second line 160in column 1, etc.). 161This option requires the use of the 162.Fl Ar column 163option. 164.It Fl d 165Produce output that is double spaced. 166An extra 167.Em <newline> 168character is output following every 169.Em <newline> 170found in the input. 171.It Xo Fl e 172.Op Ar char 173.Op Ar gap 174.Xc 175Expand each input 176.Em <tab> 177to the next greater column 178position specified by the formula 179.Ar n*gap+1 , 180where 181.Em n 182is an integer > 0. 183If 184.Ar gap 185is zero or is omitted the default is 8. 186All 187.Em <tab> 188characters in the input are expanded into the appropriate 189number of 190.Em <space> Ns s. 191If any nondigit character, 192.Ar char , 193is specified, it is used as the input tab character. 194.It Fl F 195Use a 196.Em <form-feed> 197character for new pages, 198instead of the default behavior that uses a 199sequence of 200.Em <newline> 201characters. 202.It Fl f 203Same as the 204.Fl F 205option. 206.It Fl h Ar header 207Use the string 208.Ar header 209to replace the 210.Ar file name 211in the header line. 212.It Xo Fl i 213.Op Ar char 214.Op Ar gap 215.Xc 216In output, replace multiple 217.Em <space> Ns s 218with 219.Em <tab> Ns s 220whenever two or more 221adjacent 222.Em <space> Ns s 223reach column positions 224.Ar gap+1 , 225.Ar 2*gap+1 , 226etc. 227If 228.Ar gap 229is zero or omitted, default 230.Em <tab> 231settings at every eighth column position 232is used. 233If any nondigit character, 234.Ar char , 235is specified, it is used as the output 236.Em <tab> 237character. 238.It Fl l Ar lines 239Override the 66 line default and reset the page length to 240.Ar lines . 241If 242.Ar lines 243is not greater than the sum of both the header and trailer 244depths (in lines), the 245.Nm pr 246utility suppresses output of both the header and trailer, as if the 247.Fl t 248option were in effect. 249.It Fl m 250Merge the contents of multiple files. 251One line from each file specified by a file operand is 252written side by side into text columns of equal fixed widths, in 253terms of the number of column positions. 254The number of text columns depends on the number of 255file operands successfully opened. 256The maximum number of files merged depends on page width and the 257per process open file limit. 258The options 259.Fl e 260and 261.Fl i 262are assumed. 263.It Xo Fl n 264.Op Ar char 265.Op Ar width 266.Xc 267Provide 268.Ar width 269digit line numbering. 270The default for 271.Ar width , 272if not specified, is 5. 273The number occupies the first 274.Ar width 275column positions of each text column or each line of 276.Fl m 277output. 278If 279.Ar char 280(any nondigit character) is given, it is appended to the line number to 281separate it from whatever follows. 282The default for 283.Ar char 284is a 285.Em <tab> . 286Line numbers longer than 287.Ar width 288columns are truncated. 289.It Fl o Ar offset 290Each line of output is preceded by 291.Ar offset 292.Em <spaces> Ns s. 293If the 294.Fl o 295option is not specified, the default is zero. 296The space taken is in addition to the output line width. 297.It Fl r 298Write no diagnostic reports on failure to open a file. 299.It Fl s Op Ar char 300Separate text columns by the single character 301.Ar char 302instead of by the appropriate number of 303.Em <space> Ns s 304(default for 305.Ar char 306is the 307.Em <tab> 308character). 309.It Fl t 310Print neither the five-line identifying 311header nor the five-line trailer usually supplied for each page. 312Quit printing after the last line of each file without spacing to the 313end of the page. 314.It Fl w Ar width 315Set the width of the line to 316.Ar width 317column positions for multiple text-column output only. 318If the 319.Fl w 320option is not specified and the 321.Fl s 322option is not specified, the default width is 72. 323If the 324.Fl w 325option is not specified and the 326.Fl s 327option is specified, the default width is 512. 328.It Ar file 329A pathname of a file to be printed. 330If no 331.Ar file 332operands are specified, or if a 333.Ar file 334operand is 335.Dq - , 336the standard input is used. 337The standard input is used only if no 338.Ar file 339operands are specified, or if a 340.Ar file 341operand is 342.Dq - . 343.El 344.Pp 345The 346.Fl s 347option does not allow the option letter to be separated from its 348argument, and the options 349.Fl e , 350.Fl i , 351and 352.Fl n 353require that both arguments, if present, not be separated from the option 354letter. 355.Sh ERRORS 356If 357.Nm pr 358receives an interrupt while printing to a terminal, it 359flushes all accumulated error messages to the screen before 360terminating. 361.Pp 362The 363.Nm pr 364utility exits 0 on success, and 1 if an error occurs. 365.Pp 366Error messages are written to standard error during the printing 367process (if output is redirected) or after all successful 368file printing is complete (when printing to a terminal). 369.Sh NOTES 370The interpretation of 371.Em <form-feed> Ns s 372in the input stream is that they are special 373.Em <newline> Ns s 374which have the side effect of causing a page break. 375While this works 376correctly for all cases, strict interpretation also implies that the 377common convention of placing a 378.Em <form-feed> 379on a line by itself is actually interpreted as a blank line, page break, 380blank line. 381.Sh RESTRICTIONS 382The 383.Nm pr 384utility is intended to paginate input containing basic 385.Xr ascii 7 386text formatting and input streams containing non-printing 387.Em <control-characters> , 388.Em <escape-sequences> 389or long lines may result in formatting errors. 390.Pp 391The 392.Nm pr 393utility does not currently understand over-printing using 394.Em <back-space> 395or 396.Em <return> 397characters, and except in the case of unmodified single-column output, 398use of these characters will cause formatting errors. 399.Sh SEE ALSO 400.Xr cat 1 , 401.Xr more 1 , 402.Xr ascii 7 403.Sh STANDARDS 404The 405.Nm 406utility is compliant with the 407.St -p1003.1-2008 408specification. 409.Pp 410.St -p1003.1-2008 411is relatively silent concerning the 412handling of input characters beyond the behavior dictated by the 413.Nm pr 414required command 415options. 416.Sh HISTORY 417A 418.Nm 419command appeared in 420.At v1 . 421.Sh BUGS 422The lack of a line wrapping option, and the specification that truncation 423does not apply to single-column output frequently results in formatting 424errors when input lines are longer than actual line width of the output device. 425.Pp 426The default width of 72 is archaic and non-obvious since it is normally 427ignored in the default single column mode. 428Using the 429.Fl m 430option with one column provides a way to truncate single column output but 431there's no way to wrap long lines to a fixed line width. 432.Pp 433The default of 434.Em <tab> 435for the separator for the 436.Fl n 437and 438.Fl s 439options often results in lines apparently wider than expected. 440