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