pr man page on Archlinux

Man page or keyword search:  
man Server   11224 pages
apropos Keyword Search (all sections)
Output format
Archlinux logo
[printable version]

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
       POSIX.1‐2008, 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 sepa‐
       rated 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  col‐
		 umns (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 ver‐
		 tical 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 exam‐
		 ple, 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	 <new‐
		 line> 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> characters in the input	shall  be  expanded  into  the
		 appropriate  number  of  <space> characters. If any non-digit
		 character, char, is specified, it shall be used as the	 input
		 <tab>.	 If the first character of the −e option-argument is a
		 digit, the entire option-argument shall be assumed to be gap.

       −f	 Use a <form-feed> for	new  pages,  instead  of  the  default
		 behavior  that uses a sequence of <newline> characters. 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> characters.

       −h header Use the string header to replace the contents of the file op‐
		 erand in the page header.

       −i[char][gap]
		 In  output,  replace <space> characters with <tab> characters
		 wherever one or more adjacent <space> characters 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 col‐
		 umn  position	shall  be assumed. If any non-digit character,
		 char, is specified, it shall be used as the output <tab>.  If
		 the first character of the −i option-argument is a digit, the
		 entire option-argument shall be assumed to be gap.

       −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. Implemen‐
		 tations 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 posi‐
		 tions 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> char‐
		 acters. 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> characters (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  mul‐
		 tiple text-column output only. If the −w option is not speci‐
		 fied 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	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	 vari‐
		 ables	that are unset or null. (See the Base Definitions vol‐
		 ume of POSIX.1‐2008, Section 8.2, Internationalization	 Vari‐
		 ables	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 (charac‐
		 ter 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> characters or a sequence of <newline> characters,	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 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
       A  conforming  application must protect its first operand, if it starts
       with a <plus-sign>, by preceding it with the "−−" argument that denotes
       the  end	 of  the options. For example, pr+x could be interpreted as an
       invalid page number or a file operand.

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 POSIX.1‐2008. 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 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> characters  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
       POSIX.1‐2008, 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

       The Base Definitions volume of  POSIX.1‐2008,  Chapter  8,  Environment
       Variables, Section 12.2, Utility Syntax Guidelines

COPYRIGHT
       Portions	 of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       --  Portable  Operating	System	Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
       cal  and	 Electronics  Engineers,  Inc  and  The	 Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum	 1  applied.)  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.unix.org/online.html .

       Any typographical or formatting errors that appear  in  this  page  are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors,	 see  https://www.ker‐
       nel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group		     2013				PR(1P)
[top]

List of man pages available for Archlinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net