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