PR(1P) - phpMan

PR(1P)                     POSIX Programmer's Manual                    PR(1P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the  corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.
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 sepa-
       rated 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 deci-
       mal 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 unspeci-
              fied, 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 oper-
              and 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  util-
              ity  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 sup-
              port 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 speci-
              fied, 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  speci-
       fied, 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  Vari-
              ables  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  speci-
       fied. 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 stan-
       dard 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 alert-
       ing 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 guide-
       lines.
       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  Guide-
       lines.  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 use-
       less 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 .

IEEE/The Open Group                  2003                               PR(1P)