[Appendix B] B.3 Command Summary for awk
Author: Dale Dougherty & Arnold Robbins
Date: 1998-08-03T21:06:51Z

#

| Appendix B Quick Reference for awk |

## B.3 Command Summary for awk

The following alphabetical list of statements and functions includes all that are available in POSIX awk, nawk, or gawk. See Chapter 11, A Flock of awks, for extensions available in different implementations.

`atan2()`

  `atan2`(y, x)

  Returns the arctangent of y/x in radians.

`break`

  Exit from a `while`, `for`, or `do` loop.

`close()`

  `close`(filename-expr)

  `close`(command-expr)

  In most implementations of awk, you can only have a limited number of files and/or pipes open simultaneously. Therefore, awk provides a `close()` function that allows you to close a file or a pipe. It takes as an argument the same expression that opened the pipe or file. This expression must be identical, character by character, to the one that opened the file or pipe - even whitespace is significant.

`continue`

  Begin next iteration of `while`, `for`, or `do` loop.

`cos()`

  `cos`(x)

  Return cosine of x in radians.

`delete`

  `delete` array[element]

  Delete element of an array.

`do`

  `do`

  body

  `while` (expr)

  Looping statement. Execute statements in body then evaluate expr and if true, execute body again.

`exit`

  `exit` [expr]

  Exit from script, reading no new input. The `END` rule, if it exists, will be executed. An optional expr becomes awk's return value.

`exp()`

  `exp`(x)

  Return exponential of x (e ^ x).

`for`

  `for` (init-expr; test-expr; incr-expr) statement

  C-style looping construct. init-expr assigns the initial value of the counter variable. test-expr is a relational expression that is evaluated each time before executing the statement. When test-expr is false, the loop is exited. incr-expr is used to increment the counter variable after each pass.

  `for` (item `in` array) statement

  Special loop designed for reading associative arrays. For each element of the array, the statement is executed; the element can be referenced by array[item].

`getline`

  Read next line of input.

  `getline` [var] [<file]

  command | `getline` [var]

  The first form reads input from file 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 it is parsed into fields, setting `NF`, `NR`, and `FNR`. If var is specified, the result is assigned to var and the $0 is not 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 if end-of-line is encountered, and -1 if for some reason it is otherwise unsuccessful.

`gsub()`

  `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, defaults to $0.

`if`

  `if` (expr) statement1

  [ `else` statement2 ]

  Conditional statement. Evaluate expr and, if true, execute statement1; if `else` clause is supplied, execute statement2 if expr is false.

`index()`

  `index`(str, substr)

  Return position (starting at 1) of substring in string.

`int()`

  `int`(x)

  Return integer value of x by truncating any digits following a decimal point.

`length()`

  `length`(str)

  Return length of string, or the length of $0 if no argument.

`log()`

  `log`(x)

  Return natural logarithm (base e) of x.

`match()`

  `match`(s, r)

  Function that matches the pattern, specified by the regular expression r, in the string s and returns either the position in s where the match begins, or 0 if no occurrences are found. Sets the values of `RSTART` and `RLENGTH` to the start and length of the match, respectively.

`next`

  Read next input line and begin executing script at first rule.

`print`

  `print` [ output-expr ] [ dest-expr ]

  Evaluate the output-expr and direct it to standard output followed by the value of `ORS`. Each output-expr is separated by the value of `OFS`. dest-expr is an optional expression that directs the output to a file or pipe. "> file" directs the output to a file, overwriting its previous contents. ">> file" appends the output to a file, preserving its previous contents. In both of these cases, the file will be created if it does not already exist. "| command" directs the output as the input to a system command.

`printf`

  `printf` (format-expr [, expr-list ]) [ dest-expr ]

  An alternative output statement borrowed from the C language. It has the ability to produce formatted output. It can also be used to output data without automatically producing a newline. format-expr is a string of format specifications and constants; see next section for a list of format specifiers. expr-list is a list of arguments corresponding to format specifiers. See the `print` statement for a description of dest-expr.

`rand()`

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

  `return` [expr]

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

`sin()`

  `sin`(x)

  Return sine of x in radians.

`split()`

  `split`(str, array, sep)

  Function that parses string into elements of array using field separator, returning number of elements in array. Value of `FS` is used if no field separator is specified. Array splitting works the same as field splitting.

`sprintf()`

  `sprintf` (format-expr [, expr-list ] )

  Function that returns string formatted according to `printf` format specification. It formats data but does not output it. format-expr is a string of format specifications and constants; see the next section for a list of format specifiers. expr-list is a list of arguments corresponding to format specifiers.

`sqrt()`

  `sqrt`(x)

  Return square root of x.

`srand()`

  `srand`(expr)

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

`sub()`

  `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, defaults to $0.

`substr()`

  `substr`(str, beg, len)

  Return substring of string str at beginning position beg, and the characters that follow to maximum specified length len. If no length is given, use the rest of the string.

`system()`

  `system`(command)

  Function that executes the specified command and returns its status. The status of the executed command typically indicates success or failure. A value of 0 means that the command executed successfully. A non-zero value, whether positive or negative, indicates a failure of some sort. The documentation for the command you're running will give you the details. The output of the command is not available for processing within the awk script. Use "command `| getline`" to read the output of a command into the script.

`tolower()`

  `tolower`(str)

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

  > [3] Very early versions of nawk, such as that in SunOS 4.1.x, don't support `tolower()` and `toupper()`. However, they are now part of the POSIX specification for awk.

`toupper()`

  `toupper`(str)

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

`while`

  `while` (expr) statement

  Looping construct. While expr is true, execute statement.

### B.3.1 Format Expressions Used in printf and sprintf

A format expression can take three optional modifiers following "%" and preceding the format specifier:

> `%-`width.precision format-specifier

The width of the output field is a numeric value. When you specify a field width, the contents of the field will be right-justified by default. You must specify "-" to get left-justification. Thus, "%-20s" outputs a string left-justified in a field 20 characters wide. If the string is less than 20 characters, the field will be padded with spaces to fill.

The precision modifier, used for decimal or floating-point values, controls the number of digits that appear to the right of the decimal point. For string formats, it controls the number of characters from the string to print.

You can specify both the width and precision dynamically, via values in the `printf` or `sprintf` argument list. You do this by specifying asterisks, instead of specifying literal values.

>     printf("%*.*g\n", 5, 3, myvar);

In this example, the width is 5, the precision is 3, and the value to print will come from `myvar`. Older versions of nawk may not support this.

Note that the default precision for the output of numeric values is "%.6g." The default can be changed by setting the system variable `OFMT`. This affects the precision used by the `print` statement when outputting numbers. For instance, if you are using awk to write reports that contain dollar values, you might prefer to change `OFMT` to "%.2f."

The format specifiers, shown in Table 13.7, are used with `printf` and `sprintf` statements.

Table B.6: Format Specifiers Used in printf
Character | Description
--- | ---
c | ASCII character.
d | Decimal integer.
i | Decimal integer. Added in POSIX.
e | Floating-point format ([-]d.precision `e`[+-]dd).
E | Floating-point format ([-]d.precision `E`[+-]dd).
f | Floating-point format ([-]ddd.precision).
g | `e` or `f` conversion, whichever is shortest, with trailing zeros removed.
G | `E` or `f` conversion, whichever is shortest, with trailing zeros removed.
o | Unsigned octal value.
s | String.
x | Unsigned hexadecimal number. Uses `a`-`f` for 10 to 15.
X | Unsigned hexadecimal number. Uses `A`-`F` for 10 to 15.
% | Literal %.

Often, whatever format specifiers are available in the system's sprintf(3) subroutine are available in awk.

The way `printf` and `sprintf()` do rounding will often depend upon the system's C sprintf(3) subroutine. On many machines, sprintf rounding is "unbiased," which means it doesn't always round a trailing ".5" up, contrary to naive expectations. In unbiased rounding, ".5" rounds to even, rather than always up, so 1.5 rounds to 2 but 4.5 rounds to 4. The result is that if you are using a format that does rounding (e.g., `"%.0f"`) you should check what your system does. The following function does traditional rounding; it might be useful if your awk's `printf` does unbiased rounding.

>     # round --- do normal rounding
>     #	Arnold Robbins, arnold@gnu.ai.mit.edu
>     #	Public Domain
>     function round(x,       ival, aval, fraction)
>     {
>             ival = int(x)	# integer part, int() truncates
>     	# see if fractional part
>     	if (ival == x)	# no fraction
>     		return x
>     	if (x < 0) {
>     		aval = -x	# absolute value
>     		ival = int(aval)
>     		fraction = aval - ival
>     		if (fraction >= .5)
>     			return int(x) - 1		# -2.5 --> -3
>     		else
>     			return int(x)		# -2.3 --> -2
>     	} else {
>     		fraction = x - ival
>     		if (fraction >= .5)
>     			return ival + 1
>     		else
>     			return ival
>     	}
>     }

B.2 Language Summary for awk |  | C. Supplement for Chapter 12