xcu_chap02.html

IEEE 1003.1-2003, Single Unix Specification v3

<h4><a name="tag_02_06_07"></a>Quote Removal</h4>

<p>The quote characters: <tt>'\'</tt> , <tt>'&quot;</tt> , and <tt>''</tt> (backslash, single-quote, double-quote) that were present in
the original word shall be removed unless they have themselves been quoted.</p>

<h3><a name="tag_02_07"></a>Redirection</h3>

<p>Redirection is used to open and close files for the current shell execution environment (see <a href="#tag_02_12">Shell
Execution Environment</a> ) or for any command. Redirection operators can be used with numbers representing file descriptors (see
the Base Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../basedefs/xbd_chap03.html#tag_03_165">Section 3.165, File
Descriptor</a>) as described below.</p>

<p>The overall format used for redirection is:</p>

<blockquote>
<pre>
<b>[</b><i>n</i><b>]</b><i>redir-op word</i>
</pre>
</blockquote>

<p>The number <i>n</i> is an optional decimal number designating the file descriptor number; the application shall ensure it is
delimited from any preceding text and immediately precede the redirection operator <i>redir-op</i>. If <i>n</i> is quoted, the
number shall not be recognized as part of the redirection expression. For example:</p>

<blockquote>
<pre>
<tt>echo \2&gt;a
</tt>
</pre>
</blockquote>

<p>writes the character 2 into file <b>a</b>. If any part of <i>redir-op</i> is quoted, no redirection expression is recognized.
For example:</p>

<blockquote>
<pre>
<tt>echo 2\&gt;a
</tt>
</pre>
</blockquote>

<p>writes the characters 2&gt;<i>a</i> to standard output. The optional number, redirection operator, and <i>word</i> shall not
appear in the arguments provided to the command to be executed (if any).</p>

<p>Open files are represented by decimal numbers starting with zero. The largest possible value is implementation-defined; however,
all implementations shall support at least 0 to 9, inclusive, for use by the application. These numbers are called &quot;file
descriptors&quot;. The values 0, 1, and 2 have special meaning and conventional uses and are implied by certain redirection operations;
they are referred to as <i>standard input</i>, <i>standard output</i>, and <i>standard error</i>, respectively. Programs usually
take their input from standard input, and write output on standard output. Error messages are usually written on standard error.
The redirection operators can be preceded by one or more digits (with no intervening &lt;blank&gt;s allowed) to designate the file
descriptor number.</p>

<p>If the redirection operator is <tt>"&lt;&lt;"</tt> or <tt>"&lt;&lt;-"</tt> , the word that follows the redirection operator
shall be subjected to quote removal; it is unspecified whether any of the other expansions occur. For the other redirection
operators, the word that follows the redirection operator shall be subjected to tilde expansion, parameter expansion, command
substitution, arithmetic expansion, and quote removal. Pathname expansion shall not be performed on the word by a non-interactive
shell; an interactive shell may perform it, but shall do so only when the expansion would result in one word.</p>

<p>If more than one redirection operator is specified with a command, the order of evaluation is from beginning to end.</p>

<p>A failure to open or create a file shall cause a redirection to fail.</p>

<h4><a name="tag_02_07_01"></a>Redirecting Input</h4>

<p>Input redirection shall cause the file whose name results from the expansion of <i>word</i> to be opened for reading on the
designated file descriptor, or standard input if the file descriptor is not specified.</p>

<p>The general format for redirecting input is:</p>

<blockquote>
<pre>
<b>[</b><i>n</i><b>]</b><tt>&lt;</tt><i>word</i>
</pre>
</blockquote>

<p>where the optional <i>n</i> represents the file descriptor number. If the number is omitted, the redirection shall refer to
standard input (file descriptor 0).</p>

<h4><a name="tag_02_07_02"></a>Redirecting Output</h4>

<p>The two general formats for redirecting output are:</p>

<blockquote>
<pre>
<b>[</b><i>n</i><b>]</b><tt>&gt;</tt><i>word</i>
<b>[</b><i>n</i><b>]</b><tt>&gt;|</tt><i>word</i>
</pre>
</blockquote>

<p>where the optional <i>n</i> represents the file descriptor number. If the number is omitted, the redirection shall refer to
standard output (file descriptor 1).</p>

<p>Output redirection using the <tt>'&gt;'</tt> format shall fail if the <i>noclobber</i> option is set (see the description of <a
href="set.html"><i>set</i></a> <b>-C</b>) and the file named by the expansion of <i>word</i> exists and is a regular file. Otherwise,
redirection using the <tt>'&gt;'</tt> or <tt>"&gt;|"</tt> formats shall cause the file whose name results from the expansion of
<i>word</i> to be created and opened for output on the designated file descriptor, or standard output if none is specified. If the
file does not exist, it shall be created; otherwise, it shall be truncated to be an empty file after being opened.</p>

<h4><a name="tag_02_07_03"></a>Appending Redirected Output</h4>

<p>Appended output redirection shall cause the file whose name results from the expansion of word to be opened for output on the
designated file descriptor. The file is opened as if the <a href="../functions/open.html"><i>open</i>()</a> function as defined in
the System Interfaces volume of IEEE&nbsp;Std&nbsp;1003.1-2001 was called with the O_APPEND flag. If the file does not exist, it
shall be created.</p>

<p>The general format for appending redirected output is as follows:</p>

<blockquote>
<pre>
<b>[</b><i>n</i><b>]</b><tt>&gt;&gt;</tt><i>word</i>
</pre>
</blockquote>

<p>where the optional <i>n</i> represents the file descriptor number. If the number is omitted, the redirection refers to standard
output (file descriptor 1).</p>

<h4><a name="tag_02_07_04"></a>Here-Document</h4>

<p>The redirection operators <tt>"&lt;&lt;"</tt> and <tt>"&lt;&lt;-"</tt> both allow redirection of lines contained in a shell
input file, known as a &quot;here-document&quot;, to the input of a command.</p>

<p>The here-document shall be treated as a single word that begins after the next &lt;newline&gt; and continues until there is a
line containing only the delimiter and a &lt;newline&gt;, with no &lt;blank&gt;s in between. Then the next here-document starts, if
there is one. The format is as follows:</p>

<blockquote>
<pre>
<b>[</b><i>n</i><b>]</b><tt>&lt;&lt;</tt><i>word
    here-document
delimiter</i>
</pre>
</blockquote>

<p>where the optional <i>n</i> represents the file descriptor number. If the number is omitted, the here-document refers to
standard input (file descriptor 0).</p>

<p>If any character in <i>word</i> is quoted, the delimiter shall be formed by performing quote removal on <i>word</i>, and the
here-document lines shall not be expanded. Otherwise, the delimiter shall be the <i>word</i> itself.</p>

<p>If no characters in <i>word</i> are quoted, all lines of the here-document shall be expanded for parameter expansion, command
substitution, and arithmetic expansion. In this case, the backslash in the input behaves as the backslash inside double-quotes (see
<a href="#tag_02_02_03">Double-Quotes</a> ). However, the double-quote character ( <tt>' )'</tt> shall not be treated specially
within a here-document, except when the double-quote appears within <tt>"$()"</tt> , <tt>"``"</tt> , or <tt>"${}"</tt> .</p>

<p>If the redirection symbol is <tt>"&lt;&lt;-"</tt> , all leading &lt;tab&gt;s shall be stripped from input lines and the line
containing the trailing delimiter. If more than one <tt>"&lt;&lt;"</tt> or <tt>"&lt;&lt;-"</tt> operator is specified on a line,
the here-document associated with the first operator shall be supplied first by the application and shall be read first by the
shell.</p>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h5><a name="tag_02_07_04_01"></a>Examples</h5>

<p>An example of a here-document follows:</p>

<blockquote>
<pre>
<tt>cat &lt;&lt;eof1; cat &lt;&lt;eof2
Hi,
eof1
Helene.
eof2
</tt>
</pre>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<h4><a name="tag_02_07_05"></a>Duplicating an Input File Descriptor</h4>

<p>The redirection operator:</p>

<blockquote>
<pre>
<b>[</b><i>n</i><b>]</b><tt>&lt;&amp;</tt><i>word</i>
</pre>
</blockquote>

<p>shall duplicate one input file descriptor from another, or shall close one. If <i>word</i> evaluates to one or more digits, the
file descriptor denoted by <i>n</i>, or standard input if <i>n</i> is not specified, shall be made to be a copy of the file
descriptor denoted by <i>word</i>; if the digits in <i>word</i> do not represent a file descriptor already open for input, a
redirection error shall result; see <a href="#tag_02_08_01">Consequences of Shell Errors</a> . If <i>word</i> evaluates to
<tt>'-'</tt> , file descriptor <i>n</i>, or standard input if <i>n</i> is not specified, shall be closed. Attempts to close a file
descriptor that is not open shall not constitute an error. If <i>word</i> evaluates to something else, the behavior is
unspecified.</p>

<h4><a name="tag_02_07_06"></a>Duplicating an Output File Descriptor</h4>

<p>The redirection operator:</p>

<blockquote>
<pre>
<b>[</b><i>n</i><b>]</b><tt>&gt;&amp;</tt><i>word</i>
</pre>
</blockquote>

<p>shall duplicate one output file descriptor from another, or shall close one. If <i>word</i> evaluates to one or more digits, the
file descriptor denoted by <i>n</i>, or standard output if <i>n</i> is not specified, shall be made to be a copy of the file
descriptor denoted by <i>word</i>; if the digits in <i>word</i> do not represent a file descriptor already open for output, a
redirection error shall result; see <a href="#tag_02_08_01">Consequences of Shell Errors</a> . If <i>word</i> evaluates to
<tt>'-'</tt> , file descriptor <i>n</i>, or standard output if <i>n</i> is not specified, is closed. Attempts to close a file
descriptor that is not open shall not constitute an error. If <i>word</i> evaluates to something else, the behavior is
unspecified.</p>

<h4><a name="tag_02_07_07"></a>Open File Descriptors for Reading and Writing</h4>

<p>The redirection operator:</p>

<blockquote>
<pre>
<b>[</b><i>n</i><b>]</b><tt>&lt;&gt;</tt><i>word</i>
</pre>
</blockquote>

<p>shall cause the file whose name is the expansion of <i>word</i> to be opened for both reading and writing on the file descriptor
denoted by <i>n</i>, or standard input if <i>n</i> is not specified. If the file does not exist, it shall be created.</p>

<h3><a name="tag_02_08"></a>Exit Status and Errors</h3>

<h4><a name="tag_02_08_01"></a>Consequences of Shell Errors</h4>

<p>For a non-interactive shell, an error condition encountered by a special built-in (see <a href="#tag_02_14">Special Built-In
Utilities</a> ) or other type of utility shall cause the shell to write a diagnostic message to standard error and exit as shown in
the following table:</p>

<center>
<table border="1" cellpadding="3" align="center">
<tr valign="top">
<th align="center">
<p class="tent"><b>Error</b></p>
</th>
<th align="center">
<p class="tent"><b>Special Built-In</b></p>
</th>
<th align="center">
<p class="tent"><b>Other Utilities</b></p>
</th>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">Shell language syntax error</p>
</td>
<td align="left">
<p class="tent">Shall exit</p>
</td>
<td align="left">
<p class="tent">Shall exit</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">Utility syntax error (option or operand error)</p>
</td>
<td align="left">
<p class="tent">Shall exit</p>
</td>
<td align="left">
<p class="tent">Shall not exit</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">Redirection error</p>
</td>
<td align="left">
<p class="tent">Shall exit</p>
</td>
<td align="left">
<p class="tent">Shall not exit</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">Variable assignment error</p>
</td>
<td align="left">
<p class="tent">Shall exit</p>
</td>
<td align="left">
<p class="tent">Shall not exit</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">Expansion error</p>
</td>
<td align="left">
<p class="tent">Shall exit</p>
</td>
<td align="left">
<p class="tent">Shall exit</p>
</td>