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$
  38 .\"
  39 .Dd April 18, 1994
  40 .Dt PR 1
  41 .Os BSD 4.4
  42 .Sh NAME
  43 .Nm pr
  44 .Nd print files
  45 .Sh SYNOPSIS
  46 .Nm
  47 .Bk -words
  48 .Op Ar \&+page
  49 .Ek
  50 .Bk -words
  51 .Op Fl Ar column
  52 .Ek
  53 .Op Fl adFmrt
  54 .Bk -words
  55 .Oo
  56 .Op Fl e
  57 .Op Ar char
  58 .Op Ar gap
  59 .Oc
  60 .Ek
  61 .Bk -words
  62 .Op Fl L Ar locale
  63 .Ek
  64 .Bk -words
  65 .Op Fl h Ar header
  66 .Ek
  67 .Bk -words
  68 .Oo
  69 .Op Fl i
  70 .Op Ar char
  71 .Op Ar gap
  72 .Oc
  73 .Ek
  74 .Bk -words
  75 .Op Fl l Ar lines
  76 .Ek
  77 .Bk -words
  78 .Op Fl o Ar offset
  79 .Ek
  80 .Bk -words
  81 .Oo
  82 .Op Fl s
  83 .Op Ar char
  84 .Oc
  85 .Ek
  86 .Bk -words
  87 .Oo
  88 .Op Fl n
  89 .Op Ar char
  90 .Op Ar width
  91 .Oc
  92 .Ek
  93 .Bk -words
  94 .Op Fl w Ar width
  95 .Ek
  96 .Op -
  97 .Op Ar file ...
  98 .Sh DESCRIPTION
  99 The
 100 .Nm
 101 utility is a printing and pagination filter for text files.
 102 When multiple input files are specified, each is read, formatted,
 103 and written to standard output.
 104 By default, the input is separated into 66-line pages, each with
 105 .Bl -bullet
 106 .It
 107 A 5-line header with the page number, date, time, and
 108 the pathname of the file.
 109 .It
 110 A 5-line trailer consisting of blank lines.
 111 .El
 112 .Pp
 113 If standard output is associated with a terminal,
 114 diagnostic messages are suppressed until the
 115 .Nm
 116 utility has completed processing.
 117 .Pp
 118 When multiple column output is specified,
 119 text columns are of equal width.
 120 By default text columns are separated by at least one
 121 .Em <blank> .
 122 Input lines that do not fit into a text column are truncated.
 123 Lines are not truncated under single column output.
 124 .Sh OPTIONS
 125 .Pp
 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 .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 Ar \&[char\&]\&[gap\&]
 167 Expand each input
 168 .Em <tab>
 169 to the next greater column
 170 position specified by the formula
 171 .Ar n*gap+1 ,
 172 where
 173 .Em n
 174 is an integer > 0.
 175 If
 176 .Ar gap
 177 is zero or is omitted the default is 8.
 178 All
 179 .Em <tab>
 180 characters in the input are expanded into the appropriate
 181 number of
 182 .Em <space>s .
 183 If any nondigit character,
 184 .Ar char ,
 185 is specified, it is used as the input tab character.
 186 .It Fl F
 187 Use a
 188 .Em <form-feed>
 189 character for new pages,
 190 instead of the default behavior that uses a
 191 sequence of
 192 .Em <newline>
 193 characters.
 194 .It Fl h Ar header
 195 Use the string
 196 .Ar header
 197 to replace the
 198 .Ar file name
 199 in the header line.
 200 .It Fl i Ar \&[char\&]\&[gap\&]
 201 In output, replace multiple
 202 .Em <space>s
 203 with
 204 .Em <tab>s
 205 whenever two or more
 206 adjacent
 207 .Em <space>s
 208 reach column positions
 209 .Ar gap+1 ,
 210 .Ar 2*gap+1 ,
 211 etc.
 212 If
 213 .Ar gap
 214 is zero or omitted, default
 215 .Em <tab>
 216 settings at every eighth column position
 217 is used.
 218 If any nondigit character,
 219 .Ar char ,
 220 is specified, it is used as the output
 221 .Em <tab>
 222 character.
 223 .It Fl L Ar locale
 224 Use
 225 .Ar locale
 226 specified as argument instead of one found in environment.
 227 Use "C" to reset locale to default.
 228 .It Fl l Ar lines
 229 Override the 66 line default and reset the page length to
 230 .Ar lines .
 231 If
 232 .Ar lines
 233 is not greater than the sum of both the header and trailer
 234 depths (in lines), the
 235 .Nm
 236 utility suppresses output of both the header and trailer, as if the
 237 .Fl t
 238 option were in effect.
 239 .It Fl m
 240 Merge the contents of multiple files.
 241 One line from each file specified by a file operand is
 242 written side by side into text columns of equal fixed widths, in
 243 terms of the number of column positions.
 244 The number of text columns depends on the number of
 245 file operands successfully opened.
 246 The maximum number of files merged depends on page width and the
 247 per process open file limit.
 248 The options
 249 .Fl e
 250 and
 251 .Fl i
 252 are assumed.
 253 .It Fl n Ar \&[char\&]\&[width\&]
 254 Provide
 255 .Ar width
 256 digit line numbering.
 257 The default for
 258 .Ar width ,
 259 if not specified, is 5.
 260 The number occupies the first
 261 .Ar width
 262 column positions of each text column or each line of
 263 .Fl m
 264 output.
 265 If
 266 .Ar char
 267 (any nondigit character) is given, it is appended to the line number to
 268 separate it from whatever follows.
 269 The default for
 270 .Ar char
 271 is a
 272 .Em <tab> .
 273 Line numbers longer than
 274 .Ar width
 275 columns are truncated.
 276 .It Fl o Ar offset
 277 Each line of output is preceded by
 278 .Ar offset
 279 .Em <spaces>s .
 280 If the
 281 .Fl o
 282 option is not specified, the default is zero.
 283 The space taken is in addition to the output line width.
 284 .It Fl r
 285 Write no diagnostic reports on failure to open a file.
 286 .It Fl s Ar char
 287 Separate text columns by the single character
 288 .Ar char
 289 instead of by the appropriate number of
 290 .Em <space>s
 291 (default for
 292 .Ar char
 293 is the
 294 .Em <tab>
 295 character).
 296 .It Fl t
 297 Print neither the five-line identifying
 298 header nor the five-line trailer usually supplied for each page.
 299 Quit printing after the last line of each file without spacing to the
 300 end of the page.
 301 .It Fl w Ar width
 302 Set the width of the line to
 303 .Ar width
 304 column positions for multiple text-column output only.
 305 If the
 306 .Fl w
 307 option is not specified and the
 308 .Fl s
 309 option is not specified, the default width is 72.
 310 If the
 311 .Fl w
 312 option is not specified and the
 313 .Fl s
 314 option is specified, the default width is 512.
 315 .It Ar file
 316 A pathname of a file to be printed.
 317 If no
 318 .Ar file
 319 operands are specified, or if a
 320 .Ar file
 321 operand is
 322 .Sq Fl ,
 323 the standard input is used.
 324 The standard input is used only if no
 325 .Ar file
 326 operands are specified, or if a
 327 .Ar file
 328 operand is
 329 .Sq Fl .
 330 .El
 331 .Pp
 332 The
 333 .Fl s
 334 option does not allow the option letter to be separated from its
 335 argument, and the options
 336 .Fl e ,
 337 .Fl i ,
 338 and
 339 .Fl n
 340 require that both arguments, if present, not be separated from the option
 341 letter.
 342 .Sh ERRORS
 343 .Pp
 344 If
 345 .Nm
 346 receives an interrupt while printing to a terminal, it
 347 flushes all accumulated error messages to the screen before
 348 terminating.
 349 .Pp
 350 The
 351 .Nm
 352 utility exits 0 on success, and 1 if an error occurs.
 353 .Pp
 354 Error messages are written to standard error during the printing
 355 process (if output is redirected) or after all successful
 356 file printing is complete (when printing to a terminal).
 357 .Sh SEE ALSO
 358 .Xr cat 1 ,
 359 .Xr more 1
 360 .Sh STANDARDS
 361 The
 362 .Nm
 363 utility is
 364 .St -p1003.2
 365 compatible.
 366 .Sh HISTORY
 367 A
 368 .Nm
 369 command appeared in
 370 .At v1 .