About Us Documentation

Contact Site Map



GAWK Manual - gawk Summary Go to the previous, next chapter.

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 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:

	awk [POSIX or GNU style options] -f source-file [--] file ...
	awk [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.

  • -v var=val
  • --assign=var=val Assign the variable var the value val before program execution begins.

  • -W compat
  • --compat Specifies 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 error output. 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 error output.

  • -W lint
  • --lint Give warnings about dubious or non-portable awk constructs.

  • -W posix
  • --posix Specifies POSIX compatibility mode, in which gawk extensions are turned off and additional restrictions apply.

  • -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. This option may disappear in a future version of gawk.

  • -- 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 the argument parsing conventions of POSIX.
  • Any other options are flagged as invalid, but are otherwise ignored.

    An awk program consists of a sequence of pattern-action statements and optional function definitions.

    	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 -f /dev/tty; then type your program, and end it with a Control-d. See section Invoking awk specifies a search path to use when finding source files named with the -f option. The default path, which is .:/usr/lib/awk:/usr/local/lib/awk 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 environment variable.

    gawk compiles the program into an internal form, and then proceeds to read each file named in the ARGV array. 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 line in the input, gawk tests to see if it matches any pattern in the awk program. For each pattern that the line matches, the associated action is executed.

    Variables and Fields

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


    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 blank, fields are separated by runs of blanks and/or tabs. 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 nonexistent fields (i.e., fields after $NF) return the null-string. However, assigning to a nonexistent 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.

    See section Reading Input Files, for a full description of the way awk defines and uses fields.

    Built-in Variables

    awk's built-in variables are:

  • ARGC The number of command line arguments (not including options or the awk program itself).

  • ARGIND The index in ARGV of the current file being processed. It is always true that FILENAME == ARGV[ARGIND].

  • ARGV The 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.

  • 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 containing the values of the environment variables. The array is indexed by variable name, each element being the value of that variable. Thus, the environment variable HOME would be in ENVIRON["HOME"]. Its value might be /u/close.

    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 array ENVIRON 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 -.

  • FNR The input record number in the current input file.

  • FS The input field separator, a blank by default.

  • IGNORECASE The case-sensitivity flag for regular expression operations. If IGNORECASE has a nonzero value, then pattern matching in rules, field splitting with FS, regular expression matching with ~ and !~, and the gsub, index, match, split and sub predefined functions all ignore case when doing regular expression operations.

  • 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 blank by default.

  • ORS The output record separator, by default a newline.

  • RS The input record separator, by default a newline. RS is exceptional in that 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 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.

  • RSTART The index of the first character matched by match; 0 if no match.

  • 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".
  • See section Built-in Variables, for more information.


    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 an if or while statement 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.

    An element may be deleted from an array using the delete statement.

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

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

    Certain 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 0 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.

    The awk language defines comparisons as being 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.

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

    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 and Actions

    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, of course, not both. If the pattern is missing, the action is executed for every single line of input. A missing action is equivalent to this action,

    	{ 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. Normally, a statement ends 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 them 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's commenting convention; see section awk Statements versus Lines.


    awk patterns may be one of the following:

    	/regular expression/
    	relational expression
    	pattern && pattern
    	pattern || pattern
    	pattern ? pattern : pattern
    	! pattern
    	pattern1, pattern2

    BEGIN and END are two special kinds of patterns that are not tested against the input. The action parts of all BEGIN rules are merged 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 merged, 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 line that matches the regular expression. Regular expressions are extensions of those in egrep, and 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 to any of the pattern operators.

    See section Patterns, for a full description of the pattern part of awk rules.

    Regular Expressions

    Regular expressions are the extended kind found in egrep. They are composed of characters as follows:

  • c matches the character c (assuming c is a character with no special meaning in regexps).

  • \c matches the literal character c.

  • . matches any character except newline.

  • ^ matches the beginning of a line or a string.

  • $ matches the end of a line or a string.

  • [abc...] matches any of the characters abc... (character class).

  • [^abc...] matches any character except abc... and newline (negated character class).

  • 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).
  • See section Regular Expressions as Patterns, for a more detailed explanation of regular expressions.

    The escape sequences allowed in string constants are also valid in regular expressions (see section Constant Expressions).


    Action statements are enclosed in braces, { and }. 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 patterned after those in C.


    The operators in awk, in order of increasing precedence, are:

  • = += -= *= /= %= ^= Assignment. Both absolute assignment (var=value) and operator assignment (the other forms) are supported.

  • ?: A conditional expression, as in C. 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.

  • || Logical ``or''.

  • && Logical ``and''.

  • ~ !~ Regular expression match, negated match.

  • < <= > >= != == The usual relational operators.

  • blank String concatenation.

  • + - Addition and subtraction.

  • * / % Multiplication, division, and modulus.

  • + - ! Unary plus, unary minus, and logical negation.

  • ^ Exponentiation (** may also be used, and **= for the assignment operator, but they are not specified in the POSIX standard).

  • ++ -- Increment and decrement, both prefix and postfix.

  • $ Field reference.
  • See section Expressions as Action Statements, for a full description of all the operators listed above. See section Examining Fields, for a description of the field reference operator.

    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
    	delete array[index]
    	exit [ expression ]
    	{ statements }

    See section Control Statements in Actions, for a full description of all the control statements listed above.

    I/O Statements

    The input/output statements are as follows:

  • getline Set $0 from next input record; set NF, NR, FNR.

  • getline <file Set $0 from next record of file; set NF.

  • getline var Set var from next input record; set NF, FNR.

  • getline var <file Set var from next record of file.

  • 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.

  • next file Stop processing the current input file. The next input record read comes from the next input file. FILENAME is updated, FNR is set to 1, 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.

  • print Prints the current record.

  • print expr-list Prints expressions.

  • print expr-list > file Prints expressions on file.

  • printf fmt, expr-list Format and print.

  • printf fmt, expr-list > file Format and print on file.
  • Other input/output redirections are also allowed. For print and printf, >> file appends output to the file, and | command writes on a pipe. In a similar fashion, command | getline pipes input into getline. getline returns 0 on end of file, and -1 on an error.

    See section Explicit Input with getline statement. See section Printing Output, for a full description of print and printf. Finally, see section The next Statement statement works.

    printf Summary

    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 A floating point number of the form [-]d.ddddddE[+-]dd.

  • %f A floating point number of the form [-]ddd.dddddd.

  • %g Use %e or %f conversion, whichever produces a shorter string, with nonsignificant zeros suppressed.

  • %o An unsigned octal number (again, an integer).

  • %s A character string.

  • %x An unsigned hexadecimal number (an integer).

  • %X Like %x, except use 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.

  • width The field should be padded to this width. If width has a leading zero, then the field is padded with zeros. Otherwise it is padded with blanks.

  • .prec A number indicating the maximum width of strings or digits to the right of the decimal point.
  • 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.

    Note Using printf Statements for Fancier Printing, for examples and for a more detailed description.

    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 the following files provide process related information about the running gawk program.

  • /dev/pid Reading this file returns the process ID of the current process, in decimal, terminated with a newline.

  • /dev/ppid Reading this file returns the parent process ID of the current process, in decimal, terminated with a newline.

  • /dev/pgrpid Reading this file returns the process group ID of the current process, in decimal, terminated with a newline.

  • /dev/user Reading this file returns a single record terminated with a newline. The fields are separated with blanks. The fields represent the following information:

  • $1 The value of the getuid system call.

  • $2 The value of the geteuid system call.

  • $3 The value of the getgid system call.

  • $4 The value of the getegid system call.
  • 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 by these names on your system.

    See section Standard I/O Streams, for a longer description that provides the motivation for this feature.

    Numeric Functions

    awk has the following predefined arithmetic functions:

  • atan2(y, x) returns the arctangent of y/x in radians.

  • cos(expr) returns the cosine in radians.

  • exp(expr) the exponential function.

  • int(expr) truncates to integer.

  • log(expr) the natural logarithm function.

  • rand() returns a random number between 0 and 1.

  • sin(expr) returns the sine 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.
  • String Functions

    awk has the following predefined string functions:

  • gsub(r, s, t) for each substring matching the regular expression r in the string t, substitute the string s, and return the number of substitutions. If t is not supplied, use $0.

  • index(s, t) returns the index of the string t in the string s, or 0 if t is not present.

  • length(s) returns the length of the string s. The length of $0 is returned if no argument is supplied.

  • match(s, r) returns the position in s where the regular expression r occurs, or 0 if r is not present, and sets the values of RSTART and RLENGTH.

  • split(s, a, r) splits the string s into the array a on the regular expression r, and returns the number of fields. If r is omitted, FS is used instead.

  • sprintf(fmt, expr-list) prints expr-list according to fmt, and returns the resulting string.

  • sub(r, s, t) this is just like gsub, but only the first matching substring is replaced.

  • substr(s, i, n) returns the n-character substring of s starting at i. If n is omitted, the rest of s 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. Nonalphabetic 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. Nonalphabetic characters are left unchanged.

  • system(cmd-line) Execute the command cmd-line, and return the exit status.
  • Built-in time functions

    The following two functions are available for getting the current time of day, and for formatting time stamps.

  • 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. See section Functions for Dealing with Time Stamps, for the details on the conversion specifiers that strftime accepts.
  • String Constants

    String constants in awk are sequences of characters enclosed between 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. (This feature should tell us something about language design by committee.) 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 1-, 2-, or 3-digit sequence of octal digits. Thus, "\033" is also a string containing the ASCII ESC (escape) character.

  • \c The literal character c.
  • 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 Constant Expressions.


    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 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, for a more complete description.

    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)

    This feature is marked as ``deprecated'' in the POSIX standard, and gawk will issue a warning about its use if -W lint is specified on the command line.

    The other feature is the use of 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. gawk will support this usage if -W posix has not been specified.