Built-in Variables that Convey Information

This is an alphabetical list of the variables that are set automatically by awk on certain occasions in order to provide information to your program. Those variables that are specific to gawk are marked with an asterisk, `*'.

ARGC

ARGV

The command-line arguments available to awk programs are stored in an array called ARGV. ARGC is the number of command-line arguments present. See section Other Command Line Arguments. Unlike most awk arrays, ARGV is indexed from zero to ARGC - 1. For example:

$ awk 'BEGIN {
>        for (i = 0; i < ARGC; i++) 
>            print ARGV[i] 
>      }' inventory-shipped BBS-list
-| awk
-| inventory-shipped
-| BBS-list

In this example, ARGV[0] contains "awk", ARGV[1] contains "inventory-shipped", and ARGV[2] contains "BBS-list". The value of ARGC is three, one more than the index of the last element in ARGV, since the elements are numbered from zero. The names ARGC and ARGV, as well as the convention of indexing the array from zero to ARGC - 1, are derived from the C language's method of accessing command line arguments. See section Using ARGC and ARGV, for information about how awk uses these variables.

ARGIND *

The index in ARGV of the current file being processed. Every time gawk opens a new data file for processing, it sets ARGIND to the index in ARGV of the file name. When gawk is processing the input files, it is always true that `FILENAME == ARGV[ARGIND]'. This variable is useful in file processing; it allows you to tell how far along you are in the list of data files, and to distinguish between successive instances of the same filename on the command line. While you can change the value of ARGIND within your awk program, gawk will automatically set it to a new value when the next file is opened. This variable is a gawk extension. In other awk implementations, or if gawk is in compatibility mode (see section Command Line Options), it is not special.

ENVIRON

An associative array that contains the values of the environment. The array indices are the environment variable names; the values are the values of the particular environment variables. For example, ENVIRON["HOME"] might be `/home/arnold'. Changing this array does not affect the environment passed on to any programs that awk may spawn via redirection or the system function. (In a future version of gawk, it may do so.) Some operating systems may not have environment variables. On such systems, the ENVIRON array is empty (except for ENVIRON["AWKPATH"]).

ERRNO *

If a system error occurs either doing a redirection for getline, during a read for getline, or during a close operation, then ERRNO will contain a string describing the error. This variable is a gawk extension. In other awk implementations, or if gawk is in compatibility mode (see section Command Line Options), it is not special.

FILENAME

This is the name of the file that awk is currently reading. When no data files are listed on the command line, awk reads from the standard input, and FILENAME is set to "-". FILENAME is changed each time a new file is read (see section Reading Input Files). Inside a BEGIN rule, the value of FILENAME is "", since there are no input files being processed yet.(9) (d.c.)

FNR

FNR is the current record number in the current file. FNR is incremented each time a new record is read (see section Explicit Input with getline). It is reinitialized to zero each time a new input file is started.

NF

NF is the number of fields in the current input record. NF is set each time a new record is read, when a new field is created, or when $0 changes (see section Examining Fields).

NR

This is the number of input records awk has processed since the beginning of the program's execution (see section How Input is Split into Records). NR is set each time a new record is read.

RLENGTH

RLENGTH is the length of the substring matched by the match function (see section Built-in Functions for String Manipulation). RLENGTH is set by invoking the match function. Its value is the length of the matched string, or -1 if no match was found.

RSTART

RSTART is the start-index in characters of the substring matched by the match function (see section Built-in Functions for String Manipulation). RSTART is set by invoking the match function. Its value is the position of the string where the matched substring starts, or zero if no match was found.

RT *

RT is set each time a record is read. It contains the input text that matched the text denoted by RS, the record separator. This variable is a gawk extension. In other awk implementations, or if gawk is in compatibility mode (see section Command Line Options), it is not special.

A side note about NR and FNR. awk simply increments both of these variables each time it reads a record, instead of setting them to the absolute value of the number of records read. This means that your program can change these variables, and their new values will be incremented for each record (d.c.). For example:

$ echo '1
> 2
> 3
> 4' | awk 'NR == 2 { NR = 17 }
> { print NR }'
-| 1
-| 17
-| 18
-| 19

Before FNR was added to the awk language (see section Major Changes between V7 and SVR3.1), many awk programs used this feature to track the number of records in a file by resetting NR to zero when FILENAME changed.

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