xcu_chap02.html

IEEE 1003.1-2003, Single Unix Specification v3

</ol>

<p>The expansions described in this section shall occur in the same shell environment as that in which the command is executed.</p>

<p>If the complete expansion appropriate for a word results in an empty field, that empty field shall be deleted from the list of
fields that form the completely expanded command, unless the original word contained single-quote or double-quote characters.</p>

<p>The <tt>'$'</tt> character is used to introduce parameter expansion, command substitution, or arithmetic evaluation. If an
unquoted <tt>'$'</tt> is followed by a character that is either not numeric, the name of one of the special parameters (see <a
href="#tag_02_05_02">Special Parameters</a> ), a valid first character of a variable name, a left curly brace ( <tt>'{'</tt> ) or a
left parenthesis, the result is unspecified.</p>

<h4><a name="tag_02_06_01"></a>Tilde Expansion</h4>

<p>A &quot;tilde-prefix&quot; consists of an unquoted tilde character at the beginning of a word, followed by all of the characters
preceding the first unquoted slash in the word, or all the characters in the word if there is no slash. In an assignment (see the
Base Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../basedefs/xbd_chap04.html#tag_04_21">Section 4.21, Variable
Assignment</a>), multiple tilde-prefixes can be used: at the beginning of the word (that is, following the equal sign of the
assignment), following any unquoted colon, or both. A tilde-prefix in an assignment is terminated by the first unquoted colon or
slash. If none of the characters in the tilde-prefix are quoted, the characters in the tilde-prefix following the tilde are treated
as a possible login name from the user database. A portable login name cannot contain characters outside the set given in the
description of the <i>LOGNAME</i> environment variable in the Base Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href=
"../basedefs/xbd_chap08.html#tag_08_03">Section 8.3, Other Environment Variables</a>. If the login name is null (that is, the
tilde-prefix contains only the tilde), the tilde-prefix is replaced by the value of the variable <i>HOME .</i> If <i>HOME</i> is
unset, the results are unspecified. Otherwise, the tilde-prefix shall be replaced by a pathname of the initial working directory
associated with the login name obtained using the <a href="../functions/getpwnam.html"><i>getpwnam</i>()</a> function as defined in
the System Interfaces volume of IEEE&nbsp;Std&nbsp;1003.1-2001. If the system does not recognize the login name, the results are
undefined.</p>

<h4><a name="tag_02_06_02"></a>Parameter Expansion</h4>

<p>The format for parameter expansion is as follows:</p>

<blockquote>
<pre>
<tt>${</tt><i>expression</i><tt>}
</tt>
</pre>
</blockquote>

<p>where <i>expression</i> consists of all characters until the matching <tt>'}'</tt> . Any <tt>'}'</tt> escaped by a backslash or
within a quoted string, and characters in embedded arithmetic expansions, command substitutions, and variable expansions, shall not
be examined in determining the matching <tt>'}'</tt> .</p>

<p>The simplest form for parameter expansion is:</p>

<blockquote>
<pre>
<tt>${</tt><i>parameter</i><tt>}
</tt>
</pre>
</blockquote>

<p>The value, if any, of <i>parameter</i> shall be substituted.</p>

<p>The parameter name or symbol can be enclosed in braces, which are optional except for positional parameters with more than one
digit or when <i>parameter</i> is followed by a character that could be interpreted as part of the name. The matching closing brace
shall be determined by counting brace levels, skipping over enclosed quoted strings, and command substitutions.</p>

<p>If the parameter name or symbol is not enclosed in braces, the expansion shall use the longest valid name (see the Base
Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../basedefs/xbd_chap03.html#tag_03_230">Section 3.230, Name</a>),
whether or not the symbol represented by that name exists.</p>

<p>If a parameter expansion occurs inside double-quotes:</p>

<ul>
<li>
<p>Pathname expansion shall not be performed on the results of the expansion.</p>
</li>

<li>
<p>Field splitting shall not be performed on the results of the expansion, with the exception of <tt>'@'</tt> ; see <a href=
"#tag_02_05_02">Special Parameters</a> .</p>
</li>
</ul>

<p>In addition, a parameter expansion can be modified by using one of the following formats. In each case that a value of
<i>word</i> is needed (based on the state of <i>parameter</i>, as described below), <i>word</i> shall be subjected to tilde
expansion, parameter expansion, command substitution, and arithmetic expansion. If <i>word</i> is not needed, it shall not be
expanded. The <tt>'}'</tt> character that delimits the following parameter expansion modifications shall be determined as described
previously in this section and in <a href="#tag_02_02_03">Double-Quotes</a> . (For example, ${ <b>foo-bar</b>} <b>xyz</b>} would
result in the expansion of <b>foo</b> followed by the string <b>xyz</b>} if <b>foo</b> is set, else the string <tt>"barxyz}"</tt>
).</p>

<dl compact>
<dt>${<i>parameter</i>:-<i>word</i>}</dt>

<dd><b>Use Default Values</b>. If <i>parameter</i> is unset or null, the expansion of <i>word</i> shall be substituted; otherwise,
the value of <i>parameter</i> shall be substituted.</dd>

<dt>${<i>parameter</i>:=<i>word</i>}</dt>

<dd><b>Assign Default Values</b>. If <i>parameter</i> is unset or null, the expansion of <i>word</i> shall be assigned to
<i>parameter</i>. In all cases, the final value of <i>parameter</i> shall be substituted. Only variables, not positional parameters
or special parameters, can be assigned in this way.</dd>

<dt>${<i>parameter</i>:?<b>[</b><i>word</i><b>]</b>}</dt>

<dd><b>Indicate Error if Null or Unset</b>. If <i>parameter</i> is unset or null, the expansion of <i>word</i> (or a message
indicating it is unset if <i>word</i> is omitted) shall be written to standard error and the shell exits with a non-zero exit
status. Otherwise, the value of <i>parameter</i> shall be substituted. An interactive shell need not exit.</dd>

<dt>${<i>parameter</i>:+<i>word</i>}</dt>

<dd><b>Use Alternative Value</b>. If <i>parameter</i> is unset or null, null shall be substituted; otherwise, the expansion of
<i>word</i> shall be substituted.</dd>
</dl>

<p>In the parameter expansions shown previously, use of the colon in the format shall result in a test for a parameter that is
unset or null; omission of the colon shall result in a test for a parameter that is only unset. The following table summarizes the
effect of the colon:</p>

<center>
<table border="1" cellpadding="3" align="center">
<tr valign="top">
<th align="center">
<p class="tent"><i>&nbsp;</i></p>
</th>
<th align="center">
<p class="tent"><i>parameter</i></p>
</th>
<th align="center">
<p class="tent"><i>parameter</i></p>
</th>
<th align="center">
<p class="tent"><i>parameter</i></p>
</th>
</tr>

<tr valign="top">
<th align="center">
<p class="tent"><b>&nbsp;</b></p>
</th>
<th align="center">
<p class="tent"><b>Set and Not Null</b></p>
</th>
<th align="center">
<p class="tent"><b>Set But Null</b></p>
</th>
<th align="center">
<p class="tent"><b>Unset</b></p>
</th>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><b>${</b><i>parameter</i><b>:-</b><i>word</i><b>}</b></p>
</td>
<td align="left">
<p class="tent">substitute <i>parameter</i></p>
</td>
<td align="left">
<p class="tent">substitute <i>word</i></p>
</td>
<td align="left">
<p class="tent">substitute <i>word</i></p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><b>${</b><i>parameter</i><b>-</b><i>word</i><b>}</b></p>
</td>
<td align="left">
<p class="tent">substitute <i>parameter</i></p>
</td>
<td align="left">
<p class="tent">substitute null</p>
</td>
<td align="left">
<p class="tent">substitute <i>word</i></p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><b>${</b><i>parameter</i><b>:=</b><i>word</i><b>}</b></p>
</td>
<td align="left">
<p class="tent">substitute <i>parameter</i></p>
</td>
<td align="left">
<p class="tent">assign <i>word</i></p>
</td>
<td align="left">
<p class="tent">assign <i>word</i></p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><b>${</b><i>parameter</i><b>=</b><i>word</i><b>}</b></p>
</td>
<td align="left">
<p class="tent">substitute <i>parameter</i></p>
</td>
<td align="left">
<p class="tent">substitute null</p>
</td>
<td align="left">
<p class="tent">assign <i>word</i></p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><b>${</b><i>parameter</i><b>:?</b><i>word</i><b>}</b></p>
</td>
<td align="left">
<p class="tent">substitute <i>parameter</i></p>
</td>
<td align="left">
<p class="tent">error, exit</p>
</td>
<td align="left">
<p class="tent">error, exit</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><b>${</b><i>parameter</i><b>?</b><i>word</i><b>}</b></p>
</td>
<td align="left">
<p class="tent">substitute <i>parameter</i></p>
</td>
<td align="left">
<p class="tent">substitute null</p>
</td>
<td align="left">
<p class="tent">error, exit</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><b>${</b><i>parameter</i><b>:+</b><i>word</i><b>}</b></p>
</td>
<td align="left">
<p class="tent">substitute <i>word</i></p>
</td>
<td align="left">
<p class="tent">substitute null</p>
</td>
<td align="left">
<p class="tent">substitute null</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><b>${</b><i>parameter</i><b>+</b><i>word</i><b>}</b></p>
</td>
<td align="left">
<p class="tent">substitute <i>word</i></p>
</td>
<td align="left">
<p class="tent">substitute <i>word</i></p>
</td>
<td align="left">
<p class="tent">substitute null</p>
</td>
</tr>
</table>
</center>

<p>In all cases shown with &quot;substitute&quot;, the expression is replaced with the value shown. In all cases shown with &quot;assign&quot;,
<i>parameter</i> is assigned that value, which also replaces the expression.</p>

<dl compact>
<dt>${#<i>parameter</i>}</dt>

<dd><b>String Length</b>. The length in characters of the value of <i>parameter</i> shall be substituted. If <i>parameter</i> is
<tt>'*'</tt> or <tt>'@'</tt> , the result of the expansion is unspecified.</dd>
</dl>

<p>The following four varieties of parameter expansion provide for substring processing. In each case, pattern matching notation
(see <a href="#tag_02_13">Pattern Matching Notation</a> ), rather than regular expression notation, shall be used to evaluate the
patterns. If <i>parameter</i> is <tt>'*'</tt> or <tt>'@'</tt> , the result of the expansion is unspecified. Enclosing the full
parameter expansion string in double-quotes shall not cause the following four varieties of pattern characters to be quoted,
whereas quoting characters within the braces shall have this effect.</p>

<dl compact>
<dt>${<i>parameter</i>%<i>word</i>}</dt>

<dd><b>Remove Smallest Suffix Pattern</b>. The <i>word</i> shall be expanded to produce a pattern. The parameter expansion shall
then result in <i>parameter</i>, with the smallest portion of the suffix matched by the <i>pattern</i> deleted.</dd>

<dt>${<i>parameter</i>%%<i>word</i>}</dt>

<dd><b>Remove Largest Suffix Pattern</b>. The <i>word</i> shall be expanded to produce a pattern. The parameter expansion shall
then result in <i>parameter</i>, with the largest portion of the suffix matched by the <i>pattern</i> deleted.</dd>

<dt>${<i>parameter</i>#<i>word</i>}</dt>

<dd><b>Remove Smallest Prefix Pattern</b>. The <i>word</i> shall be expanded to produce a pattern. The parameter expansion shall
then result in <i>parameter</i>, with the smallest portion of the prefix matched by the <i>pattern</i> deleted.</dd>

<dt>${<i>parameter</i>##<i>word</i>}</dt>

<dd><b>Remove Largest Prefix Pattern</b>. The <i>word</i> shall be expanded to produce a pattern. The parameter expansion shall
then result in <i>parameter</i>, with the largest portion of the prefix matched by the <i>pattern</i> deleted.</dd>
</dl>

<hr>