Provided by: manpages-posix_2.16-1_all bug

NAME

       pr - print files

SYNOPSIS

       pr [+page][-column][-adFmrt][-e[char][ gap]][-h header][-i[char][gap]]

               [-l lines][-n[char][width]][-o offset][-s[char]][-w width][-fp]
               [file...]

DESCRIPTION

       The pr utility is a printing and pagination filter. If multiple input files are specified,
       each shall be read, formatted, and written to standard output. By default, the input shall
       be separated into 66-line pages, each with:

        * A 5-line header that includes the page number, date, time, and the pathname of the file

        * A 5-line trailer consisting of blank lines

       If  standard  output  is associated with a terminal, diagnostic messages shall be deferred
       until the pr utility has completed processing.

       When options specifying multi-column output are specified, output text columns shall be of
       equal  width;  input  lines  that  do  not  fit  into a text column shall be truncated. By
       default, text columns shall be separated with at least one <blank>.

OPTIONS

       The pr utility shall conform to  the  Base  Definitions  volume  of  IEEE Std 1003.1-2001,
       Section 12.2, Utility Syntax Guidelines, except that: the page option has a '+' delimiter;
       page and column can be multi-digit numbers; some of the option-arguments are optional; and
       some  of the option-arguments cannot be specified as separate arguments from the preceding
       option letter. In particular, the -s option  does  not  allow  the  option  letter  to  be
       separated  from  its argument, and the options -e, -i, and -n require that both arguments,
       if present, not be separated from the option letter.

       The following options shall be supported. In the following  option  descriptions,  column,
       lines,  offset,  page,  and  width  are  positive  decimal integers; gap is a non-negative
       decimal integer.

       +page  Begin output at page number page of the formatted input.

       -column
              Produce multi-column output that is arranged in column columns (the  default  shall
              be  1)  and  is written down each column in the order in which the text is received
              from the input file. This option should not be used with -m. The options -e and  -i
              shall  be assumed for multiple text-column output.  Whether or not text columns are
              produced with identical vertical lengths is unspecified, but a  text  column  shall
              never exceed the length of the page (see the -l option). When used with -t, use the
              minimum number of lines to write the output.

       -a     Modify the effect of the - column option so that the columns are filled across  the
              page  in  a  round-robin order (for example, when column is 2, the first input line
              heads column 1, the second heads column 2, the third is the second line  in  column
              1, and so on).

       -d     Produce  output  that  is  double-spaced; append an extra <newline> following every
              <newline> found in the input.

       -e[char][gap]

              Expand each input <tab> to the  next  greater  column  position  specified  by  the
              formula n* gap+1, where n is an integer > 0. If gap is zero or is omitted, it shall
              default to 8. All <tab>s in the input shall be expanded into the appropriate number
              of  <space>s.  If  any non-digit character, char, is specified, it shall be used as
              the input <tab>.

       -f     Use a <form-feed> for new pages, instead  of  the  default  behavior  that  uses  a
              sequence  of  <newline>s.  Pause  before  beginning  the first page if the standard
              output is associated with a terminal.

       -F     Use a <form-feed> for new pages, instead  of  the  default  behavior  that  uses  a
              sequence of <newline>s.

       -h  header
              Use  the  string  header  to  replace  the contents of the file operand in the page
              header.

       -i[char][gap]
              In output, replace multiple <space>s with <tab>s  wherever  two  or  more  adjacent
              <space>s  reach  column  positions gap+1, 2* gap+1, 3* gap+1, and so on.  If gap is
              zero or is omitted, default tab settings at every eighth column position  shall  be
              assumed.  If  any  non-digit character, char, is specified, it shall be used as the
              output <tab>.

       -l  lines
              Override the 66-line default and reset the page length to lines.  If lines  is  not
              greater  than  the  sum  of  both  the header and trailer depths (in lines), the pr
              utility shall suppress both the header and trailer, as if the  -t  option  were  in
              effect.

       -m     Merge  files.  Standard output shall be formatted so the pr utility writes one line
              from each file specified by a file operand, side by side into text columns of equal
              fixed  widths,  in  terms of the number of column positions.  Implementations shall
              support merging of at least nine file operands.

       -n[char][width]

              Provide width-digit line numbering (default for width shall be 5). The number shall
              occupy  the  first  width column positions of each text column of default output or
              each line of -m output. If char (any non-digit character) is  given,  it  shall  be
              appended  to the line number to separate it from whatever follows (default for char
              is a <tab>).

       -o  offset
              Each line of output shall be preceded by offset <space>s. If the -o option  is  not
              specified,  the default offset shall be zero. The space taken is in addition to the
              output line width (see the -w option below).

       -p     Pause before beginning each page if the standard output is directed to a terminal (
              pr  shall write an <alert> to standard error and wait for a <carriage-return> to be
              read on /dev/tty).

       -r     Write no diagnostic reports on failure to open files.

       -s[char]
              Separate text columns by the single character char instead of  by  the  appropriate
              number of <space>s (default for char shall be <tab>).

       -t     Write  neither  the  five-line identifying header nor the five-line trailer usually
              supplied for each page. Quit writing after the  last  line  of  each  file  without
              spacing to the end of the page.

       -w  width
              Set the width of the line to width column positions for multiple text-column output
              only. If the -w option is not specified and the -s option  is  not  specified,  the
              default  width  shall be 72. If the -w option is not specified and the -s option is
              specified, the default width shall be 512.

       For single column output, input lines shall not be truncated.

OPERANDS

       The following operand shall be supported:

       file   A pathname of a file to be written. If no file operands are specified, or if a file
              operand is '-' , the standard input shall be used.

STDIN

       The  standard  input  shall  be  used only if no file operands are specified, or if a file
       operand is '-' .  See the INPUT FILES section.

INPUT FILES

       The input files shall be text files.

       The file /dev/tty shall be used to read responses required by the -p option.

ENVIRONMENT VARIABLES

       The following environment variables shall affect the execution of pr:

       LANG   Provide a default value for the internationalization variables that  are  unset  or
              null.  (See  the  Base  Definitions  volume  of  IEEE Std 1003.1-2001, Section 8.2,
              Internationalization Variables for the precedence of internationalization variables
              used to determine the values of locale categories.)

       LC_ALL If  set  to  a  non-empty  string  value,  override  the  values  of  all the other
              internationalization variables.

       LC_CTYPE
              Determine the locale for the interpretation of sequences of bytes of text  data  as
              characters  (for  example,  single-byte  as  opposed  to  multi-byte  characters in
              arguments and input files) and which characters are defined as printable (character
              class  print).  Non-printable  characters are still written to standard output, but
              are not counted for the purpose for column-width and line-length calculations.

       LC_MESSAGES
              Determine the locale that should be used to  affect  the  format  and  contents  of
              diagnostic messages written to standard error.

       LC_TIME
              Determine the format of the date and time for use in writing header lines.

       NLSPATH
              Determine the location of message catalogs for the processing of LC_MESSAGES .

       TZ     Determine  the  timezone  used to calculate date and time strings written in header
              lines. If TZ is unset or null, an unspecified default timezone shall be used.

ASYNCHRONOUS EVENTS

       If pr receives an interrupt while writing to a terminal, it shall  flush  all  accumulated
       error messages to the screen before terminating.

STDOUT

       The  pr  utility output shall be a paginated version of the original file (or files). This
       pagination shall be accomplished using either <form-feed>s or a sequence of <newline>s, as
       controlled by the -F    or -f option. Page headers shall be generated unless the -t option
       is specified. The page headers shall be of the form:

              "\n\n%s %s Page %d\n\n\n", <output of date>, <file>, <page number>

       In the POSIX locale, the <output of date> field, representing the date and  time  of  last
       modification of the input file (or the current date and time if the input file is standard
       input), shall be equivalent to the output of the following command as it would  appear  if
       executed at the given time:

              date "+%b %e %H:%M %Y"

       without  the  trailing <newline>, if the page being written is from standard input. If the
       page being written is not from standard input, in the POSIX locale, the same format  shall
       be  used,  but  the  time used shall be the modification time of the file corresponding to
       file instead of the current time. When the LC_TIME locale category is not set to the POSIX
       locale, a different format and order of presentation of this field may be used.

       If  the  standard  input  is  used  instead  of  a file operand, the <file> field shall be
       replaced by a null string.

       If the -h option is specified, the <file> field shall be replaced by the header argument.

STDERR

       The standard error shall be used for diagnostic messages and  for  alerting  the  terminal
       when -p is specified.

OUTPUT FILES

       None.

EXTENDED DESCRIPTION

       None.

EXIT STATUS

       The following exit values shall be returned:

        0     Successful completion.

       >0     An error occurred.

CONSEQUENCES OF ERRORS

       Default.

       The following sections are informative.

APPLICATION USAGE

       None.

EXAMPLES

        1. Print a numbered list of all files in the current directory:

           ls -a | pr -n -h "Files in $(pwd)."

        2. Print file1 and file2 as a double-spaced, three-column listing headed by "file list'':

           pr -3d -h "file list" file1 file2

        3. Write file1 on file2, expanding tabs to columns 10, 19, 28, ...:

           pr -e9 -t <file1 >file2

RATIONALE

       This utility is one of those that does not follow the Utility Syntax Guidelines because of
       its historical origins. The standard developers could have added new options  that  obeyed
       the  guidelines  (and  marked  the  old  options  obsolescent)  or devised an entirely new
       utility; there are examples of  both  actions  in  this  volume  of  IEEE Std 1003.1-2001.
       Because  of its widespread use by historical applications, the standard developers decided
       to exempt this version of pr from many of the guidelines.

       Implementations are required to accept option-arguments to the -h, -l, -o, and -w  options
       whether  presented  as  part  of  the  same  argument  or as a separate argument to pr, as
       suggested by the Utility Syntax Guidelines. The -n and -s options, however, are  specified
       as  in  historical  practice  because they are frequently specified without their optional
       arguments. If a <blank> were allowed before the option-argument in  these  cases,  a  file
       operand could mistakenly be interpreted as an option-argument in historical applications.

       The  text  about the minimum number of lines in multi-column output was included to ensure
       that a best effort is made in balancing  the  length  of  the  columns.  There  are  known
       historical implementations in which, for example, 60-line files are listed by pr -2 as one
       column of 56 lines and a second of 4. Although this is not a problem when a full page with
       headers and trailers is produced, it would be relatively useless when used with -t.

       Historical  implementations of the pr utility have differed in the action taken for the -f
       option. BSD uses it as described here for the -F  option;  System  V  uses  it  to  change
       trailing <newline>s on each page to a <form-feed> and, if standard output is a TTY device,
       sends an <alert> to standard error and reads a line from /dev/tty before the  first  page.
       There  were  strong arguments from both sides of this issue concerning historical practice
       and as a result the -F option was added.  XSI-conformant  systems  support  the  System  V
       historical actions for the -f option.

       The  <output of date>  field  in  the -l format is specified only for the POSIX locale. As
       noted, the format can be different in other locales. No mechanism  for  defining  this  is
       present  in  this  volume of IEEE Std 1003.1-2001, as the appropriate vehicle is a message
       catalog; that is, the format should be specified as a "message".

FUTURE DIRECTIONS

       None.

SEE ALSO

       expand , lp

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1,  2003  Edition,  Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard,  the  original  IEEE  and  The  Open Group Standard is the referee document. The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .