459 lines
19 KiB
HTML
459 lines
19 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>pr</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="pr"></a> <a name="tag_04_101"></a><!-- pr -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_04_101_01"></a>NAME</h4>
|
|
|
|
<blockquote>pr - print files</blockquote>
|
|
|
|
<h4><a name="tag_04_101_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>pr</tt>
|
|
<b>[</b><tt>+</tt><i>page</i><b>][</b><tt>-</tt><i>column</i><b>][</b><tt>-adFmrt</tt><b>][</b><tt>-e</tt><b>[</b><i>char</i><b>][</b><i>
|
|
gap</i><b>]][</b><tt>-h</tt> <i>header</i><b>][</b><tt>-i</tt><b>[</b><i>char</i><b>][</b><i>gap</i><b>]] <sup>[<a href=
|
|
"javascript:open_code('XSI')">XSI</a>]</sup><br>
|
|
</b> <tt> </tt> <b>[</b><tt>-l</tt>
|
|
<i>lines</i><b>][</b><tt>-n</tt><b>[</b><i>char</i><b>][</b><i>width</i><b>]][</b><tt>-o</tt>
|
|
<i>offset</i><b>][</b><tt>-s</tt><b>[</b><i>char</i><b>]][</b><tt>-w</tt> <i>width</i><b>][</b><tt><img src=
|
|
"../images/opt-start.gif" border="0">-f<img src="../images/opt-end.gif" border="0">p</tt><b>]<br>
|
|
</b> <tt> </tt> <b>[</b><i>file</i><tt>...</tt><b>]</b></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_101_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>pr</i> 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:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>A 5-line header that includes the page number, date, time, and the pathname of the file</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A 5-line trailer consisting of blank lines</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>If standard output is associated with a terminal, diagnostic messages shall be deferred until the <i>pr</i> utility has
|
|
completed processing.</p>
|
|
|
|
<p>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>.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_101_04"></a>OPTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>pr</i> utility shall conform to the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/xbd_chap12.html#tag_12_02">Section 12.2, Utility Syntax Guidelines</a>, except that: the <i>page</i> option has a
|
|
<tt>'+'</tt> delimiter; <i>page</i> and <i>column</i> 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
|
|
<b>-s</b> option does not allow the option letter to be separated from its argument, and the options <b>-e</b>, <b>-i</b>, and
|
|
<b>-n</b> require that both arguments, if present, not be separated from the option letter.</p>
|
|
|
|
<p>The following options shall be supported. In the following option descriptions, <i>column</i>, <i>lines</i>, <i>offset</i>,
|
|
<i>page</i>, and <i>width</i> are positive decimal integers; <i>gap</i> is a non-negative decimal integer.</p>
|
|
|
|
<dl compact>
|
|
<dt><b>+</b><i>page</i></dt>
|
|
|
|
<dd>Begin output at page number <i>page</i> of the formatted input.</dd>
|
|
|
|
<dt><b>-</b><i>column</i></dt>
|
|
|
|
<dd>Produce multi-column output that is arranged in <i>column</i> 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 <b>-m</b>. The options
|
|
<b>-e</b> and <b>-i</b> 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 <b>-l</b> option). When used
|
|
with <b>-t</b>, use the minimum number of lines to write the output.</dd>
|
|
|
|
<dt><b>-a</b></dt>
|
|
|
|
<dd>Modify the effect of the <b>-</b> <i>column</i> option so that the columns are filled across the page in a round-robin order
|
|
(for example, when <i>column</i> 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).</dd>
|
|
|
|
<dt><b>-d</b></dt>
|
|
|
|
<dd>Produce output that is double-spaced; append an extra <newline> following every <newline> found in the input.</dd>
|
|
|
|
<dt><b>-e[</b><i>char</i><b>][</b><i>gap</i><b>]</b></dt>
|
|
|
|
<dd><br>
|
|
Expand each input <tab> to the next greater column position specified by the formula <i>n</i>* <i>gap</i>+1, where <i>n</i>
|
|
is an integer > 0. If <i>gap</i> 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, <i>char</i>, is specified, it shall be used as the input
|
|
<tab>.</dd>
|
|
|
|
<dt><b>-f</b></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
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. <img src="../images/opt-end.gif" alt="[Option End]"
|
|
border="0"></dd>
|
|
|
|
<dt><b>-F</b></dt>
|
|
|
|
<dd>Use a <form-feed> for new pages, instead of the default behavior that uses a sequence of <newline>s.</dd>
|
|
|
|
<dt><b>-h </b> <i>header</i></dt>
|
|
|
|
<dd>Use the string <i>header</i> to replace the contents of the <i>file</i> operand in the page header.</dd>
|
|
|
|
<dt><b>-i[</b><i>char</i><b>][</b><i>gap</i><b>]</b></dt>
|
|
|
|
<dd>In output, replace multiple <space>s with <tab>s wherever two or more adjacent <space>s reach column
|
|
positions <i>gap</i>+1, 2* <i>gap</i>+1, 3* <i>gap</i>+1, and so on. If <i>gap</i> is zero or is omitted, default tab settings at
|
|
every eighth column position shall be assumed. If any non-digit character, <i>char</i>, is specified, it shall be used as the
|
|
output <tab>.</dd>
|
|
|
|
<dt><b>-l </b> <i>lines</i></dt>
|
|
|
|
<dd>Override the 66-line default and reset the page length to <i>lines</i>. If <i>lines</i> is not greater than the sum of both the
|
|
header and trailer depths (in lines), the <i>pr</i> utility shall suppress both the header and trailer, as if the <b>-t</b> option
|
|
were in effect.</dd>
|
|
|
|
<dt><b>-m</b></dt>
|
|
|
|
<dd>Merge files. Standard output shall be formatted so the <i>pr</i> utility writes one line from each file specified by a
|
|
<i>file</i> 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 <i>file</i> operands.</dd>
|
|
|
|
<dt><b>-n[</b><i>char</i><b>][</b><i>width</i><b>]</b></dt>
|
|
|
|
<dd><br>
|
|
Provide <i>width</i>-digit line numbering (default for <i>width</i> shall be 5). The number shall occupy the first <i>width</i>
|
|
column positions of each text column of default output or each line of <b>-m</b> output. If <i>char</i> (any non-digit character)
|
|
is given, it shall be appended to the line number to separate it from whatever follows (default for <i>char</i> is a
|
|
<tab>).</dd>
|
|
|
|
<dt><b>-o </b> <i>offset</i></dt>
|
|
|
|
<dd>Each line of output shall be preceded by offset <space>s. If the <b>-o</b> option is not specified, the default offset
|
|
shall be zero. The space taken is in addition to the output line width (see the <b>-w</b> option below).</dd>
|
|
|
|
<dt><b>-p</b></dt>
|
|
|
|
<dd>Pause before beginning each page if the standard output is directed to a terminal ( <i>pr</i> shall write an <alert> to
|
|
standard error and wait for a <carriage-return> to be read on <b>/dev/tty</b>).</dd>
|
|
|
|
<dt><b>-r</b></dt>
|
|
|
|
<dd>Write no diagnostic reports on failure to open files.</dd>
|
|
|
|
<dt><b>-s[</b><i>char</i><b>]</b></dt>
|
|
|
|
<dd>Separate text columns by the single character <i>char</i> instead of by the appropriate number of <space>s (default for
|
|
<i>char</i> shall be <tab>).</dd>
|
|
|
|
<dt><b>-t</b></dt>
|
|
|
|
<dd>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.</dd>
|
|
|
|
<dt><b>-w </b> <i>width</i></dt>
|
|
|
|
<dd>Set the width of the line to <i>width</i> column positions for multiple text-column output only. If the <b>-w</b> option is not
|
|
specified and the <b>-s</b> option is not specified, the default width shall be 72. If the <b>-w</b> option is not specified and
|
|
the <b>-s</b> option is specified, the default width shall be 512.
|
|
|
|
<p>For single column output, input lines shall not be truncated.</p>
|
|
</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_101_05"></a>OPERANDS</h4>
|
|
|
|
<blockquote>
|
|
<p>The following operand shall be supported:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>file</i></dt>
|
|
|
|
<dd>A pathname of a file to be written. If no <i>file</i> operands are specified, or if a <i>file</i> operand is <tt>'-'</tt> , the
|
|
standard input shall be used.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_101_06"></a>STDIN</h4>
|
|
|
|
<blockquote>
|
|
<p>The standard input shall be used only if no <i>file</i> operands are specified, or if a <i>file</i> operand is <tt>'-'</tt> .
|
|
See the INPUT FILES section.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_101_07"></a>INPUT FILES</h4>
|
|
|
|
<blockquote>
|
|
<p>The input files shall be text files.</p>
|
|
|
|
<p>The file <b>/dev/tty</b> shall be used to read responses required by the <b>-p</b> option.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_101_08"></a>ENVIRONMENT VARIABLES</h4>
|
|
|
|
<blockquote>
|
|
<p>The following environment variables shall affect the execution of <i>pr</i>:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>LANG</i></dt>
|
|
|
|
<dd>Provide a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <a href="../basedefs/xbd_chap08.html#tag_08_02">Section 8.2, Internationalization Variables</a> for
|
|
the precedence of internationalization variables used to determine the values of locale categories.)</dd>
|
|
|
|
<dt><i>LC_ALL</i></dt>
|
|
|
|
<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>
|
|
|
|
<dt><i>LC_CTYPE</i></dt>
|
|
|
|
<dd>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
|
|
<b>print</b>). Non-printable characters are still written to standard output, but are not counted for the purpose for column-width
|
|
and line-length calculations.</dd>
|
|
|
|
<dt><i>LC_MESSAGES</i></dt>
|
|
|
|
<dd>Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard
|
|
error.</dd>
|
|
|
|
<dt><i>LC_TIME</i></dt>
|
|
|
|
<dd>Determine the format of the date and time for use in writing header lines.</dd>
|
|
|
|
<dt><i>NLSPATH</i></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Determine the location of message catalogs for the processing of <i>LC_MESSAGES .</i> <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></dd>
|
|
|
|
<dt><i>TZ</i></dt>
|
|
|
|
<dd>Determine the timezone used to calculate date and time strings written in header lines. If <i>TZ</i> is unset or null, an
|
|
unspecified default timezone shall be used.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_101_09"></a>ASYNCHRONOUS EVENTS</h4>
|
|
|
|
<blockquote>
|
|
<p>If <i>pr</i> receives an interrupt while writing to a terminal, it shall flush all accumulated error messages to the screen
|
|
before terminating.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_101_10"></a>STDOUT</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>pr</i> 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 <b>-F</b> <sup>[<a href=
|
|
"javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> or <b>-f</b>
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0"> option. Page headers shall be generated unless the <b>-t</b> option
|
|
is specified. The page headers shall be of the form:</p>
|
|
|
|
<pre>
|
|
<tt>"\n\n%s %s Page %d\n\n\n", <</tt><i>output of date</i><tt>>, <</tt><i>file</i><tt>>, <</tt><i>page number</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>In the POSIX locale, the <<i>output of date</i>> 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:</p>
|
|
|
|
<pre>
|
|
<tt>date "+%b %e %H:%M %Y"
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>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 <i>file</i> instead of the current time. When the <i>LC_TIME</i> locale category is not set to the POSIX locale, a
|
|
different format and order of presentation of this field may be used.</p>
|
|
|
|
<p>If the standard input is used instead of a <i>file</i> operand, the <<i>file</i>> field shall be replaced by a null
|
|
string.</p>
|
|
|
|
<p>If the <b>-h</b> option is specified, the <<i>file</i>> field shall be replaced by the <i>header</i> argument.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_101_11"></a>STDERR</h4>
|
|
|
|
<blockquote>
|
|
<p>The standard error shall be used for diagnostic messages and for alerting the terminal when <b>-p</b> is specified.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_101_12"></a>OUTPUT FILES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_101_13"></a>EXTENDED DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_101_14"></a>EXIT STATUS</h4>
|
|
|
|
<blockquote>
|
|
<p>The following exit values shall be returned:</p>
|
|
|
|
<dl compact>
|
|
<dt> 0</dt>
|
|
|
|
<dd>Successful completion.</dd>
|
|
|
|
<dt>>0</dt>
|
|
|
|
<dd>An error occurred.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_101_15"></a>CONSEQUENCES OF ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>Default.</p>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_04_101_16"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_101_17"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<ol>
|
|
<li>
|
|
<p>Print a numbered list of all files in the current directory:</p>
|
|
|
|
<pre>
|
|
<tt>ls -a | pr -n -h "Files in $(pwd)."
|
|
</tt>
|
|
</pre>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Print <b>file1</b> and <b>file2</b> as a double-spaced, three-column listing headed by "file list'':</p>
|
|
|
|
<pre>
|
|
<tt>pr -3d -h "file list" file1 file2
|
|
</tt>
|
|
</pre>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Write <b>file1</b> on <b>file2</b>, expanding tabs to columns 10, 19, 28, ...:</p>
|
|
|
|
<pre>
|
|
<tt>pr -e9 -t <file1 >file2
|
|
</tt>
|
|
</pre>
|
|
</li>
|
|
</ol>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_101_18"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>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 <i>pr</i> from many of the guidelines.</p>
|
|
|
|
<p>Implementations are required to accept option-arguments to the <b>-h</b>, <b>-l</b>, <b>-o</b>, and <b>-w</b> options whether
|
|
presented as part of the same argument or as a separate argument to <i>pr</i>, as suggested by the Utility Syntax Guidelines. The
|
|
<b>-n</b> and <b>-s</b> 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 <i>file</i> operand could
|
|
mistakenly be interpreted as an option-argument in historical applications.</p>
|
|
|
|
<p>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 <i>pr</i>
|
|
-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 <b>-t</b>.</p>
|
|
|
|
<p>Historical implementations of the <i>pr</i> utility have differed in the action taken for the <b>-f</b> option. BSD uses it as
|
|
described here for the <b>-F</b> 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 <b>/dev/tty</b> before the
|
|
first page. There were strong arguments from both sides of this issue concerning historical practice and as a result the <b>-F</b>
|
|
option was added. XSI-conformant systems support the System V historical actions for the <b>-f</b> option.</p>
|
|
|
|
<p>The <<i>output of date</i>> field in the <b>-l</b> 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".</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_101_19"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_101_20"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="expand.html"><i>expand</i></a> , <a href="lp.html"><i>lp</i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_101_21"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 2.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_101_22"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The <b>-p</b> option is added.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|