Next: , Previous: User-modified, Up: Built-in Variables


7.5.2 Built-in Variables That Convey Information

The following is an alphabetical list of variables that awk sets automatically on certain occasions in order to provide information to your program. The variables that are specific to gawk are marked with a pound sign (‘#’).

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 Other Arguments. Unlike most awk arrays, ARGV is indexed from 0 to ARGC − 1. In the following example:
          $ awk 'BEGIN {
          >         for (i = 0; i < ARGC; i++)
          >             print ARGV[i]
          >      }' inventory-shipped BBS-list
          -| awk
          -| inventory-shipped
          -| BBS-list

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, because the elements are numbered from zero.

The names ARGC and ARGV, as well as the convention of indexing the array from 0 to ARGC − 1, are derived from the C language's method of accessing command-line arguments.

The value of ARGV[0] can vary from system to system. Also, you should note that the program text is not included in ARGV, nor are any of awk's command-line options. See ARGC and ARGV, for information about how awk uses these variables. (d.c.)


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, ‘FILENAME == ARGV[ARGIND]’ is always true.

This variable is useful in file processing; it allows you to tell how far along you are in the list of data files as well as to distinguish between successive instances of the same file name on the command line.

While you can change the value of ARGIND within your awk program, gawk automatically sets 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 Options), it is not special.


ENVIRON
An associative array containing the values of the environment. The array indices are the environment variable names; the elements 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.

Some operating systems may not have environment variables. On such systems, the ENVIRON array is empty (except for ENVIRON["AWKPATH"], see AWKPATH Variable and ENVIRON["AWKLIBPATH"], see AWKLIBPATH Variable).


ERRNO #
If a system error occurs during a redirection for getline, during a read for getline, or during a close() operation, then ERRNO contains a string describing the error.

In addition, gawk clears ERRNO before opening each command-line input file. This enables checking if the file is readable inside a BEGINFILE pattern (see BEGINFILE/ENDFILE).

Otherwise, ERRNO works similarly to the C variable errno. Except for the case just mentioned, gawk never clears it (sets it to zero or ""). Thus, you should only expect its value to be meaningful when an I/O operation returns a failure value, such as getline returning −1. You are, of course, free to clear it yourself before doing an I/O operation.

This variable is a gawk extension. In other awk implementations, or if gawk is in compatibility mode (see Options), it is not special.


FILENAME
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 Reading Files). Inside a BEGIN rule, the value of FILENAME is "", since there are no input files being processed yet.1 (d.c.) Note, though, that using getline (see Getline) inside a BEGIN rule can give FILENAME a value.


FNR
The current record number in the current file. FNR is incremented each time a new record is read (see Records). It is reinitialized to zero each time a new input file is started.


NF
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 Fields).

Unlike most of the variables described in this section, assigning a value to NF has the potential to affect awk's internal workings. In particular, assignments to NF can be used to create or remove fields from the current record. See Changing Fields.


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.


NR
The number of input records awk has processed since the beginning of the program's execution (see Records). NR is incremented each time a new record is read.


PROCINFO #
The elements of this array provide access to information about the running awk program. The following elements (listed alphabetically) are guaranteed to be available:
PROCINFO["egid"]
The value of the getegid() system call.
PROCINFO["euid"]
The value of the geteuid() system call.
PROCINFO["FS"]
This is "FS" if field splitting with FS is in effect, "FIELDWIDTHS" if field splitting with FIELDWIDTHS is in effect, or "FPAT" if field matching with FPAT is in effect.
PROCINFO["identifiers"]
A subarray, indexed by the names of all identifiers used in the text of the AWK program. For each identifier, the value of the element is one of the following:
"array"
The identifier is an array.
"extension"
The identifier is an extension function loaded via @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.

The values indicate what gawk knows about the identifiers after it has finished parsing the program; they are not updated while the program runs.

PROCINFO["gid"]
The value of the getgid() system call.
PROCINFO["pgrpid"]
The process group ID of the current process.
PROCINFO["pid"]
The process ID of the current process.
PROCINFO["ppid"]
The parent process ID of the current process.
PROCINFO["sorted_in"]
If this element exists in PROCINFO, its value controls the order in which array indices will be processed by ‘for (index in array) ...’ loops. Since this is an advanced feature, we defer the full description until later; see Scanning an Array.
PROCINFO["strftime"]
The default time format string for strftime(). Assigning a new value to this element changes the default. See Time Functions.
PROCINFO["uid"]
The value of the getuid() system call.
PROCINFO["version"]
The version of gawk.

The following additional elements in the array are available to provide information about the MPFR and GMP libraries if your version of gawk supports arbitrary precision numbers (see Arbitrary Precision Arithmetic):

PROCINFO["mpfr_version"]
The version of the GNU MPFR library.
PROCINFO["gmp_version"]
The version of the GNU MP library.
PROCINFO["prec_max"]
The maximum precision supported by MPFR.
PROCINFO["prec_min"]
The minimum precision required by MPFR.

The following additional elements in the array are available to provide information about the version of the extension API, if your version of gawk supports dynamic loading of extension functions (see Dynamic Extensions):

PROCINFO["api_major"]
The major version of the extension API.
PROCINFO["api_minor"]
The minor version of the extension API.

On some systems, there may be elements in the array, "group1" through "groupN" for some N. N is the number of supplementary groups that the process has. Use the in operator to test for these elements (see Reference to Elements).

The PROCINFO array has the following additional uses:

This array is a gawk extension. In other awk implementations, or if gawk is in compatibility mode (see Options), it is not special.


RLENGTH
The length of the substring matched by the match() function (see String Functions). RLENGTH is set by invoking the match() function. Its value is the length of the matched string, or −1 if no match is found.


RSTART
The start-index in characters of the substring that is matched by the match() function (see String Functions). 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 #
This 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 Options), it is not special.


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 isarray() function (see Type Functions) may be used to test if an element in SYMTAB is an array. Also, you may not use the delete statement with the SYMTAB array.

You may use an index for SYMTAB that is not a predefined identifer:

          SYMTAB["xxx"] = 5
          print SYMTAB["xxx"]

This works as expected: in this case SYMTAB acts just like a regular array. The only difference is that you can't then delete SYMTAB["xxx"].

The SYMTAB array is more interesting than it looks. Andrew Schorr points out that it effectively gives awk data pointers. Consider his example:

          # Indirect multiply of any variable by amount, return result
          
          function multiply(variable, amount)
          {
              return SYMTAB[variable] *= amount
          }
NOTE: In order to avoid severe time-travel paradoxes2, neither FUNCTAB nor SYMTAB are available as elements within the SYMTAB array.

Changing NR and FNR

awk increments NR and FNR each time it reads a record, instead of setting them to the absolute value of the number of records read. This means that a program can change these variables and their new values are incremented for each record. (d.c.) The following example shows this:

     $ 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 V7/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.


Footnotes

[1] Some early implementations of Unix awk initialized FILENAME to "-", even if there were data files to be processed. This behavior was incorrect and should not be relied upon in your programs.

[2] Not to mention difficult implementation issues.