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