AWK variables are dynamic; they come into existence when they are
first used. Their values are either floating-point numbers or
strings, or both, depending upon how they are used.
Additionally, gawk allows variables to have regular-expression
type. AWK also has one dimensional arrays; arrays with multiple
dimensions may be simulated. Gawk provides true arrays of
arrays; see Arrays, below. Several pre-defined variables are set
as a program runs; these are described as needed and summarized
below.
Records
Normally, records are separated by newline characters. You can
control how records are separated by assigning values to the
built-in variable RS. If RS is any single character, that
character separates records. Otherwise, RS is a regular
expression. Text in the input that matches this regular
expression separates the record. However, in compatibility mode,
only the first character of its string value is used for
separating records. If RS is set to the null string, then
records are separated by empty lines. When RS is set to the null
string, the newline character always acts as a field separator,
in addition to whatever value FS may have.
Fields
As each input record is read, gawk splits the record into fields,
using the value of the FS variable as the field separator. If FS
is a single character, fields are separated by that character.
If FS is the null string, then each individual character becomes
a separate field. Otherwise, FS is expected to be a full regular
expression. In the special case that FS is a single space,
fields are separated by runs of spaces and/or tabs and/or
newlines. NOTE: The value of IGNORECASE (see below) also affects
how fields are split when FS is a regular expression, and how
records are separated when RS is a regular expression.
If the FIELDWIDTHS variable is set to a space-separated list of
numbers, each field is expected to have fixed width, and gawk
splits up the record using the specified widths. Each field
width may optionally be preceded by a colon-separated value
specifying the number of characters to skip before the field
starts. The value of FS is ignored. Assigning a new value to FS
or FPAT overrides the use of FIELDWIDTHS.
Similarly, if the FPAT variable is set to a string representing a
regular expression, each field is made up of text that matches
that regular expression. In this case, the regular expression
describes the fields themselves, instead of the text that
separates the fields. Assigning a new value to FS or FIELDWIDTHS
overrides the use of FPAT.
Each field in the input record may be referenced by its position:
$1, $2, and so on. $0 is the whole record, including leading and
trailing whitespace. Fields need not be referenced by constants:
n = 5
print $n
prints the fifth field in the input record.
The variable NF is set to the total number of fields in the input
record.
References to non-existent fields (i.e., fields after $NF)
produce the null string. However, assigning to a non-existent
field (e.g., $(NF+2) = 5) increases the value of NF, creates any
intervening fields with the null string as their values, and
causes the value of $0 to be recomputed, with the fields being
separated by the value of OFS. References to negative numbered
fields cause a fatal error. Decrementing NF causes the values of
fields past the new value to be lost, and the value of $0 to be
recomputed, with the fields being separated by the value of OFS.
Assigning a value to an existing field causes the whole record to
be rebuilt when $0 is referenced. Similarly, assigning a value
to $0 causes the record to be resplit, creating new values for
the fields.
Built-in Variables
Gawk's built-in variables are:
ARGC The number of command line arguments (does not include
options to gawk, or the program source).
ARGIND The index in ARGV of the current file being processed.
ARGV Array of command line arguments. The array is indexed
from 0 to ARGC - 1. Dynamically changing the contents of
ARGV can control the files used for data.
BINMODE
On non-POSIX systems, specifies use of 'binary' mode for
all file I/O. Numeric values of 1, 2, or 3, specify that
input files, output files, or all files, respectively,
should use binary I/O. String values of "r", or "w"
specify that input files, or output files, respectively,
should use binary I/O. String values of "rw" or "wr"
specify that all files should use binary I/O. Any other
string value is treated as "rw", but generates a warning
message.
CONVFMT
The conversion format for numbers, "%.6g", by default.
ENVIRON
An array containing the values of the current environment.
The array is indexed by the environment variables, each
element being the value of that variable (e.g.,
ENVIRON["HOME"] might be "/home/arnold").
In POSIX mode, changing this array does not affect the
environment seen by programs which gawk spawns via
redirection or the system() function. Otherwise, gawk
updates its real environment so that programs it spawns
see the changes.
ERRNO If a system error occurs either doing a redirection for
getline, during a read for getline, or during a close(),
then ERRNO is set to a string describing the error. The
value is subject to translation in non-English locales.
If the string in ERRNO corresponds to a system error in
the errno(3) variable, then the numeric value can be found
in PROCINFO["errno"]. For non-system errors,
PROCINFO["errno"] will be zero.
FIELDWIDTHS
A whitespace-separated list of field widths. When set,
gawk parses the input into fields of fixed width, instead
of using the value of the FS variable as the field
separator. Each field width may optionally be preceded by
a colon-separated value specifying the number of
characters to skip before the field starts. See Fields,
above.
FILENAME
The name of the current input file. If no files are
specified on the command line, the value of FILENAME is
'-'. However, FILENAME is undefined inside the BEGIN rule
(unless set by getline).
FNR The input record number in the current input file.
FPAT A regular expression describing the contents of the fields
in a record. When set, gawk parses the input into fields,
where the fields match the regular expression, instead of
using the value of FS as the field separator. See Fields,
above.
FS The input field separator, a space by default. See
Fields, above.
FUNCTAB
An array whose indices and corresponding values are the
names of all the user-defined or extension functions in
the program. NOTE: You may not use the delete statement
with the FUNCTAB array.
IGNORECASE
Controls the case-sensitivity of all regular expression
and string operations. If IGNORECASE has a non-zero
value, then string comparisons and pattern matching in
rules, field splitting with FS and FPAT, record separating
with RS, regular expression matching with ~ and !~, and
the gensub(), gsub(), index(), match(), patsplit(),
split(), and sub() built-in functions all ignore case when
doing regular expression operations. NOTE: Array
subscripting is not affected. However, the asort() and
asorti() functions are affected.
Thus, if IGNORECASE is not equal to zero, /aB/ matches all
of the strings "ab", "aB", "Ab", and "AB". As with all
AWK variables, the initial value of IGNORECASE is zero, so
all regular expression and string operations are normally
case-sensitive.
LINT Provides dynamic control of the --lint option from within
an AWK program. When true, gawk prints lint warnings.
When false, it does not. The values allowed for the
--lint option may also be assigned to LINT, with the same
effects. Any other true value just prints warnings.
NF The number of fields in the current input record.
NR The total number of input records seen so far.
OFMT The output format for numbers, "%.6g", by default.
OFS The output field separator, a space by default.
ORS The output record separator, by default a newline.
PREC The working precision of arbitrary precision floating-
point numbers, 53 by default.
PROCINFO
The elements of this array provide access to information
about the running AWK program. On some systems, there may
be elements in the array, "group1" through "groupn" for
some n, which is the number of supplementary groups that
the process has. Use the in operator to test for these
elements. The following elements are guaranteed to be
available:
PROCINFO["argv"]
The command line arguments as received by gawk at
the C-language level. The subscripts start from
zero.
PROCINFO["egid"]
The value of the getegid(2) system call.
PROCINFO["errno"]
The value of errno(3) when ERRNO is set to the
associated error message.
PROCINFO["euid"]
The value of the geteuid(2) system call.
PROCINFO["FS"]
"FS" if field splitting with FS is in effect,
"FPAT" if field splitting with FPAT is in effect,
"FIELDWIDTHS" if field splitting with FIELDWIDTHS
is in effect, or "API" if API input parser field
splitting is in effect.
PROCINFO["gid"]
The value of the getgid(2) system call.
PROCINFO["identifiers"]
A subarray, indexed by the names of all identifiers
used in the text of the AWK program. The values
indicate what gawk knows about the identifiers
after it has finished parsing the program; they are
not updated while the program runs. For each
identifier, the value of the element is one of the
following:
"array"
The identifier is an array.
"builtin"
The identifier is a built-in function.
"extension"
The identifier is an extension function
loaded via @load or --load.
"scalar"
The identifier is a scalar.
"untyped"
The identifier is untyped (could be used as
a scalar or array, gawk doesn't know yet).
"user" The identifier is a user-defined function.
PROCINFO["pgrpid"]
The value of the getpgrp(2) system call.
PROCINFO["pid"]
The value of the getpid(2) system call.
PROCINFO["platform"]
A string indicating the platform for which gawk was
compiled. It is one of:
"djgpp", "mingw"
Microsoft Windows, using either DJGPP, or
MinGW, respectively.
"os2" OS/2.
"posix"
GNU/Linux, Cygwin, Mac OS X, and legacy Unix
systems.
"vms" OpenVMS or Vax/VMS.
PROCINFO["ppid"]
The value of the getppid(2) system call.
PROCINFO["strftime"]
The default time format string for strftime().
Changing its value affects how strftime() formats
time values when called with no arguments.
PROCINFO["uid"]
The value of the getuid(2) system call.
PROCINFO["version"]
The version of gawk.
The following elements are present if loading dynamic
extensions is available:
PROCINFO["api_major"]
The major version of the extension API.
PROCINFO["api_minor"]
The minor version of the extension API.
The following elements are available if MPFR support is
compiled into gawk:
PROCINFO["gmp_version"]
The version of the GNU GMP library used for
arbitrary precision number support in gawk.
PROCINFO["mpfr_version"]
The version of the GNU MPFR library used for
arbitrary precision number support in gawk.
PROCINFO["prec_max"]
The maximum precision supported by the GNU MPFR
library for arbitrary precision floating-point
numbers.
PROCINFO["prec_min"]
The minimum precision allowed by the GNU MPFR
library for arbitrary precision floating-point
numbers.
The following elements may set by a program to change
gawk's behavior:
PROCINFO["NONFATAL"]
If this exists, then I/O errors for all
redirections become nonfatal.
PROCINFO["name", "NONFATAL"]
Make I/O errors for name be nonfatal.
PROCINFO["command", "pty"]
Use a pseudo-tty for two-way communication with
command instead of setting up two one-way pipes.
PROCINFO["input", "READ_TIMEOUT"]
The timeout in milliseconds for reading data from
input, where input is a redirection string or a
filename. A value of zero or less than zero means
no timeout.
PROCINFO["input", "RETRY"]
If an I/O error that may be retried occurs when
reading data from input, and this array entry
exists, then getline returns -2 instead of
following the default behavior of returning -1 and
configuring input to return no further data. An
I/O error that may be retried is one where errno(3)
has the value EAGAIN, EWOULDBLOCK, EINTR, or
ETIMEDOUT. This may be useful in conjunction with
PROCINFO["input", "READ_TIMEOUT"] or in situations
where a file descriptor has been configured to
behave in a non-blocking fashion.
PROCINFO["sorted_in"]
If this element exists in PROCINFO, then its value
controls the order in which array elements are
traversed in for loops. Supported values are
"@ind_str_asc", "@ind_num_asc", "@val_type_asc",
"@val_str_asc", "@val_num_asc", "@ind_str_desc",
"@ind_num_desc", "@val_type_desc", "@val_str_desc",
"@val_num_desc", and "@unsorted". The value can
also be the name (as a string) of any comparison
function defined as follows:
function cmp_func(i1, v1, i2, v2)
where i1 and i2 are the indices, and v1 and v2 are
the corresponding values of the two elements being
compared. It should return a number less than,
equal to, or greater than 0, depending on how the
elements of the array are to be ordered.
ROUNDMODE
The rounding mode to use for arbitrary precision
arithmetic on numbers, by default "N" (IEEE-754
roundTiesToEven mode). The accepted values are:
"A" or "a"
for rounding away from zero. These are only
available if your version of the GNU MPFR library
supports rounding away from zero.
"D" or "d"
for roundTowardNegative.
"N" or "n"
for roundTiesToEven.
"U" or "u"
for roundTowardPositive.
"Z" or "z"
for roundTowardZero.
RS The input record separator, by default a newline.
RT The record terminator. Gawk sets RT to the input text
that matched the character or regular expression specified
by RS.
RSTART The index of the first character matched by match(); 0 if
no match. (This implies that character indices start at
one.)
RLENGTH
The length of the string matched by match(); -1 if no
match.
SUBSEP The string used to separate multiple subscripts in array
elements, by default "\034".
SYMTAB An array whose indices are the names of all currently
defined global variables and arrays in the program. The
array may be used for indirect access to read or write the
value of a variable:
foo = 5
SYMTAB["foo"] = 4
print foo # prints 4
The typeof() function may be used to test if an element in
SYMTAB is an array. You may not use the delete statement
with the SYMTAB array, nor assign to elements with an
index that is not a variable name.
TEXTDOMAIN
The text domain of the AWK program; used to find the
localized translations for the program's strings.
Arrays
Arrays are subscripted with an expression between square brackets
([ and ]). If the expression is an expression list (expr, expr
...) then the array subscript is a string consisting of the
concatenation of the (string) value of each expression, separated
by the value of the SUBSEP variable. This facility is used to
simulate multiply dimensioned arrays. For example:
i = "A"; j = "B"; k = "C"
x[i, j, k] = "hello, world\n"
assigns the string "hello, world\n" to the element of the array x
which is indexed by the string "A\034B\034C". All arrays in AWK
are associative, i.e., indexed by string values.
The special operator in may be used to test if an array has an
index consisting of a particular value:
if (val in array)
print array[val]
If the array has multiple subscripts, use (i, j) in array.
The in construct may also be used in a for loop to iterate over
all the elements of an array. However, the (i, j) in array
construct only works in tests, not in for loops.
An element may be deleted from an array using the delete
statement. The delete statement may also be used to delete the
entire contents of an array, just by specifying the array name
without a subscript.
gawk supports true multidimensional arrays. It does not require
that such arrays be ``rectangular'' as in C or C++. For example:
a[1] = 5
a[2][1] = 6
a[2][2] = 7
NOTE: You may need to tell gawk that an array element is really a
subarray in order to use it where gawk expects an array (such as
in the second argument to split()). You can do this by creating
an element in the subarray and then deleting it with the delete
statement.
Namespaces
Gawk provides a simple namespace facility to help work around the
fact that all variables in AWK are global.
A qualified name consists of a two simple identifiers joined by a
double colon (::). The left-hand identifier represents the
namespace and the right-hand identifier is the variable within
it. All simple (non-qualified) names are considered to be in the
``current'' namespace; the default namespace is awk. However,
simple identifiers consisting solely of uppercase letters are
forced into the awk namespace, even if the current namespace is
different.
You change the current namespace with an @namespace "name"
directive.
The standard predefined builtin function names may not be used as
namespace names. The names of additional functions provided by
gawk may be used as namespace names or as simple identifiers in
other namespaces. For more details, see GAWK: Effective AWK
Programming.
Variable Typing And Conversion
Variables and fields may be (floating point) numbers, or strings,
or both. They may also be regular expressions. How the value of
a variable is interpreted depends upon its context. If used in a
numeric expression, it will be treated as a number; if used as a
string it will be treated as a string.
To force a variable to be treated as a number, add zero to it; to
force it to be treated as a string, concatenate it with the null
string.
Uninitialized variables have the numeric value zero and the
string value "" (the null, or empty, string).
When a string must be converted to a number, the conversion is
accomplished using strtod(3). A number is converted to a string
by using the value of CONVFMT as a format string for sprintf(3),
with the numeric value of the variable as the argument. However,
even though all numbers in AWK are floating-point, integral
values are always converted as integers. Thus, given
CONVFMT = "%2.2f"
a = 12
b = a ""
the variable b has a string value of "12" and not "12.00".
NOTE: When operating in POSIX mode (such as with the --posix
option), beware that locale settings may interfere with the way
decimal numbers are treated: the decimal separator of the numbers
you are feeding to gawk must conform to what your locale would
expect, be it a comma (,) or a period (.).
Gawk performs comparisons as follows: If two variables are
numeric, they are compared numerically. If one value is numeric
and the other has a string value that is a 'numeric string,' then
comparisons are also done numerically. Otherwise, the numeric
value is converted to a string and a string comparison is
performed. Two strings are compared, of course, as strings.
Note that string constants, such as "57", are not numeric
strings, they are string constants. The idea of 'numeric string'
only applies to fields, getline input, FILENAME, ARGV elements,
ENVIRON elements and the elements of an array created by split()
or patsplit() that are numeric strings. The basic idea is that
user input, and only user input, that looks numeric, should be
treated that way.
Octal and Hexadecimal Constants
You may use C-style octal and hexadecimal constants in your AWK
program source code. For example, the octal value 011 is equal
to decimal 9, and the hexadecimal value 0x11 is equal to decimal
17.
String Constants
String constants in AWK are sequences of characters enclosed
between double quotes (like "value"). Within strings, certain
escape sequences are recognized, as in C. These are:
\\ A literal backslash.
\a The 'alert' character; usually the ASCII BEL character.
\b Backspace.
\f Form-feed.
\n Newline.
\r Carriage return.
\t Horizontal tab.
\v Vertical tab.
\xhex digits
The character represented by the string of hexadecimal
digits following the \x. Up to two following hexadecimal
digits are considered part of the escape sequence. E.g.,
"\x1B" is the ASCII ESC (escape) character.
\ddd The character represented by the 1-, 2-, or 3-digit
sequence of octal digits. E.g., "\033" is the ASCII ESC
(escape) character.
\c The literal character c.
In compatibility mode, the characters represented by octal and
hexadecimal escape sequences are treated literally when used in
regular expression constants. Thus, /a\52b/ is equivalent to
/a\*b/.
Regexp Constants
A regular expression constant is a sequence of characters
enclosed between forward slashes (like /value/). Regular
expression matching is described more fully below; see Regular
Expressions.
The escape sequences described earlier may also be used inside
constant regular expressions (e.g., /[ \t\f\n\r\v]/ matches
whitespace characters).
Gawk provides strongly typed regular expression constants. These
are written with a leading @ symbol (like so: @/value/). Such
constants may be assigned to scalars (variables, array elements)
and passed to user-defined functions. Variables that have been so
assigned have regular expression type.
