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