usr.bin/pr/pr.1

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