13.8 Alphabetical Summary of Commands

The following alphabetical list of statements and functions includes all that are available in gawk in Linux.

and(x,y)

Return the result of a bitwise AND of x and y.

asort(array[,outarray])

Sort the values of the specified array and assign numeric indices according to each value's new position in the array. If an output array is specified, the array to be sorted is copied to the new array and the new array is sorted, leaving the original array unchanged.

atan2(y,x)

Return the arctangent of y/x in radians.

break

Exit from a while or for loop.

close(filename-expr)
close(command-expr)

Close a file read by a getline command or a pipe. Takes as an argument the same expression that opened the pipe or file.

compl(value)

Return the bitwise complement of value.

continue

Begin next iteration of while or for loop without reaching the bottom.

cos(x)

Return the cosine of x, an angle in radians.

delete array[element]
delete array

Delete element of array. If no element is specified, all elements are deleted.

do
    body
while (expr)

Looping statement. Execute statements in body, then evaluate expr. If expr is true, execute body again.

exit

Do not execute remaining instruction, and read no new input. END procedures will be executed.

exp(arg)

Return the natural exponent of arg (the inverse of log).

fflush(filename)

Flush output to filename; default is the standard output.

for (i=lower ; i<=upper ; i++)
    command

While the value of variable i is in the range between lower and upper, do command. A series of commands must be put within braces. <= or any relational operator can be used; ++ or -- can be used to increment or decrement the variable.

for (item  in array)
     command

For each item in an associative array, execute command. Multiple commands must be put inside braces. Refer to each element of the array as array[item]. Elements of gawk arrays are stored in an order that enables access of any element in essentially equivalent time. This order may appear to be indiscriminate; if the output is desired in sorted order, you must pipe it through the sort command.

function name(parameter-list) {
     statements
}

Create name as a user-defined function consisting of gawk statements that apply to the specified list of parameters. Gawk accepts func as a synonymn for function.

gensub(r,s,n,t)

Substitute s for the nth match of regular expression r in the string t. Leave t unchanged, but return new string as the result. If n is g or G, change all matches. If t is not supplied, it defaults to $0.

getline [varhairsp;] [<file]
command | getline [var]

The first form reads input from file or the next file on the command line, and the second form reads the output of command. Both forms read one line at a time, and each time the statement is executed it gets the next line of input. The line of input is assigned to $0 and is parsed into fields, setting NF, NR, and FNR. If var is specified, the result is assigned to var, and neither $0 nor NF is changed. Thus, if the result is assigned to a variable, the current line does not change. getline is actually a function, and it returns 1 if it reads a record successfully, 0 at EOF, and -1 if for some reason it is unsuccessful.

gsub(r,s,t)

Globally substitute s for each match of the regular expression r in the string t. Return the number of substitutions. If t is not supplied, it defaults to $0.

if (condition)
    command1
[else
    command2]

If condition is true, execute command1; otherwise, execute command2. condition can be an expression using any of the relational operators <, <=, = =, !=, >=, or >, as well as the pattern-matching operator ~. A series of commands must be put within braces.

Example

The following line determines whether the first word in each line starts with A, uppercase or lowercase:

if ($1 ~ /[Aa]*/)

index(substr,str)

Return the position of a substring in a string. Returns 0 if substr is not contained in str.

int(arg)

Return the integer part of arg.

length(arg)

Return the length of arg. If arg is not supplied, $0 is assumed.

log(arg)

Return the natural logarithm of arg (the inverse of exp).

lshift(value, n)

Bitwise command. Return the result of shifting value to the left by n bits.

match(s,r)

Return position in s where regular expression r first matches, or 0 if no occurrences are found. Sets the value of RSTART and RLENGTH.

mktime(datestring)

Convert a date given in the form YYYY MM DD HH MM SS [DST] into a timestamp. The time is assumed to be in the local time zone. The daylight savings time value, DST, may be 1 (true), 0 (false) or -1 (autodetect).

next

Read next input line and start new cycle through pattern/procedures statements.

nextfile

Skip to the next file on the gawk command line and start new cycle through pattern/procedures statements.

or(x,y)

Return the result of a bitwise OR of x and y.

print [args] [destination]

Print args on output. Literal strings must be quoted. Fields are printed in the order they are listed. If separated by commas in the argument list, they are separated in the output by the character specified by OFS. If separated by spaces, they are concatenated in the output. destination is a shell redirection or pipe expression (e.g., > file) that redirects the default output.

printf[format [, expressions]]

Formatted print statement. Expressions or variables can be formatted according to instructions in the format argument. The number of expressions must correspond to the number specified in the format sections.

format follows the conventions of the C-language printf statement. Here are a few of the most common formats:

%s

A string.

%d

A decimal number.

%n.mf

A floating-point number. n is the total number of digits; m is the number of digits after the decimal point.

%[-]nc

n specifies minimum field length for format type c. - left-justifies value in field; otherwise, value is right-justified.

Field widths are adjustable. For example, %3.2f limits a floating-point number to a minimum width of three digits, with two digits after the decimal point.

format also can contain embedded escape sequences, \n (newline) and \t (tab) being the most common. Spaces and literal text can be placed in the format argument by quoting the entire argument. If there are multiple expressions to be printed, multiple formats should be specified.

Example

Using the script:

{printf ("The sum on line %s is %d.\n", NR, $1+$2)}

the following input line:

5   5

produces this output, followed by a newline:

The sum on line 1 is 10.

rand( )

Generate a random number between 0 and 1. This function returns the same series of numbers each time the script is executed, unless the random number generator is seeded using the srand function.

return [expr]

Used at end of user-defined functions to exit function, returning the value of expr.

rshift(value, n)

Bitwise command. Return the result of shifting value to the right by n bits.

sin(x)

Return the sine of x, an angle in radians.

split(string,array[,sep])

Split string into elements of array array[1],...,array[n]. The string is split at each occurrence of separator sep. If sep is not specified, FS is used. If sep is a null string, a split is performed on every character. The number of array elements created is returned.

sprintf [format[, expression(s)]]

Return the value of one or more expressions using the specified format (see printf). Data is formatted but not printed.

sqrt(arg)

Return square root of arg.

srand(expr)

Use expr to set a new seed for random number generator. Default is time of day.

strftime([format[,timestamp]])

Format timestamp according to format. Return the formatted string. The timestamp is a time-of-day value in seconds since midnight, January 1, 1970, UTC. The format string is similar to that of sprintf. (See the example for systime.) If timestamp is omitted, it defaults to the current time. If format is omitted, it defaults to a value that produces output similar to that of date.

strtonum(str)

Return the numeric value of string str. If str begins with 0 or 0x it will be treated as an octal or hexadecimal number. Trailing letters on str are ignored.

sub(r,s,t)

Substitute s for first match of the regular expression r in the string t. Return 1 if successful; 0 otherwise. If t is not supplied, the default is $0.

substr(string,m[,n])

Return substring of string beginning at character position m and consisting of the next n characters. If n is omitted, include all characters to the end of the string.

system(command)

Execute the specified shell command and return its status. The status of the command that is executed typically indicates success (1), completion (0), or unexpected error (-1). The output of the command is not available for processing within the gawk script.

systime( )

Return number of seconds since midnight UTC, January 1, 1970.

Example

Log the start and end times of a data processing program:

BEGIN {
      now = systime( )
      mesg = strftime("Started at %m/%d/%Y %H:%M:%S", now)
      print mesg
}
process data ...
END {
      now = systime( )
      mesg = strftime("Ended at %m/%d/%Y %H:%M:%S", now)
      print mesg
}

tolower(str)

Translate all uppercase characters in str to lowercase and return the new string.

toupper(str)

Translate all lowercase characters in str to uppercase and return the new string.

while (condition)
  command

Execute command while condition is true (see if for a description of allowable conditions). A series of commands must be put within braces.

xor(x,y)

Return the result of a bitwise XOR of x and y.