awk.html

IEEE 1003.1-2003, Single Unix Specification v3

</tt>
</pre>

<p>except that lvalue shall be evaluated only once. The value of the expression:</p>

<pre>
<i>expr1</i> <tt>%</tt> <i>expr2</i>
</pre>

<p>shall be equivalent to the value returned by the ISO&nbsp;C standard function call:</p>

<pre>
<tt>fmod(</tt><i>expr1</i><tt>,</tt> <i>expr2</i><tt>)
</tt>
</pre>

<p>The expression:</p>

<pre>
<tt>lvalue %=</tt> <i>expr</i>
</pre>

<p>shall be equivalent to the ISO&nbsp;C standard expression:</p>

<pre>
<tt>lvalue = fmod(lvalue,</tt> <i>expr</i><tt>)
</tt>
</pre>

<p>except that lvalue shall be evaluated only once.</p>

<p>Variables and fields shall be set by the assignment statement:</p>

<pre>
<tt>lvalue =</tt> <i>expression</i>
</pre>

<p>and the type of <i>expression</i> shall determine the resulting variable type. The assignment includes the arithmetic
assignments ( <tt>"+="</tt> , <tt>"-="</tt> , <tt>"*="</tt> , <tt>"/="</tt> , <tt>"%="</tt> , <tt>"^="</tt> , <tt>"++"</tt> ,
<tt>"--"</tt> ) all of which shall produce a numeric result. The left-hand side of an assignment and the target of increment and
decrement operators can be one of a variable, an array with index, or a field selector.</p>

<p>The <i>awk</i> language supplies arrays that are used for storing numbers or strings. Arrays need not be declared. They shall
initially be empty, and their sizes shall change dynamically. The subscripts, or element identifiers, are strings, providing a type
of associative array capability. An array name followed by a subscript within square brackets can be used as an lvalue and thus as
an expression, as described in the grammar; see <a href="#tag_04_06_13_16">Grammar</a> . Unsubscripted array names can be used in
only the following contexts:</p>

<ul>
<li>
<p>A parameter in a function definition or function call</p>
</li>

<li>
<p>The <b>NAME</b> token following any use of the keyword <b>in</b> as specified in the grammar (see <a href=
"#tag_04_06_13_16">Grammar</a> ); if the name used in this context is not an array name, the behavior is undefined</p>
</li>
</ul>

<p>A valid array <i>index</i> shall consist of one or more comma-separated expressions, similar to the way in which
multi-dimensional arrays are indexed in some programming languages. Because <i>awk</i> arrays are really one-dimensional, such a
comma-separated list shall be converted to a single string by concatenating the string values of the separate expressions, each
separated from the other by the value of the <b>SUBSEP</b> variable. Thus, the following two index operations shall be
equivalent:</p>

<pre>
<i>var</i><b>[</b><i>expr1</i><tt>,</tt> <i>expr2</i><tt>, ...</tt> <i>exprn</i><b>]
<br>
</b><i>var</i><b>[</b><i>expr1</i> <tt>SUBSEP</tt> <i>expr2</i> <tt>SUBSEP ... SUBSEP</tt> <i>exprn</i><b>]</b>
</pre>

<p>The application shall ensure that a multi-dimensioned <i>index</i> used with the <b>in</b> operator is parenthesized. The
<b>in</b> operator, which tests for the existence of a particular array element, shall not cause that element to exist. Any other
reference to a nonexistent array element shall automatically create it.</p>

<p>Comparisons (with the <tt>'&lt;'</tt> , <tt>"&lt;="</tt> , <tt>"!="</tt> , <tt>"=="</tt> , <tt>'&gt;'</tt> , and
<tt>"&gt;="</tt> operators) shall be made numerically if both operands are numeric, if one is numeric and the other has a string
value that is a numeric string, or if one is numeric and the other has the uninitialized value. Otherwise, operands shall be
converted to strings as required and a string comparison shall be made using the locale-specific collation sequence. The value of
the comparison expression shall be 1 if the relation is true, or 0 if the relation is false.</p>

<h5><a name="tag_04_06_13_03"></a>Variables and Special Variables</h5>

<p>Variables can be used in an <i>awk</i> program by referencing them. With the exception of function parameters (see <a href=
"#tag_04_06_13_15">User-Defined Functions</a> ), they are not explicitly declared. Function parameter names shall be local to the
function; all other variable names shall be global. The same name shall not be used as both a function parameter name and as the
name of a function or a special <i>awk</i> variable. The same name shall not be used both as a variable name with global scope and
as the name of a function. The same name shall not be used within the same scope both as a scalar variable and as an array.
Uninitialized variables, including scalar variables, array elements, and field variables, shall have an uninitialized value. An
uninitialized value shall have both a numeric value of zero and a string value of the empty string. Evaluation of variables with an
uninitialized value, to either string or numeric, shall be determined by the context in which they are used.</p>

<p>Field variables shall be designated by a <tt>'$'</tt> followed by a number or numerical expression. The effect of the field
number <i>expression</i> evaluating to anything other than a non-negative integer is unspecified; uninitialized variables or string
values need not be converted to numeric values in this context. New field variables can be created by assigning a value to them.
References to nonexistent fields (that is, fields after $<b>NF</b>), shall evaluate to the uninitialized value. Such references
shall not create new fields. However, assigning to a nonexistent field (for example, $(<b>NF</b>+2)=5) shall increase the value of
<b>NF</b>; create any intervening fields with the uninitialized value; and cause the value of $0 to be recomputed, with the fields
being separated by the value of <b>OFS</b>. Each field variable shall have a string value or an uninitialized value when created.
Field variables shall have the uninitialized value when created from $0 using <b>FS</b> and the variable does not contain any
characters. If appropriate, the field variable shall be considered a numeric string (see <a href="#tag_04_06_13_02">Expressions in
awk</a> ).</p>

<p>Implementations shall support the following other special variables that are set by <i>awk</i>:</p>

<dl compact>
<dt><b>ARGC</b></dt>

<dd>The number of elements in the <b>ARGV</b> array.</dd>

<dt><b>ARGV</b></dt>

<dd>An array of command line arguments, excluding options and the <i>program</i> argument, numbered from zero to <b>ARGC</b>-1. 

<p>The arguments in <b>ARGV</b> can be modified or added to; <b>ARGC</b> can be altered. As each input file ends, <i>awk</i> shall
treat the next non-null element of <b>ARGV</b>, up to the current value of <b>ARGC</b>-1, inclusive, as the name of the next input
file. Thus, setting an element of <b>ARGV</b> to null means that it shall not be treated as an input file. The name <tt>'-'</tt>
indicates the standard input. If an argument matches the format of an <i>assignment</i> operand, this argument shall be treated as
an <i>assignment</i> rather than a <i>file</i> argument.</p>
</dd>

<dt><b>CONVFMT</b></dt>

<dd>The <b>printf</b> format for converting numbers to strings (except for output statements, where <b>OFMT</b> is used);
<tt>"%.6g"</tt> by default.</dd>

<dt><b>ENVIRON</b></dt>

<dd>An array representing the value of the environment, as described in the <i>exec</i> functions defined in the System Interfaces
volume of IEEE&nbsp;Std&nbsp;1003.1-2001. The indices of the array shall be strings consisting of the names of the environment
variables, and the value of each array element shall be a string consisting of the value of that variable. If appropriate, the
environment variable shall be considered a <i>numeric string</i> (see <a href="#tag_04_06_13_02">Expressions in awk</a> ); the
array element shall also have its numeric value. 

<p>In all cases where the behavior of <i>awk</i> is affected by environment variables (including the environment of any commands
that <i>awk</i> executes via the <b>system</b> function or via pipeline redirections with the <b>print</b> statement, the
<b>printf</b> statement, or the <b>getline</b> function), the environment used shall be the environment at the time <i>awk</i>
began executing; it is implementation-defined whether any modification of <b>ENVIRON</b> affects this environment.</p>
</dd>

<dt><b>FILENAME</b></dt>

<dd>A pathname of the current input file. Inside a <b>BEGIN</b> action the value is undefined. Inside an <b>END</b> action the
value shall be the name of the last input file processed.</dd>

<dt><b>FNR</b></dt>

<dd>The ordinal number of the current record in the current file. Inside a <b>BEGIN</b> action the value shall be zero. Inside an
<b>END</b> action the value shall be the number of the last record processed in the last file processed.</dd>

<dt><b>FS</b></dt>

<dd>Input field separator regular expression; a &lt;space&gt; by default.</dd>

<dt><b>NF</b></dt>

<dd>The number of fields in the current record. Inside a <b>BEGIN</b> action, the use of <b>NF</b> is undefined unless a
<b>getline</b> function without a <i>var</i> argument is executed previously. Inside an <b>END</b> action, <b>NF</b> shall retain
the value it had for the last record read, unless a subsequent, redirected, <b>getline</b> function without a <i>var</i> argument
is performed prior to entering the <b>END</b> action.</dd>

<dt><b>NR</b></dt>

<dd>The ordinal number of the current record from the start of input. Inside a <b>BEGIN</b> action the value shall be zero. Inside
an <b>END</b> action the value shall be the number of the last record processed.</dd>

<dt><b>OFMT</b></dt>

<dd>The <b>printf</b> format for converting numbers to strings in output statements (see <a href="#tag_04_06_13_10">Output
Statements</a> ); <tt>"%.6g"</tt> by default. The result of the conversion is unspecified if the value of <b>OFMT</b> is not a
floating-point format specification.</dd>

<dt><b>OFS</b></dt>

<dd>The <b>print</b> statement output field separation; &lt;space&gt; by default.</dd>

<dt><b>ORS</b></dt>

<dd>The <b>print</b> statement output record separator; a &lt;newline&gt; by default.</dd>

<dt><b>RLENGTH</b></dt>

<dd>The length of the string matched by the <b>match</b> function.</dd>

<dt><b>RS</b></dt>

<dd>The first character of the string value of <b>RS</b> shall be the input record separator; a &lt;newline&gt; by default. If
<b>RS</b> contains more than one character, the results are unspecified. If <b>RS</b> is null, then records are separated by
sequences consisting of a &lt;newline&gt; plus one or more blank lines, leading or trailing blank lines shall not result in empty
records at the beginning or end of the input, and a &lt;newline&gt; shall always be a field separator, no matter what the value of
<b>FS</b> is.</dd>

<dt><b>RSTART</b></dt>

<dd>The starting position of the string matched by the <b>match</b> function, numbering from 1. This shall always be equivalent to
the return value of the <b>match</b> function.</dd>

<dt><b>SUBSEP</b></dt>

<dd>The subscript separator string for multi-dimensional arrays; the default value is implementation-defined.</dd>
</dl>

<h5><a name="tag_04_06_13_04"></a>Regular Expressions</h5>

<p>The <i>awk</i> utility shall make use of the extended regular expression notation (see the Base Definitions volume of
IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../basedefs/xbd_chap09.html#tag_09_04">Section 9.4, Extended Regular Expressions</a>)
except that it shall allow the use of C-language conventions for escaping special characters within the EREs, as specified in the
table in the Base Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../basedefs/xbd_chap05.html">Chapter 5, File
Format Notation</a> ( <tt>'\\'</tt> , <tt>'\a'</tt> , <tt>'\b'</tt> , <tt>'\f'</tt> , <tt>'\n'</tt> , <tt>'\r'</tt> , <tt>'\t'</tt>
, <tt>'\v'</tt> ) and the following table; these escape sequences shall be recognized both inside and outside bracket expressions.
Note that records need not be separated by &lt;newline&gt;s and string constants can contain &lt;newline&gt;s, so even the
<tt>"\n"</tt> sequence is valid in <i>awk</i> EREs. Using a slash character within an ERE requires the escaping shown in the
following table.<br>
</p>

<center><b>Table: Escape Sequences in <i>awk</i></b></center>

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

<tr valign="top">
<th align="center">
<p class="tent"><b>Sequence</b></p>
</th>
<th align="center">
<p class="tent"><b>Description</b></p>
</th>
<th align="center">
<p class="tent"><b>Meaning</b></p>
</th>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">\"</p>
</td>
<td align="left">
<p class="tent">Backslash quotation-mark</p>
</td>
<td align="left">
<p class="tent">Quotation-mark character</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">\/</p>
</td>
<td align="left">
<p class="tent">Backslash slash</p>
</td>
<td align="left">
<p class="tent">Slash character</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">\ddd</p>
</td>
<td align="left">
<p class="tent">A backslash character followed by the longest sequence of one, two, or three octal-digit characters (01234567). If
all of the digits are 0 (that is, representation of the NUL character), the behavior is undefined.</p>
</td>
<td align="left">
<p class="tent">The character whose encoding is represented by the one, two, or three-digit octal integer. Multi-byte characters
require multiple, concatenated escape sequences of this type, including the leading <tt>'\'</tt> for each byte.</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">\c</p>
</td>
<td align="left">
<p class="tent">A backslash character followed by any character not described in this table or in the table in the Base Definitions
volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../basedefs/xbd_chap05.html">Chapter 5, File Format Notation</a> ( <tt>'\\'</tt>
, <tt>'\a'</tt> , <tt>'\b'</tt> , <tt>'\f'</tt> , <tt>'\n'</tt> , <tt>'\r'</tt> , <tt>'\t'</tt> , <tt>'\v'</tt> ).</p>
</td>
<td align="left">
<p class="tent">Undefined</p>
</td>
</tr>
</table>
</center>

<p>A regular expression can be matched against a specific field or string by using one of the two regular expression matching
operators, <tt>'&#152;'</tt> and <tt>"!&#152;"</tt> . These operators shall interpret their right-hand operand as a regular
expression and their left-hand operand as a string. If the regular expression matches the string, the <tt>'&#152;'</tt> expression
shall evaluate to a value of 1, and the <tt>"!&#152;"</tt> expression shall evaluate to a value of 0. (The regular expression
matching operation is as defined by the term matched in the Base Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href=
"../basedefs/xbd_chap09.html#tag_09_01">Section 9.1, Regular Expression Definitions</a>, where a match occurs on any part of the
string unless the regular expression is limited with the circumflex or dollar sign special characters.) If the regular expression
does not match the string, the <tt>'&#152;'</tt> expression shall evaluate to a value of 0, and the <tt>"!&#152;"</tt> expression
shall evaluate to a value of 1. If the right-hand operand is any expression other than the lexical token <b>ERE</b>, the string
value of the expression shall be interpreted as an extended regular expression, including the escape conventions described above.
Note that these same escape conventions shall also be applied in determining the value of a string literal (the lexical token
<b>STRING</b>), and thus shall be applied a second time when a string literal is used in this context.</p>

<p>When an <b>ERE</b> token appears as an expression in any context other than as the right-hand of the <tt>'&#152;'</tt> or
<tt>"!&#152;"</tt> operator or as one of the built-in function arguments described below, the value of the resulting expression
shall be the equivalent of:</p>

<pre>
<tt>$0 &#152; /</tt><i>ere</i><tt>/
</tt>
</pre>

<p>The <i>ere</i> argument to the <b>gsub</b>, <b>match</b>, <b>sub</b> functions, and the <i>fs</i> argument to the <b>split</b>
function (see <a href="#tag_04_06_13_13">String Functions</a> ) shall be interpreted as extended regular expressions. These can be
either <b>ERE</b> tokens or arbitrary expressions, and shall be interpreted in the same manner as the right-hand side of the
<tt>'&#152;'</tt> or <tt>"!&#152;"</tt> operator.</p>

<p>An extended regular expression can be used to separate fields by using the <b>-F</b> <i>ERE</i> option or by assigning a string
containing the expression to the built-in variable <b>FS</b>. The default value of the <b>FS</b> variable shall be a single
&lt;space&gt;. The following describes <b>FS</b> behavior:</p>

<ol>
<li>
<p>If <b>FS</b> is a null string, the behavior is unspecified.</p>
</li>

<li>
<p>If <b>FS</b> is a single character:</p>