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