Go to the first, previous, next, last section, table of contents.

# `gawk` Summary

This appendix provides a brief summary of the `gawk` command line and the `awk` language. It is designed to serve as "quick reference." It is therefore terse, but complete.

- Command Line Summary: Recapitulation of the command line.
- Language Summary: A terse review of the language.
- Variables/Fields: Variables, fields, and arrays.
- Rules Summary: Patterns and Actions, and their component parts.
- Actions Summary: Quick overview of actions.
- Functions Summary: Defining and calling functions.
- Historical Features: Some undocumented but supported "features".

## Command Line Options Summary

The command line consists of options to `gawk` itself, the `awk` program text (if not supplied via the ``-f'` option), and values to be made available in the `ARGC` and `ARGV` predefined `awk` variables:

    gawk [POSIX or GNU style options] -f source-file [--] file ...
    gawk [POSIX or GNU style options] [--] 'program' file ...

The options that `gawk` accepts are:

`-F fs`
`--field-separator fs`
  Use fs for the input field separator (the value of the `FS` predefined variable).
`-f program-file`
`--file program-file`
  Read the `awk` program source from the file program-file, instead of from the first command line argument.
`-mf NNN`
`-mr NNN`
  The ``f'` flag sets the maximum number of fields, and the ``r'` flag sets the maximum record size. These options are ignored by `gawk`, since `gawk` has no predefined limits; they are only for compatibility with the Bell Labs research version of Unix `awk`.
`-v var=val`
`--assign var=val`
  Assign the variable var the value val before program execution begins.
`-W traditional`
`-W compat`
`--traditional`
`--compat`
  Use compatibility mode, in which `gawk` extensions are turned off.
`-W copyleft`
`-W copyright`
`--copyleft`
`--copyright`
  Print the short version of the General Public License on the standard output, and exit. This option may disappear in a future version of `gawk`.
`-W help`
`-W usage`
`--help`
`--usage`
  Print a relatively short summary of the available options on the standard output, and exit.
`-W lint`
`--lint`
  Give warnings about dubious or non-portable `awk` constructs.
`-W lint-old`
`--lint-old`
  Warn about constructs that are not available in the original Version 7 Unix version of `awk`.
`-W posix`
`--posix`
  Use POSIX compatibility mode, in which `gawk` extensions are turned off and additional restrictions apply.
`-W re-interval`
`--re-interval`
  Allow interval expressions (see section Regular Expression Operators), in regexps.
`-W source=program-text`
`--source program-text`
  Use program-text as `awk` program source code. This option allows mixing command line source code with source code from files, and is particularly useful for mixing command line programs with library functions.
`-W version`
`--version`
  Print version information for this particular copy of `gawk` on the error output.
`--`
  Signal the end of options. This is useful to allow further arguments to the `awk` program itself to start with a ``-'`. This is mainly for consistency with POSIX argument parsing conventions.

Any other options are flagged as invalid, but are otherwise ignored. See section Command Line Options, for more details.

## Language Summary

An `awk` program consists of a sequence of zero or more pattern-action statements and optional function definitions. One or the other of the pattern and action may be omitted.

    pattern    { action statements }
    pattern
              { action statements }

    function name(parameter list)     { action statements }

`gawk` first reads the program source from the program-file(s), if specified, or from the first non-option argument on the command line. The ``-f'` option may be used multiple times on the command line. `gawk` reads the program text from all the program-file files, effectively concatenating them in the order they are specified. This is useful for building libraries of `awk` functions, without having to include them in each new `awk` program that uses them. To use a library function in a file from a program typed in on the command line, specify ``--source 'program''`, and type your program in between the single quotes. See section Command Line Options.

The environment variable `AWKPATH` specifies a search path to use when finding source files named with the ``-f'` option. The default path, which is ``.:/usr/local/share/awk'`(27) is used if `AWKPATH` is not set. If a file name given to the ``-f'` option contains a ``/'` character, no path search is performed. See section The `AWKPATH` Environment Variable.

`gawk` compiles the program into an internal form, and then proceeds to read each file named in the `ARGV` array. The initial values of `ARGV` come from the command line arguments. If there are no files named on the command line, `gawk` reads the standard input.

If a "file" named on the command line has the form ``var=val'`, it is treated as a variable assignment: the variable var is assigned the value val. If any of the files have a value that is the null string, that element in the list is skipped.

For each record in the input, `gawk` tests to see if it matches any pattern in the `awk` program. For each pattern that the record matches, the associated action is executed.

## Variables and Fields

`awk` variables are not declared; they come into existence when they are first used. Their values are either floating-point numbers or strings. `awk` also has one-dimensional arrays; multiple-dimensional arrays may be simulated. There are several predefined variables that `awk` sets as a program runs; these are summarized below.

- Fields Summary: Input field splitting.
- Built-in Summary: `awk`'s built-in variables.
- Arrays Summary: Using arrays.
- Data Type Summary: Values in `awk` are numbers or strings.

### Fields

As each input line is read, `gawk` splits the line 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. 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, tabs and/or newlines.(28) If `FS` is the null string (`""`), then each individual character in the record becomes a separate field. Note that the value of `IGNORECASE` (see section Case-sensitivity in Matching) also affects how fields are split when `FS` is a regular expression.

Each field in the input line may be referenced by its position, `$1`, `$2`, and so on. `$0` is the whole line. The value of a field may be assigned to as well. Field numbers need not be constants:

    n = 5
    print $n

prints the fifth field in the input line. The variable `NF` is set to the total number of fields in the input line.

References to non-existent fields (i.e. fields after `$NF`) return 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 value, and causes the value of `$0` to be recomputed, with the fields being separated by the value of `OFS`. 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`. See section Reading Input Files.

### Built-in Variables

`gawk`'s built-in variables are:

`ARGC`
  The number of elements in `ARGV`. See below for what is actually included in `ARGV`.
`ARGIND`
  The index in `ARGV` of the current file being processed. When `gawk` is processing the input data files, it is always true that ``FILENAME == ARGV[ARGIND]'`.
`ARGV`
  The array of command line arguments. The array is indexed from zero to `ARGC` - 1. Dynamically changing `ARGC` and the contents of `ARGV` can control the files used for data. A null-valued element in `ARGV` is ignored. `ARGV` does not include the options to `awk` or the text of the `awk` program itself.
`CONVFMT`
  The conversion format to use when converting numbers to strings.
`FIELDWIDTHS`
  A space separated list of numbers describing the fixed-width input data.
`ENVIRON`
  An array of environment variable values. The array is indexed by variable name, each element being the value of that variable. Thus, the environment variable `HOME` is `ENVIRON["HOME"]`. One possible value might be ``/home/arnold'`. Changing this array does not affect the environment seen by programs which `gawk` spawns via redirection or the `system` function. (This may change in a future version of `gawk`.) Some operating systems do not have environment variables. The `ENVIRON` array is empty when running on these systems.
`ERRNO`
  The system error message when an error occurs using `getline` or `close`.
`FILENAME`
  The name of the current input file. If no files are specified on the command line, the value of `FILENAME` is the null string.
`FNR`
  The input record number in the current input file.
`FS`
  The input field separator, a space by default.
`IGNORECASE`
  The case-sensitivity flag for string comparisons and regular expression operations. If `IGNORECASE` has a non-zero value, then pattern matching in rules, record separating with `RS`, field splitting with `FS`, regular expression matching with ``~'` and ``!~'`, and the `gensub`, `gsub`, `index`, `match`, `split` and `sub` built-in functions all ignore case when doing regular expression operations, and all string comparisons are done ignoring case. The value of `IGNORECASE` does not affect array subscripting.
`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 for the `print` statement, `"%.6g"` by default.
`OFS`
  The output field separator, a space by default.
`ORS`
  The output record separator, by default a newline.
`RS`
  The input record separator, by default a newline. If `RS` is set to the null string, then records are separated by blank lines. When `RS` is set to the null string, then the newline character always acts as a field separator, in addition to whatever value `FS` may have. If `RS` is set to a multi-character string, it denotes a regexp; input text matching the regexp separates records.
`RT`
  The input text that matched the text denoted by `RS`, the record separator.
`RSTART`
  The index of the first character last matched by `match`; zero if no match.
`RLENGTH`
  The length of the string last matched by `match`; -1 if no match.
`SUBSEP`
  The string used to separate multiple subscripts in array elements, by default `"\034"`.

See section Built-in Variables, for more information.

### Arrays

Arrays are subscripted with an expression between square brackets (``['` and ``]'`). Array subscripts are always strings; numbers are converted to strings as necessary, following the standard conversion rules (see section Conversion of Strings and Numbers).

If you use multiple expressions separated by commas inside the square brackets, then the array subscript is a string consisting of the concatenation of the individual subscript values, converted to strings, separated by the subscript separator (the value of `SUBSEP`).

The special operator `in` may be used in a conditional context to see 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'` to test for existence of an element.

The `in` construct may also be used in a `for` loop to iterate over all the elements of an array. See section Scanning All Elements of an Array.

You can remove an element from an array using the `delete` statement.

You can clear an entire array using ``delete array'`.

See section Arrays in `awk`.

### Data Types

The value of an `awk` expression is always either a number or a string.

Some contexts (such as arithmetic operators) require numeric values. They convert strings to numbers by interpreting the text of the string as a number. If the string does not look like a number, it converts to zero.

Other contexts (such as concatenation) require string values. They convert numbers to strings by effectively printing them with `sprintf`. See section Conversion of Strings and Numbers, for the details.

To force conversion of a string value to a number, simply add zero to it. If the value you start with is already a number, this does not change it.

To force conversion of a numeric value to a string, concatenate it with the null string.

Comparisons are done numerically if both operands are numeric, or if one is numeric and the other is a numeric string. Otherwise one or both operands are converted to strings and a string comparison is performed. Fields, `getline` input, `FILENAME`, `ARGV` elements, `ENVIRON` elements and the elements of an array created by `split` are the only items that can be numeric strings. String constants, such as `"3.1415927"` are not numeric strings, they are string constants. The full rules for comparisons are described in section Variable Typing and Comparison Expressions.

Uninitialized variables have the string value `""` (the null, or empty, string). In contexts where a number is required, this is equivalent to zero.

See section Variables, for more information on variable naming and initialization; see section Conversion of Strings and Numbers, for more information on how variable values are interpreted.

## Patterns

- Pattern Summary: Quick overview of patterns.
- Regexp Summary: Quick overview of regular expressions.

An `awk` program is mostly composed of rules, each consisting of a pattern followed by an action. The action is enclosed in ``{'` and ``}'`. Either the pattern may be missing, or the action may be missing, but not both. If the pattern is missing, the action is executed for every input record. A missing action is equivalent to ``{ print }'`, which prints the entire line.

Comments begin with the ``#'` character, and continue until the end of the line. Blank lines may be used to separate statements. Statements normally end with a newline; however, this is not the case for lines ending in a ``,'`, ``{'`, ``?'`, ``:'`, ``&&'`, or ``||'`. Lines ending in `do` or `else` also have their statements automatically continued on the following line. In other cases, a line can be continued by ending it with a ``\'`, in which case the newline is ignored.

Multiple statements may be put on one line by separating each one with a ``;'`. This applies to both the statements within the action part of a rule (the usual case), and to the rule statements.

See section Comments in `awk` Programs, for information on `awk`'s commenting convention; see section `awk` Statements Versus Lines, for a description of the line continuation mechanism in `awk`.

### Pattern Summary

`awk` patterns may be one of the following:

    /regular expression/
    relational expression
    pattern && pattern
    pattern || pattern
    pattern ? pattern : pattern
    (pattern)
    ! pattern
    pattern1, pattern2
    BEGIN
    END

`BEGIN` and `END` are two special kinds of patterns that are not tested against the input. The action parts of all `BEGIN` rules are concatenated as if all the statements had been written in a single `BEGIN` rule. They are executed before any of the input is read. Similarly, all the `END` rules are concatenated, and executed when all the input is exhausted (or when an `exit` statement is executed). `BEGIN` and `END` patterns cannot be combined with other patterns in pattern expressions. `BEGIN` and `END` rules cannot have missing action parts.

For `/regular-expression/` patterns, the associated statement is executed for each input record that matches the regular expression. Regular expressions are summarized below.

A relational expression may use any of the operators defined below in the section on actions. These generally test whether certain fields match certain regular expressions.

The ``&&'`, ``||'`, and ``!'` operators are logical "and," logical "or," and logical "not," respectively, as in C. They do short-circuit evaluation, also as in C, and are used for combining more primitive pattern expressions. As in most languages, parentheses may be used to change the order of evaluation.

The ``?:'` operator is like the same operator in C. If the first pattern matches, then the second pattern is matched against the input record; otherwise, the third is matched. Only one of the second and third patterns is matched.

The ``pattern1, pattern2'` form of a pattern is called a range pattern. It matches all input lines starting with a line that matches pattern1, and continuing until a line that matches pattern2, inclusive. A range pattern cannot be used as an operand of any of the pattern operators.

See section Pattern Elements.

### Regular Expressions

Regular expressions are based on POSIX EREs (extended regular expressions). The escape sequences allowed in string constants are also valid in regular expressions (see section Escape Sequences). Regexps are composed of characters as follows:

`c`
  matches the character c (assuming c is none of the characters listed below).
`\c`
  matches the literal character c.
`.`
  matches any character, including newline. In strict POSIX mode, ``.'` does not match the NUL character, which is a character with all bits equal to zero.
`^`
  matches the beginning of a string.
`$`
  matches the end of a string.
`[abc...]`
  matches any of the characters abc... (character list).
`[[:class:]]`
  matches any character in the character class class. Allowable classes are `alnum`, `alpha`, `blank`, `cntrl`, `digit`, `graph`, `lower`, `print`, `punct`, `space`, `upper`, and `xdigit`.
`[[.symbol.]]`
  matches the multi-character collating symbol symbol. `gawk` does not currently support collating symbols.
`[[=classname=]]`
  matches any of the equivalent characters in the current locale named by the equivalence class classname. `gawk` does not currently support equivalence classes.
`[^abc...]`
  matches any character except abc... (negated character list).
`r1|r2`
  matches either r1 or r2 (alternation).
`r1r2`
  matches r1, and then r2 (concatenation).
`r+`
  matches one or more r's.
`r*`
  matches zero or more r's.
`r?`
  matches zero or one r's.
`(r)`
  matches r (grouping).
`r{n}`
`r{n,}`
`r{n,m}`
  matches at least n, n to any number, or n to m occurrences of r (interval expressions).
`\y`
  matches the empty string at either the beginning or the end of a word.
`\B`
  matches the empty string within a word.
`\<`
  matches the empty string at the beginning of a word.
`\>`
  matches the empty string at the end of a word.
`\w`
  matches any word-constituent character (alphanumeric characters and the underscore).
`\W`
  matches any character that is not word-constituent.
`\``
  matches the empty string at the beginning of a buffer (same as a string in `gawk`).
`\'`
  matches the empty string at the end of a buffer.

The various command line options control how `gawk` interprets characters in regexps.

No options
  In the default case, `gawk` provide all the facilities of POSIX regexps and the GNU regexp operators described above. However, interval expressions are not supported.
`--posix`
  Only POSIX regexps are supported, the GNU operators are not special (e.g., ``\w'` matches a literal ``w'`). Interval expressions are allowed.
`--traditional`
  Traditional Unix `awk` regexps are matched. The GNU operators are not special, interval expressions are not available, and neither are the POSIX character classes (`[[:alnum:]]` and so on). Characters described by octal and hexadecimal escape sequences are treated literally, even if they represent regexp metacharacters.
`--re-interval`
  Allow interval expressions in regexps, even if ``--traditional'` has been provided.

See section Regular Expressions.

## Actions

Action statements are enclosed in braces, ``{'` and ``}'`. A missing action statement is equivalent to ``{ print }'`.

Action statements consist of the usual assignment, conditional, and looping statements found in most languages. The operators, control statements, and Input/Output statements available are similar to those in C.

Comments begin with the ``#'` character, and continue until the end of the line. Blank lines may be used to separate statements. Statements normally end with a newline; however, this is not the case for lines ending in a ``,'`, ``{'`, ``?'`, ``:'`, ``&&'`, or ``||'`. Lines ending in `do` or `else` also have their statements automatically continued on the following line. In other cases, a line can be continued by ending it with a ``\'`, in which case the newline is ignored.

Multiple statements may be put on one line by separating each one with a ``;'`. This applies to both the statements within the action part of a rule (the usual case), and to the rule statements.

See section Comments in `awk` Programs, for information on `awk`'s commenting convention; see section `awk` Statements Versus Lines, for a description of the line continuation mechanism in `awk`.

- Operator Summary: `awk` operators.
- Control Flow Summary: The control statements.
- I/O Summary: The I/O statements.
- Printf Summary: A summary of `printf`.
- Special File Summary: Special file names interpreted internally.
- Built-in Functions Summary: Built-in numeric and string functions.
- Time Functions Summary: Built-in time functions.
- String Constants Summary: Escape sequences in strings.

### Operators

The operators in `awk`, in order of decreasing precedence, are:

`(...)`
  Grouping.
`$`
  Field reference.
`++ --`
  Increment and decrement, both prefix and postfix.
`^`
  Exponentiation (``**'` may also be used, and ``**='` for the assignment operator, but they are not specified in the POSIX standard).
`+ - !`
  Unary plus, unary minus, and logical negation.
`* / %`
  Multiplication, division, and modulus.
`+ -`
  Addition and subtraction.
`space`
  String concatenation.
`< <= > >= != ==`
  The usual relational operators.
`~ !~`
  Regular expression match, negated match.
`in`
  Array membership.
`&&`
  Logical "and".
`||`
  Logical "or".
`?:`
  A conditional expression. This has the form ``expr1 ? expr2 : expr3'`. If expr1 is true, the value of the expression is expr2; otherwise it is expr3. Only one of expr2 and expr3 is evaluated.
`= += -= *= /= %= ^=`
  Assignment. Both absolute assignment (`var=value`) and operator assignment (the other forms) are supported.

See section Expressions.

### Control Statements

The control statements are as follows:

    if (condition) statement [ else statement ]
    while (condition) statement
    do statement while (condition)
    for (expr1; expr2; expr3) statement
    for (var in array) statement
    break
    continue
    delete array[index]
    delete array
    exit [ expression ]
    { statements }

See section Control Statements in Actions.

### I/O Statements

The Input/Output statements are as follows:

`getline`
  Set `$0` from next input record; set `NF`, `NR`, `FNR`. See section Explicit Input with `getline`.
`getline <file`
  Set `$0` from next record of file; set `NF`.
`getline var`
  Set var from next input record; set `NR`, `FNR`.
`getline var <file`
  Set var from next record of file.
`command | getline`
  Run command, piping its output into `getline`; sets `$0`, `NF`, `NR`.
`command | getline `var``
  Run command, piping its output into `getline`; sets var.
`next`
  Stop processing the current input record. The next input record is read and processing starts over with the first pattern in the `awk` program. If the end of the input data is reached, the `END` rule(s), if any, are executed. See section The `next` Statement.
`nextfile`
  Stop processing the current input file. The next input record read comes from the next input file. `FILENAME` is updated, `FNR` is set to one, `ARGIND` is incremented, and processing starts over with the first pattern in the `awk` program. If the end of the input data is reached, the `END` rule(s), if any, are executed. Earlier versions of `gawk` used ``next file'`; this usage is still supported, but is considered to be deprecated. See section The `nextfile` Statement.
`print`
  Prints the current record. See section Printing Output.
`print expr-list`
  Prints expressions.
`print expr-list > file`
  Prints expressions to file. If file does not exist, it is created. If it does exist, its contents are deleted the first time the `print` is executed.
`print expr-list >> file`
  Prints expressions to file. The previous contents of file are retained, and the output of `print` is appended to the file.
`print expr-list | command`
  Prints expressions, sending the output down a pipe to command. The pipeline to the command stays open until the `close` function is called.
`printf fmt, expr-list`
  Format and print.
`printf fmt, expr-list > file`
  Format and print to file. If file does not exist, it is created. If it does exist, its contents are deleted the first time the `printf` is executed.
`printf fmt, expr-list >> file`
  Format and print to file. The previous contents of file are retained, and the output of `printf` is appended to the file.
`printf fmt, expr-list | command`
  Format and print, sending the output down a pipe to command. The pipeline to the command stays open until the `close` function is called.

`getline` returns zero on end of file, and -1 on an error. In the event of an error, `getline` will set `ERRNO` to the value of a system-dependent string that describes the error.

### `printf` Summary

Conversion specification have the form `%`[flag][width][`.`prec]format. Items in brackets are optional.

The `awk` `printf` statement and `sprintf` function accept the following conversion specification formats:

`%c`
  An ASCII character. If the argument used for ``%c'` is numeric, it is treated as a character and printed. Otherwise, the argument is assumed to be a string, and the only first character of that string is printed.
`%d`
`%i`
  A decimal number (the integer part).
`%e`
`%E`
  A floating point number of the form ``[-]d.dddddde[+-]dd'`. The ``%E'` format uses ``E'` instead of ``e'`.
`%f`
  A floating point number of the form [`-`]`ddd.dddddd`.
`%g`
`%G`
  Use either the ``%e'` or ``%f'` formats, whichever produces a shorter string, with non-significant zeros suppressed. ``%G'` will use ``%E'` instead of ``%e'`.
`%o`
  An unsigned octal number (again, an integer).
`%s`
  A character string.
`%x`
`%X`
  An unsigned hexadecimal number (an integer). The ``%X'` format uses ``A'` through ``F'` instead of ``a'` through ``f'` for decimal 10 through 15.
`%%`
  A single ``%'` character; no argument is converted.

There are optional, additional parameters that may lie between the ``%'` and the control letter:

`-`
  The expression should be left-justified within its field.
`space`
  For numeric conversions, prefix positive values with a space, and negative values with a minus sign.
`+`
  The plus sign, used before the width modifier (see below), says to always supply a sign for numeric conversions, even if the data to be formatted is positive. The ``+'` overrides the space modifier.
`#`
  Use an "alternate form" for certain control letters. For ``o'`, supply a leading zero. For ``x'`, and ``X'`, supply a leading ``0x'` or ``0X'` for a non-zero result. For ``e'`, ``E'`, and ``f'`, the result will always contain a decimal point. For ``g'`, and ``G'`, trailing zeros are not removed from the result.
`0`
  A leading ``0'` (zero) acts as a flag, that indicates output should be padded with zeros instead of spaces. This applies even to non-numeric output formats. This flag only has an effect when the field width is wider than the value to be printed.
`width`
  The field should be padded to this width. The field is normally padded with spaces. If the ``0'` flag has been used, it is padded with zeros.
`.prec`
  A number that specifies the precision to use when printing. For the ``e'`, ``E'`, and ``f'` formats, this specifies the number of digits you want printed to the right of the decimal point. For the ``g'`, and ``G'` formats, it specifies the maximum number of significant digits. For the ``d'`, ``o'`, ``i'`, ``u'`, ``x'`, and ``X'` formats, it specifies the minimum number of digits to print. For the ``s'` format, it specifies the maximum number of characters from the string that should be printed.

Either or both of the width and prec values may be specified as ``*'`. In that case, the particular value is taken from the argument list.

See section Using `printf` Statements for Fancier Printing.

### Special File Names

When doing I/O redirection from either `print` or `printf` into a file, or via `getline` from a file, `gawk` recognizes certain special file names internally. These file names allow access to open file descriptors inherited from `gawk`'s parent process (usually the shell). The file names are:

``/dev/stdin'`
  The standard input.
``/dev/stdout'`
  The standard output.
``/dev/stderr'`
  The standard error output.
``/dev/fd/n'`
  The file denoted by the open file descriptor n.

In addition, reading the following files provides process related information about the running `gawk` program. All returned records are terminated with a newline.

``/dev/pid'`
  Returns the process ID of the current process.
``/dev/ppid'`
  Returns the parent process ID of the current process.
``/dev/pgrpid'`
  Returns the process group ID of the current process.
``/dev/user'`
  At least four space-separated fields, containing the return values of the `getuid`, `geteuid`, `getgid`, and `getegid` system calls. If there are any additional fields, they are the group IDs returned by `getgroups` system call. (Multiple groups may not be supported on all systems.)

These file names may also be used on the command line to name data files. These file names are only recognized internally if you do not actually have files with these names on your system.

See section Special File Names in `gawk`, for a longer description that provides the motivation for this feature.

### Built-in Functions

`awk` provides a number of built-in functions for performing numeric operations, string related operations, and I/O related operations.

The built-in arithmetic functions are:

`atan2(y, x)`
  the arctangent of y/x in radians.
`cos(expr)`
  the cosine of expr, which is in radians.
`exp(expr)`
  the exponential function (`e ^ expr`).
`int(expr)`
  truncates to integer.
`log(expr)`
  the natural logarithm of `expr`.
`rand()`
  a random number between zero and one.
`sin(expr)`
  the sine of expr, which is in radians.
`sqrt(expr)`
  the square root function.
`srand([expr])`
  use expr as a new seed for the random number generator. If no expr is provided, the time of day is used. The return value is the previous seed for the random number generator.

`awk` has the following built-in string functions:

`gensub(regex, subst, how [, target])`
  If how is a string beginning with ``g'` or ``G'`, then replace each match of regex in target with subst. Otherwise, replace the how'th occurrence. If target is not supplied, use `$0`. The return value is the changed string; the original target is not modified. Within subst, ``\n'`, where n is a digit from one to nine, can be used to indicate the text that matched the n'th parenthesized subexpression. This function is `gawk`-specific.
`gsub(regex, subst [, target])`
  for each substring matching the regular expression regex in the string target, substitute the string subst, and return the number of substitutions. If target is not supplied, use `$0`.
`index(str, search)`
  returns the index of the string search in the string str, or zero if search is not present.
`length([str])`
  returns the length of the string str. The length of `$0` is returned if no argument is supplied.
`match(str, regex)`
  returns the position in str where the regular expression regex occurs, or zero if regex is not present, and sets the values of `RSTART` and `RLENGTH`.
`split(str, arr [, regex])`
  splits the string str into the array arr on the regular expression regex, and returns the number of elements. If regex is omitted, `FS` is used instead. regex can be the null string, causing each character to be placed into its own array element. The array arr is cleared first.
`sprintf(fmt, expr-list)`
  prints expr-list according to fmt, and returns the resulting string.
`sub(regex, subst [, target])`
  just like `gsub`, but only the first matching substring is replaced.
`substr(str, index [, len])`
  returns the len-character substring of str starting at index. If len is omitted, the rest of str is used.
`tolower(str)`
  returns a copy of the string str, with all the upper-case characters in str translated to their corresponding lower-case counterparts. Non-alphabetic characters are left unchanged.
`toupper(str)`
  returns a copy of the string str, with all the lower-case characters in str translated to their corresponding upper-case counterparts. Non-alphabetic characters are left unchanged.

The I/O related functions are:

`close(expr)`
  Close the open file or pipe denoted by expr.
`fflush([expr])`
  Flush any buffered output for the output file or pipe denoted by expr. If expr is omitted, standard output is flushed. If expr is the null string (`""`), all output buffers are flushed.
`system(cmd-line)`
  Execute the command cmd-line, and return the exit status. If your operating system does not support `system`, calling it will generate a fatal error. ``system("")'` can be used to force `awk` to flush any pending output. This is more portable, but less obvious, than calling `fflush`.

### Time Functions

The following two functions are available for getting the current time of day, and for formatting time stamps. They are specific to `gawk`.

`systime()`
  returns the current time of day as the number of seconds since a particular epoch (Midnight, January 1, 1970 UTC, on POSIX systems).
`strftime([format[, timestamp]])`
  formats timestamp according to the specification in format. The current time of day is used if no timestamp is supplied. A default format equivalent to the output of the `date` utility is used if no format is supplied. See section Functions for Dealing with Time Stamps, for the details on the conversion specifiers that `strftime` accepts.

See section Built-in Functions, for a description of all of `awk`'s built-in functions.

### String Constants

String constants in `awk` are sequences of characters enclosed in double quotes (`"`). 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`
  Formfeed.
`\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'`. As in ANSI C, all following hexadecimal digits are considered part of the escape sequence. E.g., `"\x1B"` is a string containing the ASCII ESC (escape) character. (The ``\x'` escape sequence is not in POSIX `awk`.)
`\ddd`
  The character represented by the one, two, or three digit sequence of octal digits. Thus, `"\033"` is also a string containing the ASCII ESC (escape) character.
`\c`
  The literal character c, if c is not one of the above.

The escape sequences may also be used inside constant regular expressions (e.g., the regexp `/[ \t\f\n\r\v]/` matches whitespace characters).

See section Escape Sequences.

## User-defined Functions

Functions in `awk` are defined as follows:

    function name(parameter list) { statements }

Actual parameters supplied in the function call are used to instantiate the formal parameters declared in the function. Arrays are passed by reference, other variables are passed by value.

If there are fewer arguments passed than there are names in parameter-list, the extra names are given the null string as their value. Extra names have the effect of local variables.

The open-parenthesis in a function call of a user-defined function must immediately follow the function name, without any intervening white space. This is to avoid a syntactic ambiguity with the concatenation operator.

The word `func` may be used in place of `function` (but not in POSIX `awk`).

Use the `return` statement to return a value from a function.

See section User-defined Functions.

## Historical Features

There are two features of historical `awk` implementations that `gawk` supports.

First, it is possible to call the `length` built-in function not only with no arguments, but even without parentheses!

    a = length

is the same as either of

    a = length()
    a = length($0)

For example:

    $ echo abcdef | awk '{ print length }'
    -| 6

This feature is marked as "deprecated" in the POSIX standard, and `gawk` will issue a warning about its use if ``--lint'` is specified on the command line. (The ability to use `length` this way was actually an accident of the original Unix `awk` implementation. If any built-in function used `$0` as its default argument, it was possible to call that function without the parentheses. In particular, it was common practice to use the `length` function in this fashion, and this usage was documented in the `awk` manual page.)

The other historical feature is the use of either the `break` statement, or the `continue` statement outside the body of a `while`, `for`, or `do` loop. Traditional `awk` implementations have treated such usage as equivalent to the `next` statement. More recent versions of Unix `awk` do not allow it. `gawk` supports this usage if ``--traditional'` has been specified.

See section Command Line Options, for more information about the ``--posix'` and ``--lint'` options.

Go to the first, previous, next, last section, table of contents.