GAWK(1)

📦
version 5.3.2 · 9 versions
, in fedora 43, fedora 44, opensuse-leap 16.0, ubuntu questing

💖 gawk(1) — the GAWK(1) manual 💖

okay bestie, gather around 🫶 this is the gawk man page, and it's literally the cutest pattern scanning and processing language ever ✨

✨ NAME ✨

gawk - pattern scanning and processing language 🦋

✨ SYNOPSIS ✨

gawk [ POSIX or GNU style options ] -f program-file [ -- ] file ...
gawk [ POSIX or GNU style options ] [ -- ] program-text file ...

🎀 README FIRST 🎀

this page is a courtesy, not the full story 💅 the One Source Of Truth for gawk is the Texinfo manual, which you can read online in several formats at https://www.gnu.org/software/gawk/manual. it might also be installed in the Info subsystem on your machine, so you can reach it through the info(1) command 📚

if this man page ever contradicts the Texinfo manual, the manual wins. no debate 🙅‍♀️

🌸 DESCRIPTION 🌸

okay so gawk is the GNU Project's version of the AWK programming language 🧚 it follows the definition of the language in the POSIX 1003.1 standard. this version is based on the description in The AWK Programming Language, by Aho, Kernighan, and Weinberger. gawk also gets the extra features from the current version of Brian Kernighan's awk, plus a bunch of GNU-specific extensions. so iconic 👑

the command line is made of options for gawk itself, the AWK program text (unless you handed it over with -f or --include), and the values you want to pass in through the pre-defined AWK variables ARGC and ARGV ✨

🧚 PREFACE 🧚

this page is intentionally as terse as possible 🙈 the full details live in GAWK: Effective AWK Programming, so go there for the whole story on any feature. wherever it's possible, you'll also find links to the online version of the manual 💜

🦋 OPTION FORMAT 🦋

gawk options can be either the traditional POSIX-style single-letter ones, or GNU-style long options 💅 POSIX options start with a single -, while long options start with --. long options exist for both GNU-specific features and POSIX-mandated ones, so nobody gets left out 🫶

gawk-specific options are usually written in long-option form. when you give an argument to a long option, you can either join it to the option with an = sign (no spaces in between), or put it in the next command line argument. you can also abbreviate long options, as long as the abbreviation is still unique 🍓

every long option also has a matching short option, so you can use that functionality from inside #! executable scripts 🔥

👑 OPTIONS 👑

okay this is the main event 🎀 gawk takes the following options. the standard ones come first, and then the ones for gawk extensions, sorted alphabetically by short option ✨

  • -f program-file, --file program-file — read the AWK program source from the file program-file, instead of grabbing it from the first command line argument. you can use -f more than once 💖 files read with -f are treated as if they begin with an implicit @namespace "awk" statement.
  • -F fs, --field-separator fs — uses fs as the input field separator, which is the value of the FS predefined variable 🌈
  • -v var=val, --assign var=val — assigns the value val to the variable var before the program starts running. these variable values are ready and waiting in the BEGIN rule of an AWK program 🧁
  • -b, --characters-as-bytes — treats all input data as single-byte characters 🤓 the --posix option overrides this one, so keep that in mind 💀
  • -c, --traditional — runs in compatibility mode. in compatibility mode, gawk acts exactly like Brian Kernighan's awk, and none of the GNU-specific extensions get recognized 🙃
  • -C, --copyright — prints the short version of the GNU copyright information message to standard output, then exits successfully 🎀
  • -d[file], --dump-variables[=file] — prints a sorted list of global variables, their types, and their final values to file. the default file is awkvars.out in the current directory 📝
  • -D[file], --debug[=file] — turns on debugging for AWK programs 🔍 by default the debugger reads commands interactively from the keyboard (standard input). the optional file argument points to a file full of debugger commands that run non-interactively. in this mode, gawk loads the AWK source code and then prompts you for debugging commands. gawk can only debug AWK program source handed over with -f and --include. the debugger is documented in GAWK: Effective AWK Programming, which you can find at https://www.gnu.org/software/gawk/manual/html_node/Debugger.html#Debugger 💜
  • -e program-text, --source program-text — uses program-text as the AWK program source code. every argument you pass with -e is treated as if it begins with an implicit @namespace "awk" statement 🧚
  • -E file, --exec file — works like -f, except this option gets processed last 🦋 use it with #! scripts, especially for CGI applications, so nobody sneaks options or source code (!) into the command line from a URL. this option also turns off command-line variable assignments 🔒
  • -g, --gen-pot — scans and parses the AWK program, then writes a GNU .pot (Portable Object Template) format file to standard output with entries for every localizable string in the program. the program itself never actually runs 🌸
  • -h, --help — prints a relatively short summary of the available options to standard output. per the GNU Coding Standards, these options make gawk exit immediately and successfully 👋
  • -i include-file, --include include-file — loads an awk source library 📚 it searches for the library using the AWKPATH environment variable. if that first search fails, it tries again after adding the .awk suffix. the file only gets loaded once (duplicates are eliminated), and the code does not count as the main program source. files read with --include are treated as if they begin with an implicit @namespace "awk" statement 🫶
  • -I, --trace — prints the internal byte code names as they run while the program executes 👀 the trace goes to standard error, and every "op code" shows up with a + sign in front of it ✨
  • -k, --csv — turns on CSV special processing. check out Comma Separated Values, below, for more detail 📊
  • -l lib, --load lib — loads a gawk extension from the shared library lib. it searches for the library using the AWKLIBPATH environment variable. if the first search fails, it tries again after adding the default shared library suffix for your platform. the library's initialization routine is expected to be named dl_load() 🧩
  • -L [value], --lint[=value] — gives you warnings about constructs that are dubious or non-portable to other AWK implementations 🕵️‍♀️ for the list of possible values for value, see https://www.gnu.org/software/gawk/manual/html_node/Options.html#Options
  • -M, --bignum — forces arbitrary precision arithmetic on numbers 🧮 this option does nothing if gawk wasn't compiled to use the GNU MPFR and GMP libraries. (in that case, gawk issues a warning.)
NOTE: this feature is on parole 🥺 the primary gawk maintainer is no longer supporting it, although there's one member of the development team who still is. if that changes, the feature will be removed from gawk.
  • -n, --non-decimal-data — recognizes octal and hexadecimal values in input data. use this option with great caution! 💀
  • -N, --use-lc-numeric — forces gawk to use the locale's decimal point character when it parses input data 🌍
  • -o[file], --pretty-print[=file] — writes a pretty printed version of the program to file. the default file is awkprof.out in the current directory. this option implies --no-optimize 💅
  • -O, --optimize — turns on gawk's default optimizations for the internal representation of the program ⚡ this option is on by default, so you're already set 💖
  • -p[prof-file], --profile[=prof-file] — starts a profiling session and sends the profiling data to prof-file. the default is awkprof.out in the current directory. the profile holds execution counts for each statement in the program, shown in the left margin, plus function call counts for each user-defined function. gawk runs more slowly in this mode 🐢 this option implies --no-optimize 📈
  • -P, --posix — turns on compatibility mode and disables a bunch of common extensions 🤍
  • -r, --re-interval — enables interval expressions in regular expression matching. interval expressions are already on by default, but this option is still around for backwards compatibility 🕰️
  • -s, --no-optimize — turns off gawk's default optimizations for the internal representation of the program 🙅‍♀️
  • -S, --sandbox — runs gawk in sandbox mode 🏖️ this disables the system() function, input redirection with getline, output redirection with print and printf, and loading dynamic extensions. command execution through pipelines is also disabled 🔐
  • -t, --lint-old — gives you warnings about constructs that aren't portable to the original version of UNIX awk 🏛️
  • -V, --version — prints version information for this particular copy of gawk to standard output. it's super useful when you're reporting bugs 🐛 per the GNU Coding Standards, these options make gawk exit immediately and successfully ✨
  • -- — signals the end of options. this lets further arguments meant for the AWK program itself start with a - 🫶

in compatibility mode, any other options get flagged as invalid, but they're otherwise ignored 🙃 in normal operation, as long as program text has been supplied, unknown options get passed on to the AWK program through the ARGV array so it can handle them itself 🧚

for POSIX compatibility, you can use the -W option, followed by the name of a long option 💜

✨ AWK PROGRAM EXECUTION ✨

okay so an AWK program is basically a sequence of optional directives, pattern-action statements, and optional function definitions 💅 the shapes look like this:

@include "filename"
@load "filename"
@namespace "name"
pattern   { action statements }
function name(parameter list) { statements }

gawk first grabs the program source from the program-file(s) if you gave any, from the arguments to --source, or from the first non-option argument on the command line 🎀 you can use -f and --source multiple times on the command line, and gawk reads the program text as if all the program-files and command line source texts were stuck together into one big happy string 🫶

lines starting with @include let you pull other source files into your program 🧚 it's the same as using the --include option.

lines starting with @load let you load extension functions into your program ✨ same deal, it's equivalent to the --load option.

the environment variable AWKPATH is the search path gawk uses when hunting down source files named with -f and --include 🗺️ if that variable doesn't exist, the default path is ".:/usr/local/share/awk". (the actual directory may vary depending on how gawk was built and installed, so don't panic if yours looks different 🙈) also, if a file name given to -f contains a “/” character, no path search happens at all, gawk just goes straight to it.

the environment variable AWKLIBPATH is the search path for source files named with --load 🌈 if it doesn't exist, the default path is "/usr/local/lib/gawk". (again, the actual directory may vary based on how gawk was built and installed 💜)

here's the order gawk runs an AWK program, bestie, so pay attention 👑

  1. first, all the variable assignments given with the -v option get done 🌸
  2. next, gawk compiles the program into an internal form 🔧
  3. then gawk runs the code in the BEGIN rule(s), if there are any, and then starts reading each file named in the ARGV array (up to ARGV[ARGC-1]) 📖
  4. if there are no files named on the command line, gawk reads the standard input instead 🎤

if a filename on the command line looks like var=val, it gets treated as a variable assignment, meaning the variable var gets set to the value val 💅 this happens after any BEGIN rule(s) have run, so keep that in mind.

if the value of a particular element of ARGV is empty (""), gawk just skips right over it 🙃

for each input file, if a BEGINFILE rule exists, gawk runs its code before it processes the contents of that file 🍓 and similarly, gawk runs the code in ENDFILE rules after it's done processing the file.

for each record in the input, gawk checks whether it matches any pattern in the AWK program 🔍 every pattern the record matches gets its associated action run. patterns get tested in the order they show up in the program, so order matters, periodt.

finally, once all the input is used up, gawk runs the code in the END rule(s), if any 🏁

📂 Command Line Directories

okay so according to POSIX, files named on the awk command line are supposed to be text files 📄 if they're not, the behavior is “undefined”, which is the programming equivalent of "who knows what's gonna happen" 💀 most versions of awk treat a directory on the command line as a fatal error, so yikes.

gawk is way nicer about it 🦋 for gawk, a directory on the command line just produces a warning, and then gets skipped. BUT if either of the --posix or --traditional options is given, gawk goes back to treating directories on the command line as a fatal error, so be careful if you're going for strict vibes 😭

🌸 VARIABLES, RECORDS AND FIELDS 🌸

AWK variables are dynamic, which means they come into existence the moment they're first used 🧚 their values are either floating-point numbers or strings, or both, depending on how you use them. gawk also lets variables have regular-expression type, which is so iconic 💜 AWK has one-dimensional arrays, and you can simulate multiple dimensions, but gawk gives you true arrays of arrays too 👑 several pre-defined variables get set while a program runs. they're described as needed and summarized below ✨

📝 Records

normally, records are separated by newline characters 🍓 you can control how records get separated by assigning values to the built-in variable RS. for all the details, check out https://www.gnu.org/software/gawk/manual/html_node/Records.html 🫶

🧩 Fields

as each input record is read, gawk splits it into fields, using the value of the FS variable as the field separator 🔪 FIELDWIDTHS and FPAT can also be used to control input field splitting, so there's more than one way to slice it 🎀 see the details starting at https://www.gnu.org/software/gawk/manual/html_node/Fields.html.

each field in the input record can be referenced by its position: $1, $2, and so on 💖 $0 is the whole record, including any leading and trailing whitespace.

the variable NF is set to the total number of fields in the input record 🔢

references to non-existent fields (aka fields after $NF) produce the null string, so nothing scary, just empty 🫧 BUT assigning to a non-existent field (like $(NF+2) = 5) increases the value of NF, creates any intervening fields with the null string as their values, and causes $0 to be recomputed, with the fields separated by the value of OFS ✨ referencing negative numbered fields causes a fatal error, so don't do that 🚫

decrementing NF makes the values of fields past the new value get lost 😭 and $0 gets recomputed too, with the fields separated by the value of OFS. that's permanent, so be careful!

assigning a value to an existing field means the whole record gets rebuilt when $0 is referenced 🔁 similarly, assigning a value to $0 causes the record to be resplit, creating new values for the fields. it's giving recycling, but make it cute 🌈

📊 Comma Separated Values

when you run gawk with either the -k or the --csv option, it does NOT use regular record determination and field splitting like we just talked about 🙈 instead, records are terminated by unquoted newlines, and fields are separated by commas 🍬 double-quotes can enclose fields containing commas, newlines, or doubled double-quotes. for more details, see https://www.gnu.org/software/gawk/manual/html_node/Comma-Separated-Fields.html 💅

🧾 Built-in Variables

here are gawk's built-in variables! this list is purposely terse, so if you want the full tea, look at https://www.gnu.org/software/gawk/manual/html_node/Built_002din-Variables ☕

  • ARGC — the number of command line arguments 🔢
  • ARGIND — the index in ARGV of the current file being processed 📂
  • ARGV — array of command line arguments. it's indexed from 0 to ARGC - 1 🧾
  • BINMODE — on non-POSIX systems, this specifies use of “binary” mode for all file I/O 💾 for the details, see https://www.gnu.org/software/gawk/manual/html_node/PC-Using.html.
  • CONVFMT — the conversion format for numbers, "%.6g" by default 🎀
  • ENVIRON — an array containing the values of the current environment 🌿 it's indexed by the environment variables, with each element being the value of that variable.
  • ERRNO — if a system error happens while doing a redirection for getline, during a read for getline, or during a close(), then ERRNO gets set to a string describing the error 😬 the value is subject to translation in non-English locales, so it might look different for your bestie in another language 🌍
  • FIELDWIDTHS — a whitespace-separated list of field widths 📏 when set, gawk parses the input into fixed-width fields, instead of using FS as the field separator. each field width can optionally be preceded by a colon-separated value specifying how many characters to skip before the field starts 🦘
  • FILENAME — the name of the current input file 📁 if no files are specified on the command line, FILENAME is "-". BUT FILENAME is undefined inside the BEGIN rule (unless it's set by getline), so don't rely on it there 🙅
  • FNR — the input record number in the current input file 🔖
  • FPAT — a regular expression describing the contents of the fields in a record 🧶 when set, gawk parses the input into fields where the fields match the regular expression, instead of using FS as the field separator.
  • FS — the input field separator, a space by default ✂️ see https://www.gnu.org/software/gawk/manual/html_node/Field-Separators.html for the details.
  • 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. hands off! 🙅
  • IGNORECASE — controls the case-sensitivity of all regular expression and string operations 🔠 see https://www.gnu.org/software/gawk/manual/html_node/Case_002dsensitivity.html for details.
  • LINT — provides dynamic control of the --lint option from inside an AWK program 🧹
  • 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, "%.6g" by default 🖨️
  • OFS — the output field separator, a space by default 🫧
  • ORS — the output record separator, by default a newline ⏎
  • PREC — the working precision of arbitrary precision floating-point numbers, 53 by default 🧮
  • PROCINFO — the elements of this array give you access to information about the running AWK program 🕵️ see https://www.gnu.org/software/gawk/manual/html_node/Auto_002dset for the details.
  • ROUNDMODE — the rounding mode for arbitrary precision arithmetic on numbers, by default "N" (IEEE-754 roundTiesToEven mode) 🎯 see https://www.gnu.org/software/gawk/manual/html_node/Setting-the-rounding-mode for the details.
  • RS — the input record separator, by default a newline 📜
  • RT — the record terminator 🏁 gawk sets RT to the input text that matched the character or regular expression specified by RS.
  • RSTART — the index of the first character matched by match(); 0 if there's no match 🎯
  • RLENGTH — the length of the string matched by match(); -1 if there's no match 📏
  • SUBSEP — the string used to separate multiple subscripts in array elements, by default "\034" 🧷
  • SYMTAB — an array whose indices are the names of all currently defined global variables and arrays in the program 🗂️
you may not use the delete statement with the SYMTAB array, nor assign to elements with an index that isn't a variable name. no sneaky stuff! 🚫
  • TEXTDOMAIN — the text domain of the AWK program, used to find the localized translations for the program's strings 🌐

Arrays

okay so arrays get subscripted with an expression inside square brackets, [ and ]. 🧺 If that expression is an expression list (expr, expr ...), the subscript becomes one big string: the (string) value of each expression, glued together with whatever the SUBSEP variable holds in between. This is how gawk fakes multiply dimensioned arrays, and it's honestly so clever 🧠✨ For example:

i = "A"; j = "B"; k = "C"
x[i, j, k] = "hello, world\n"

that assigns "hello, world\n" to the element of x indexed by the string "A\034B\034C". Every array in AWK is associative, meaning it's indexed by string values 💅

The special in operator checks whether an array has a particular index 👀

if (val in array)
     print array[val]

If the array has multiple subscripts, use (i, j) in array instead.

The in construct can also be used in a for loop to step through every element of an array. BUT the (i, j) in array construct only works in tests, not in for loops, so don't try it there 🙈

You can delete one element from an array with the delete statement. You can also wipe the entire array by using delete and just the array name, no subscript needed 🧹

gawk supports true multidimensional arrays 💖 It does not require them to be "rectangular" the way C or C++ does, so your rows can be all different lengths and it's totally fine. For the deep dive, check https://www.gnu.org/software/gawk/manual/html_node/Arrays

Namespaces

gawk has a simple namespace facility 🎀 It helps you work around the fact that every variable in AWK is global, which can get messy fast.

A qualified name is two simple identifiers joined by a double colon, ::. The left-hand identifier is the namespace, and the right-hand one is the variable living inside it. Simple (non-qualified) names all belong to the "current" namespace, and the default namespace is awk. BUT simple identifiers made up of only uppercase letters get forced into the awk namespace, even if your current namespace is something else. Iconic 👑

You switch the current namespace with an @namespace "name" directive.

The standard predefined builtin function names are NOT allowed as namespace names. The names of extra functions that gawk provides, though, can be used as namespace names or as simple identifiers in other namespaces. For more details, see https://www.gnu.org/software/gawk/manual/html_node/Namespaces.html#Namespaces.

Variable Typing And Conversion

Variables and fields can be (floating point) numbers, strings, or both 🌈 They can also be regular expressions. What a value is depends on where it's used: in a numeric expression it gets treated as a number, and when it's used as a string it gets treated as a string. The context decides, bestie 💜

To force a variable to act like a number, add zero to it. To force it to act like a string, concatenate it with the null string "".

Uninitialized variables have the numeric value zero and the string value "" (the null, or empty, string) 🫧

When a string needs to become a number, gawk uses strtod(3) to do it. A number becomes a string by using the value of CONVFMT as a format string for sprintf(3), with the variable's numeric value as the argument. Here's the twist: even though every number in AWK is floating-point, integral values always get converted as integers ✨

Comparisons in gawk go like this. If both values are numeric, they're compared numerically. If one value is numeric and the other is a "numeric string," the comparison is also numeric. Otherwise, the numeric value gets converted to a string and a string comparison happens. Two strings are always compared as strings, obviously 🙄

Quick heads up: string constants like "57" are NOT numeric strings. They're just string constants. The idea of a "numeric string" only applies to fields, getline input, FILENAME, ARGV elements, ENVIRON elements, and the elements of an array created by split() or patsplit() that are numeric strings. The vibe is basically this: user input, and only user input, that looks numeric should get treated that way 🫶

Octal and Hexadecimal Constants

You can use C-style octal and hexadecimal constants right in your AWK program source 🔢 For example, the octal value 011 is equal to decimal 9, and the hexadecimal value 0x11 is equal to decimal 17. Math is serving 🧮

String Constants

String constants in AWK are sequences of characters wrapped in double quotes, like "value". Inside strings, certain escape sequences get recognized, same as in C. For the details, see https://www.gnu.org/software/gawk/manual/html_node/Escape-Sequences 📝

Regexp Constants

A regular expression constant is a sequence of characters wrapped in forward slashes, like /value/. 🎯

The escape sequences from the manual also work inside constant regular expressions. For example, /[ \t\f\n\r\v]/ matches whitespace characters 🫧

gawk also has strongly typed regular expression constants 🌈 These get written with a leading @ symbol, like so: @/value/. You can assign these constants to scalars (variables and array elements) and pass them to user-defined functions. Any variable that got assigned one this way has regular expression type. Very fancy, very intentional 💅

PATTERNS AND ACTIONS

AWK is a line-oriented language 📜 The pattern comes first, and then the action. Action statements are enclosed in { and }. You can leave out the pattern, or leave out the action, but not both, obviously 🙃 If the pattern is missing, the action runs for every single record of input. A missing action is the same as:

{ print }

which prints the entire record.

Comments begin with the # character and keep going until the end of the line 💬 Empty lines are fine for separating statements. Normally a statement ends at a newline, EXCEPT for lines ending in a comma, {, ?, :, &&, or ||. Lines ending in do or else also automatically continue onto the next line. Everywhere else, you can continue a line by ending it with a \, and then the newline gets ignored. Just know that a \ after a # is not special 🙈

You can cram multiple statements onto one line by separating them with a ;. This works both for the statements inside the action part of a pattern-action pair (the usual situation) and for the pattern-action statements themselves 🍓

Patterns

AWK patterns can be any one of the following:

BEGIN
END
BEGINFILE
ENDFILE
/regular expression/
relational expression
pattern && pattern
pattern || pattern
pattern ? pattern : pattern
(pattern)
! pattern
pattern1, pattern2

BEGIN and END are two special kinds of patterns that don't get tested against the input 🧚 The action parts of all the BEGIN patterns get merged, as if every statement had been written in one single BEGIN rule. They run before any input is read. Same deal with END: all the END rules get merged, and they run once all the input is used up (or when an exit statement runs). BEGIN and END can't be combined with other patterns in pattern expressions, and they can't have missing action parts either 🚫

BEGINFILE and ENDFILE are extra special patterns whose actions run before the first record of each command-line input file is read, and after the last record of each file. Inside the BEGINFILE rule, the value of ERRNO is the empty string if the file opened successfully. Otherwise, something's wrong with the file, and you should use nextfile to skip it. If you don't do that, gawk throws its usual fatal error for files that can't be opened 😭

For /regular expression/ patterns, the associated statement runs for each input record that matches the regular expression. Regular expressions here are basically the same as the ones in egrep(1). For the details on regular expressions, see https://www.gnu.org/software/gawk/manual/html_node/Regexp.html 🔍

A relational expression can use any of the operators listed below in the Operators section. These usually test whether certain fields match certain regular expressions.

The &&, ||, and ! operators are logical AND, logical OR, and logical NOT, same as in C. They short-circuit evaluate, also just like C, and they're used for combining more basic pattern expressions. Like in most languages, parentheses let you change the order of evaluation 🎀

The ?: operator works just like it does in C. If the first pattern is true, the pattern used for testing is the second pattern. Otherwise, it's the third. Only one of the second and third patterns gets evaluated, so no double work 🦋

The pattern1, pattern2 form is called a range pattern. It matches all input records starting with a record that matches pattern1, and keeps going until a record that matches pattern2, inclusive, meaning that last record counts too. It doesn't combine with any other sort of pattern expression 🌸

Actions

Action statements are enclosed in braces, { and } 💅 They consist of the usual assignment, conditional, and looping statements you'd find in most languages. The operators, control statements, and input/output statements available are patterned after the ones in C, so if you know C you're already halfway there ✨

Operators

The operators in AWK, in order of decreasing precedence, are:

  • (...) — Grouping 🧁
  • $ — Field reference.
  • ++, -- — Increment and decrement, both prefix and postfix.
  • ^ — Exponentiation 💥
  • +, -, ! — Unary plus, unary minus, and logical negation.
  • *, /, % — Multiplication, division, and modulus ✖️
  • +, - — Addition and subtraction.
  • space — String concatenation. Literally just putting things next to each other 🫶
  • |, |& — Piped I/O for getline, print, and printf.
  • <, >, <=, >=, ==, != — The regular relational operators.
  • ~, !~ — Regular expression match, negated match.
  • in — Array membership.
  • && — Logical AND.
  • || — Logical OR.
  • ?: — The C conditional expression. This has the form expr1 ? expr2 : expr3. If expr1 is true, the value of the expression is expr2, otherwise it's expr3. Only one of expr2 and expr3 gets evaluated 🦋
  • =, +=, -=, *=, /=, %=, ^= — Assignment. Both absolute assignment (var = value) and operator-assignment (the other forms) are supported 💖

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
              break
              continue
              delete array[index]
              delete array
              exit [ expression ]
              { statements }
              switch (expression) {
              case value|regex : statement
              ...
              [ default: statement ]
              }

✨ I/O Statements ✨

okay so here's where gawk gets its chat going 💬 the input/output statements are all lined up below, bestie 🫶

  • close(file [, how]) — closes an open file, pipe, or coprocess 🔒 the optional how should ONLY be used when you're closing one end of a two-way pipe to a coprocess, and it has to be a string, either "to" or "from" 💅
  • getline — sets $0 from the next input record, and sets NF, NR, FNR, and RT 📥
  • getline <file — sets $0 from the next record of file, and sets NF and RT 📂
  • getline var — sets var from the next input record, and sets NR, FNR, and RT 🎀
  • getline var <file — sets var from the next record of file, and sets RT 🧚
  • command | getline [var] — runs command and pipes its output into $0 or var (same as above), plus RT 🌸
  • command |& getline [var] — runs command as a coprocess and pipes its output into $0 or var (same as above), plus RT 🦋 the command can also be a socket, so peep the subsection Special File Names below 👀
  • fflush([file]) — flushes any buffers tied to the open output file or pipe 🚿 if file is missing or it's the null string, gawk flushes ALL open output files and pipes, iconic behavior 👑
  • next — stops processing the current input record, reads the next one, and starts over from the first pattern in the AWK program ⭐ once it hits the end of the input data, it runs any END rule(s) 🏁
  • nextfile — stops processing the current input file, so the next record read comes from the next input file 📁 it updates FILENAME and ARGIND, resets FNR to 1, and restarts from the first pattern in the AWK program 🔄 at the end of the input data, it runs any ENDFILE and END rule(s) 💖
  • print — prints the current record, terminated with the value of ORS 🖨️
  • print expr-list — prints expressions, each one separated by the value of OFS, and the output record gets terminated with the value of ORS 🍓
  • print expr-list >file — same as above, but the expressions get printed on file 📝
  • printf fmt, expr-list — formats and prints 🌈
  • printf fmt, expr-list >file — formats and prints on file 🎀
  • system(cmd-line) — executes the command cmd-line and returns its exit status 💻 this may not be available on non-POSIX systems, so heads up 🙈 for the full scoop on the exit status, check https://www.gnu.org/software/gawk/manual/html_node/I_002fO-Functions.html#I_002fO-Functions 🔗

Additional output redirections are allowed for print and printf, and they're lowkey so useful 🫶

  • print ... >> file — appends output to the file 📎
  • print ... | command — writes on a pipe 🚰
  • print ... |& command — sends data to a coprocess or socket 🦋 (see also the subsection Special File Names, below)

The getline function returns 1 on success, 0 on end of file, and -1 on an error ❌ if the errno(3) value says the I/O operation may be retried, AND PROCINFO["input", "RETRY"] is set, then -2 gets returned instead of -1, and you can try calling getline again 🔁 when there's an error, ERRNO gets set to a string describing the problem 😭

NOTE, and this is IMPORTANT bestie 🚨 failing to open a two-way socket gives you a non-fatal error that gets returned to the calling function 🙃 if you're using a pipe, coprocess, or socket with getline, or with print or printf inside a loop, you MUST use close() to create new instances of the command or socket 💀 AWK does NOT automatically close pipes, sockets, or coprocesses when they return EOF, so don't count on it 🫠

The AWK versions of the printf statement and sprintf() function are basically the same as C's 🌸 for the details, peep https://www.gnu.org/software/gawk/manual/html_node/Printf.html 💅

✨ Special File Names ✨

okay so when you do I/O redirection from print or printf into a file, or use getline from a file, gawk recognizes certain special filenames internally 🧚 these let you access open file descriptors inherited from gawk's parent process (usually the shell) 🐚 you can also use these filenames on the command line to name data files 📂 here they are, bestie:

  • - — the standard input 📥
  • /dev/stdin — the standard input 📥
  • /dev/stdout — the standard output 📤
  • /dev/stderr — the standard error output 🚨
  • /dev/fd/n — the file associated with the open file descriptor n 🔑

The following special filenames can be used with the |& coprocess operator for making TCP/IP network connections 🌐 slay:

  • /inet/tcp/lport/rhost/rport, /inet4/tcp/lport/rhost/rport, /inet6/tcp/lport/rhost/rport — files for a TCP/IP connection on local port lport to remote host rhost on remote port rport 🦋 use a port of 0 to have the system pick one for you 🎲 use /inet4 to force an IPv4 connection, and /inet6 to force an IPv6 connection 💜 plain /inet uses the system default (most likely IPv4) 🌈 these are usable ONLY with the |& two-way I/O operator 🫶
  • /inet/udp/lport/rhost/rport, /inet4/udp/lport/rhost/rport, /inet6/udp/lport/rhost/rport — same deal, but with UDP/IP instead of TCP/IP ✨

✨ Numeric Functions ✨

AWK has the following built-in arithmetic functions, and they're giving math-class-but-make-it-fun 🧮💖

  • atan2(y, x) — returns the arctangent of y/x in radians 🌙
  • cos(expr) — returns the cosine of expr, which is in radians 🌊
  • exp(expr) — the exponential function 🚀
  • int(expr) — truncates to an integer ✂️
  • log(expr) — the natural logarithm function 🪵
  • rand() — returns a random number N, between zero and one, such that 0 ≤ N < 1 🎲✨
  • sin(expr) — returns the sine of expr, which is in radians 🌊
  • sqrt(expr) — returns the square root of expr 🌟
  • srand([expr]) — uses expr as the new seed for the random number generator 🌱 if no expr is provided, it uses the time of day ⏰ returns the previous seed for the random number generator 🔙

✨ String Functions ✨

Gawk has the following built-in string functions, and the full tea on them is over at https://www.gnu.org/software/gawk/manual/html_node/String-Functions 📖 bestie, these are the main vibes 🫶

  • asort(s [, d [, how] ]) — returns the number of elements in the source array s 🧁 it sorts the contents of s using gawk's normal rules for comparing values, then replaces the indices of the sorted values in s with sequential integers starting at 1 🔢 if the optional destination array d is specified, gawk first duplicates s into d, then sorts d, leaving the indices of the source array s unchanged 💅 the optional string how controls the direction and the comparison mode, and the valid values for how are described in https://www.gnu.org/software/gawk/manual/html_node/String-Functions.html#String-Functions 📚 s and d are allowed to be the same array, but that only makes sense when you supply the third argument too 🤔
  • asorti(s [, d [, how] ]) — returns the number of elements in the source array s 🍭 it works the same as asort(), except the array indices are used for sorting, not the array values 🙃 when it's done, the array is indexed numerically, and the values are the original indices 🫠 the original values are lost, so if you want to keep them, give it a second array 💾 the purpose of the optional string how is the same as for asort() 🔁 again, s and d can be the same array, but only when you supply the third argument as well ✨
  • gensub(r, s, h [, t]) — searches the target string t for matches of the regular expression r 🔍 if h is a string beginning with g or G, it replaces ALL matches of r with s 🌈 otherwise, h is a number telling gawk which match of r to replace 🎯 if t isn't supplied, gawk uses $0 instead 📝 inside the replacement text s, the sequence \n, where n is a digit from 1 to 9, can be used to mean just the text that matched the n'th parenthesized subexpression 🧩 the sequence \0 represents the entire matched text, same as the character & 💜 unlike sub() and gsub(), the modified string gets returned as the result of the function, and the original target string is NOT changed 🫶
  • gsub(r, s [, t]) — for each substring matching the regular expression r in the string t, it substitutes the string s, and returns the number of substitutions 🔁 if t isn't supplied, it uses $0 📝 an & in the replacement text gets replaced with the text that was actually matched 🎀 to get a literal &, use \&, which has to be typed as "\\&" 🙈 for a fuller discussion of the rules for ampersands and backslashes in the replacement text of sub(), gsub(), and gensub(), check https://www.gnu.org/software/gawk/manual/html_node/Gory-Details.html#Gory-Details 🌸

index(s, t) hunts for the string t inside s and hands back its position, or zero if t isn't there at all 🙈 (which also means character positions start at one, not zero, bestie 💅)

  • length([s]) — gives you the length of the string s, or the length of $0 if you don't pass anything in. Feed it an array and it tells you how many elements that array holds 🧮
  • match(s, r [, a]) — finds where the regular expression r shows up in s and returns that position, or zero if it's a no-show. It also sets RSTART and RLENGTH for you ✨ Heads up, the argument order matches the ~ operator, so it's str ~ re 💖 For the full scoop on how the array a gets filled when you include it, check https://www.gnu.org/software/gawk/manual/html_node/String-Functions.html#String-Functions 📚
  • patsplit(s, a [, r [, seps] ]) — splits s into the array a and the separators array seps using the regex r, then returns the number of fields 🦋 The elements of a are the chunks of s that matched r. seps[i] is the separator that came right after a[i] (it might be empty, that's fine!). seps[0] is the possibly-empty separator at the very front 🌸 If you skip r, FPAT gets used instead. Both arrays get wiped clean before anything happens, and splitting works exactly like field splitting with FPAT 🫶
  • split(s, a [, r [, seps] ]) — same vibe as above, splitting s into a and seps on the regex r, and returning the number of fields 🍓 If you leave r out, FS steps in. Both arrays get cleared first. This time seps[i] is the field separator that r matched between a[i] and a[i+1], and splitting acts just like regular field splitting 💜
  • sprintf(fmt, expr-list) — prints expr-list using the format fmt and gives you back the resulting string 🎀
  • strtonum(str) — reads str and returns its numeric value 🔢 A leading 0 means octal. A leading 0x or 0X means hexadecimal. Anything else gets treated as decimal 🌈
  • sub(r, s [, t]) — basically gsub(), but it only replaces the first matching substring 🙌 It returns either zero or one, so no drama 💅
  • substr(s, i [, n]) — returns a substring of s starting at position i that is at most n characters long ✂️ If you leave n out, you get everything from i to the end of s 🦋
  • tolower(str) — returns a copy of str with every uppercase character turned into its lowercase buddy. Non-alphabetic characters just chill and stay unchanged 🧊
  • toupper(str) — returns a copy of str with every lowercase character glowed up to uppercase. Non-alphabetic characters stay exactly as they are 📣

Gawk is multibyte aware, which is so iconic 🌍 That means index(), length(), substr() and match() all count in characters, not bytes 🫶

⏰ Time Functions

Gawk gives you functions for grabbing timestamps and formatting them ⏰ The deets live at https://www.gnu.org/software/gawk/manual/html_node/Time-Functions.

  • mktime(datespec [, utc-flag]) — turns datespec into a timestamp of the same form that systime() returns, and hands it back 🕰️ If utc-flag is there and is non-zero or non-null, the time is treated as UTC. Otherwise it's assumed to be local time. If datespec doesn't have enough elements, or the resulting time is out of range, mktime() returns -1 💀 For the lowdown on datespec, see https://www.gnu.org/software/gawk/manual/html_node/Time-Functions.html#Time-Functions 📖
  • strftime([format [, timestamp[, utc-flag]]]) — formats timestamp according to format 🎨 If utc-flag is present and is non-zero or non-null, you get UTC. Otherwise it's local time. The timestamp should look like what systime() returns. No timestamp? It uses the current time of day ⏳ No format? You get a default that matches the output of date(1) 🗓️ That default lives in PROCINFO["strftime"] 🔍 For the format conversions you can count on, look at the strftime() spec in ISO C 💅
  • systime() — returns the current time of day as the number of seconds since the Epoch, which is 1970-01-01 00:00:00 UTC on POSIX systems 🕛

🔢 Bit Manipulations Functions

Gawk has bit manipulation functions for the nerdy stuff 🤓 They work by converting double-precision floating point values to uintmax_t integers, doing the operation, and then converting the result back to floating point. Passing negative operands to any of these functions causes a fatal error 💀 So don't do it!

The functions are:

  • and(v1, v2 [, ...]) — returns the bitwise AND of the values in the argument list. You need at least two 🧩
  • compl(val) — returns the bitwise complement of val 🙃
  • lshift(val, count) — returns val shifted left by count bits ⬅️
  • or(v1, v2 [, ...]) — returns the bitwise OR of the values in the argument list. Again, at least two are required 🧩
  • rshift(val, count) — returns val shifted right by count bits ➡️
  • xor(v1, v2 [, ...]) — returns the bitwise XOR of the values in the argument list. Yep, at least two 🧩

🧸 Type Functions

These functions spill the tea on the type of their arguments ☕

  • isarray(x) — returns true if x is an array, false otherwise 📦
  • typeof(x) — returns a string telling you the type of x. That string will be one of "array", "number", "regexp", "string", "strnum", "unassigned", or "undefined" 🏷️

🌍 Internationalization Functions

These functions can be used inside your AWK program to translate strings while it's running 🗣️ For the full details, go check https://www.gnu.org/software/gawk/manual/html_node/I18N-Functions.html#I18N-Functions 📚

  • bindtextdomain(directory [, domain]) — tells gawk which directory to look in for the .gmo files, for when they can't or won't live in the "standard" locations 📂 It returns the directory where domain is “bound.” The default domain is the value of TEXTDOMAIN. If directory is the null string (""), then bindtextdomain() returns the current binding for the given domain 🔗
  • dcgettext(string [, domain [, category]]) — returns the translation of string in the text domain domain for the locale category category 🌐 The default for domain is the current value of TEXTDOMAIN. The default for category is "LC_MESSAGES" 💬
  • dcngettext(string1, string2, number [, domain [, category]]) — returns the plural form used for number of the translation of string1 and string2 in the text domain domain for the locale category category 🔢 The default for domain is the current value of TEXTDOMAIN. The default for category is "LC_MESSAGES" 🫶

✅ Boolean Valued Functions

You can make special Boolean-typed values! Check the manual for how they work and why they exist 🧐

  • mkbool(expression) — based on the boolean value of expression, returns either a true value or a false value 🎯 True values have numeric value one. False values have numeric value zero 0️⃣

✨ USER-DEFINED FUNCTIONS ✨

Functions in AWK are defined like this 💅

function name(parameter list) { statements }

Functions run when they get called from inside expressions in either patterns or actions 🎬 The actual parameters you pass in the call are used to fill in the formal parameters declared in the function. Arrays are passed by reference, and other variables are passed by value 🔁

Local variables get declared as extra parameters in the parameter list. The convention is to separate them from the real parameters with extra spaces, so it's easy to spot them 👀 For example:

function  f(p, q,     a, b)   # a and b are local
{
     ...
}

/abc/     { ... ; f(1, 2) ; ... }

The left parenthesis in a function call has to come right after the function name, with no whitespace in between 🙅‍♀️ This restriction doesn't apply to the built-in functions listed above 🫶

Functions can call each other, and they can even be recursive 🌀 Function parameters that get used as local variables are initialized to the null string and the number zero each time the function is invoked 🧸

Use return expr to send a value back from a function 🎁 The return value is undefined if no value is provided, or if the function returns by “falling off” the end 👻

Functions can also be called indirectly, which is giving main character energy 👑 To do this, assign the name of the function you want to call, as a string, to a variable. Then use that variable as if it were the function name, prefixed with an @ sign, like so:

function myfunc()
{
     print "myfunc called"
     ...
}

{    ...
     the_func = "myfunc"
     @the_func()    # call through the_func to myfunc
     ...
}

If --lint has been provided, gawk warns about calls to undefined functions at parse time, instead of at run time 🔍 Calling an undefined function at run time is a fatal error 💀

🚀 DYNAMICALLY LOADING NEW FUNCTIONS 🚀

You can dynamically add new functions written in C or C++ to the running gawk interpreter with the @load statement 🧩 The full details are beyond the scope of this manual page, but you can find them at https://www.gnu.org/software/gawk/manual/html_node/Dynamic-Extensions.html#Dynamic-Extensions 📖

✨ SIGNALS ✨

okay so the gawk profiler actually takes two signals 💅 SIGUSR1 makes it dump the profile and the function call stack into the profile file (which is awkprof.out by default, or whatever file you named with the --profile option) and then it just keeps on running 🏃‍♀️ SIGHUP is the dramatic one 😭 it dumps the profile and function call stack and then exits right away.

🌸 INTERNATIONALIZATION 🌸

String constants are just sequences of characters wrapped in double quotes 🎀 Now, in non-English speaking environments you can mark a string in your AWK program as needing translation into the local natural language 🌍 You do this with a leading underscore (“_”) in front of the string. For example,

gawk 'BEGIN { print "hello, world" }'

always prints hello, world 💖 But,

gawk 'BEGIN { print _"hello, world" }'

might print bonjour, monde in France 🇫🇷 ✨ For the steps involved in producing and running a localizable AWK program, check out https://www.gnu.org/software/gawk/manual/html_node/Internationalization.html#Internationalization

🦋 GNU EXTENSIONS 🦋

Gawk has a seriously huge number of extensions on top of POSIX awk 😭 They're all described in https://www.gnu.org/software/gawk/manual/html_node/POSIX_002fGNU.html. Want none of them? Invoke gawk with the --traditional or --posix option and every extension gets switched off 🙅‍♀️

🧚 ENVIRONMENT VARIABLES 🧚

The AWKPATH environment variable is a list of directories that gawk searches when it's looking for files named via the -f, --file, -i and --include options, and the @include directive 📂 If the first search fails, gawk searches again after appending .awk to the filename.

The AWKLIBPATH environment variable is a list of directories that gawk searches when looking for files named via the -l and --load options 🔍

The GAWK_PERSIST_FILE environment variable, if it's present, names a file to use as the backing store for persistent memory 💜 For the details, see GAWK: Effective AWK Programming.

The GAWK_READ_TIMEOUT environment variable lets you set a timeout in milliseconds for reading input from a terminal, pipe or two-way communication, including sockets ⏳

For connecting to a remote host via socket, GAWK_SOCK_RETRIES controls the number of retries and GAWK_MSEC_SLEEP controls the interval between retries 🫶 The interval is in milliseconds. On systems that don't support usleep(3), the value gets rounded up to a whole number of seconds.

If POSIXLY_CORRECT exists in the environment, gawk behaves exactly as if --posix had been passed on the command line 👑 If --lint is also specified, gawk issues a warning message about this 🙈

🚪 EXIT STATUS 🚪

If the exit statement is used with a value, gawk exits with that numeric value, no questions asked ✨

Otherwise, if nothing went wrong during execution, gawk exits with the value of the C constant EXIT_SUCCESS, which is usually zero 🥳

If an error occurs, gawk exits with the value of the C constant EXIT_FAILURE, which is usually one 😬

If gawk exits because of a fatal error, the exit status is 2. On non-POSIX systems, this value may get mapped to EXIT_FAILURE.

🎀 VERSION INFORMATION 🎀

This man page documents gawk, version 5.3 🍓

💅 AUTHORS 💅

The original version of UNIX awk was designed and implemented by Alfred Aho, Peter Weinberger, and Brian Kernighan of Bell Laboratories 👩‍🔬 Ozan Yigit is the current maintainer. Brian Kernighan occasionally dabbles in its development, iconic behavior 😌

Paul Rubin and Jay Fenlason, of the Free Software Foundation, wrote gawk to be compatible with the original version of awk distributed in Seventh Edition UNIX 🧑‍💻 John Woods contributed a bunch of bug fixes. David Trueman, with contributions from Arnold Robbins, made gawk compatible with the new version of UNIX awk. Arnold Robbins is the current maintainer 🌟

See GAWK: Effective AWK Programming for a full list of the contributors to gawk and its documentation 📚 See the README file in the gawk distribution for up-to-date information about maintainers and which ports are currently supported 🔎

🐛 BUG REPORTS AND QUESTIONS 🐛

If you find a bug in gawk, please use the gawkbug(1) program to report it 🙏

Full instructions for reporting a bug are in https://www.gnu.org/software/gawk/manual/html_node/Bugs.html. Please carefully read and follow the instructions given there. This makes bug reporting and resolution way easier for everyone involved. Really 🫠

On the other hand, if you have a question about how to accomplish a particular task using awk or gawk, email help-gawk@gnu.org with your request for help 💌

🙈 BUGS 🙈

The -F option isn't necessary given the command line variable assignment feature. It only sticks around for backwards compatibility, so don't stress about it.

This manual page is too long, and gawk has too many features 💀

🔗 SEE ALSO 🔗

egrep(1), sed(1), gawkbug(1), printf(3), and strftime(3) 🌈

The AWK Programming Language, second edition, Alfred V. Aho, Brian W. Kernighan, Peter J. Weinberger, Addison-Wesley, 2023. ISBN 9-780138-269722 📖

GAWK: Effective AWK Programming, Edition 5.3, shipped with the gawk source. The current version of this document is online at https://www.gnu.org/software/gawk/manual 💜

The GNU gettext documentation, available online at https://www.gnu.org/software/gettext 🌸

🍭 EXAMPLES 🍭

Print and sort the login names of all users:

BEGIN     { FS = ":" }
     { print $1 | "sort" }

Count lines in a file:

     { nlines++ }
BEGIN  { print nlines }

Precede each line by its number in the file:

{ print FNR, $0 }

Concatenate and line number (a variation on a theme):

{ print NR, $0 }

Run an external command for particular lines of data:

tail -f access_log |
awk '/myhome.html/ { system("nmap " $1 ">> logdir/myhome.html") }'

📜 COPYING PERMISSIONS 📜

Copyright © 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, 2003, 2004, 2005, 2007, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025 Free Software Foundation, Inc. 🗽

Permission is granted to make and distribute verbatim copies of this manual page provided the copyright notice and this permission notice are preserved on all copies 🫶

Permission is granted to copy and distribute modified versions of this manual page under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one 💅

Permission is granted to copy and distribute translations of this manual page into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation 🌍

bestie, that's the whole thing 🎀 Free Software Foundation, March 23 2025, GAWK(1) 💖 now go be a awk legend ✨🦋

📦 where this page comes from