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