1GAWK(1) Utility Commands GAWK(1)
2
6 gawk - pattern scanning and processing language
7
9 gawk [ POSIX or GNU style options ] -f program-file [ -- ] file ...
10 gawk [ POSIX or GNU style options ] [ -- ] program-text file ...
11
13 Gawk is the GNU Project's implementation of the AWK programming lan‐
14 guage. It conforms to the definition of the language in the POSIX
15 1003.1 standard. This version in turn is based on the description in
16 The AWK Programming Language, by Aho, Kernighan, and Weinberger. Gawk
17 provides the additional features found in the current version of Brian
18 Kernighan's awk and numerous GNU-specific extensions.
19 The command line consists of options to gawk itself, the AWK program
21 text (if not supplied via the -f or --include options), and values to
22 be made available in the ARGC and ARGV pre-defined AWK variables.
23
25 This manual page is intentionally as terse as possible. Full details
26 are provided in GAWK: Effective AWK Programming, and you should look
27 there for the full story on any specific feature. Where possible,
28 links to the online version of the manual are provided.
29
31 Gawk options may be either traditional POSIX-style one letter options,
32 or GNU-style long options. POSIX options start with a single “-”,
33 while long options start with “--”. Long options are provided for both
34 GNU-specific features and for POSIX-mandated features.
35 Gawk-specific options are typically used in long-option form. Argu‐
37 ments to long options are either joined with the option by an = sign,
38 with no intervening spaces, or they may be provided in the next command
39 line argument. Long options may be abbreviated, as long as the abbre‐
40 viation remains unique.
41 Additionally, every long option has a corresponding short option, so
43 that the option's functionality may be used from within #! executable
44 scripts.
45
47 Gawk accepts the following options. Standard options are listed first,
48 followed by options for gawk extensions, listed alphabetically by short
49 option.
50 -f program-file, --file program-file
52 Read the AWK program source from the file program-file, instead
53 of from the first command line argument. Multiple -f options
54 may be used. Files read with -f are treated as if they begin
55 with an implicit @namespace "awk" statement.
56 -F fs, --field-separator fs
58 Use fs for the input field separator (the value of the FS prede‐
59 fined variable).
60 -v var=val, --assign var=val
62 Assign the value val to the variable var, before execution of
63 the program begins. Such variable values are available to the
64 BEGIN rule of an AWK program.
65 -b, --characters-as-bytes
67 Treat all input data as single-byte characters. The --posix op‐
68 tion overrides this one.
69 -c, --traditional
71 Run in compatibility mode. In compatibility mode, gawk behaves
72 identically to Brian Kernighan's awk; none of the GNU-specific
73 extensions are recognized.
74 -C, --copyright
76 Print the short version of the GNU copyright information message
77 on the standard output and exit successfully.
78 -d[file], --dump-variables[=file]
80 Print a sorted list of global variables, their types and final
81 values to file. The default file is awkvars.out in the current
82 directory.
83 -D[file], --debug[=file]
85 Enable debugging of AWK programs. By default, the debugger
86 reads commands interactively from the keyboard (standard input).
87 The optional file argument specifies a file with a list of com‐
88 mands for the debugger to execute non-interactively.
89 In this mode of execution, gawk loads the AWK source code and
90 then prompts for debugging commands. Gawk can only debug AWK
91 program source provided with the -f and --include options. The
92 debugger is documented in GAWK: Effective AWK Programming; see
93 https://www.gnu.org/software/gawk/manual/html_node/Debug‐
94 ger.html#Debugger.
95 -e program-text, --source program-text
97 Use program-text as AWK program source code. Each argument sup‐
98 plied via -e is treated as if it begins with an implicit @name‐
99 space "awk" statement.
100 -E file, --exec file
102 Similar to -f, however, this is option is the last one pro‐
103 cessed. This should be used with #! scripts, particularly for
104 CGI applications, to avoid passing in options or source code (!)
105 on the command line from a URL. This option disables command-
106 line variable assignments.
107 -g, --gen-pot
109 Scan and parse the AWK program, and generate a GNU .pot (Porta‐
110 ble Object Template) format file on standard output with entries
111 for all localizable strings in the program. The program itself
112 is not executed.
113 -h, --help
115 Print a relatively short summary of the available options on the
116 standard output. Per the GNU Coding Standards, these options
117 cause an immediate, successful exit.
118 -i include-file, --include include-file
120 Load an awk source library. This searches for the library using
121 the AWKPATH environment variable. If the initial search fails,
122 another attempt will be made after appending the .awk suffix.
123 The file will be loaded only once (i.e., duplicates are elimi‐
124 nated), and the code does not constitute the main program
125 source. Files read with --include are treated as if they begin
126 with an implicit @namespace "awk" statement.
127 -I, --trace
129 Print the internal byte code names as they are executed when
130 running the program. The trace is printed to standard error.
131 Each ``op code'' is preceded by a + sign in the output.
132 -l lib, --load lib
134 Load a gawk extension from the shared library lib. This
135 searches for the library using the AWKLIBPATH environment vari‐
136 able. If the initial search fails, another attempt will be made
137 after appending the default shared library suffix for the plat‐
138 form. The library initialization routine is expected to be
139 named dl_load().
140 -L [value], --lint[=value]
142 Provide warnings about constructs that are dubious or non-porta‐
143 ble to other AWK implementations. See https://www.gnu.org/soft‐
144 ware/gawk/manual/html_node/Options.html#Options for the list of
145 possible values for value.
146 -M, --bignum
148 Force arbitrary precision arithmetic on numbers. This option has
149 no effect if gawk is not compiled to use the GNU MPFR and GMP
150 libraries. (In such a case, gawk issues a warning.)
151 NOTE: This feature is on parole. The primary gawk maintainer is
153 no longer supporting it, although there is a member of the de‐
154 velopment team who is. If this situation changes, the feature
155 will be removed from gawk.
156 -n, --non-decimal-data
158 Recognize octal and hexadecimal values in input data. Use this
159 option with great caution!
160 -N, --use-lc-numeric
162 Force gawk to use the locale's decimal point character when
163 parsing input data.
164 -o[file], --pretty-print[=file]
166 Output a pretty printed version of the program to file. The de‐
167 fault file is awkprof.out in the current directory. This option
168 implies --no-optimize.
169 -O, --optimize
171 Enable gawk's default optimizations upon the internal represen‐
172 tation of the program. This option is on by default.
173 -p[prof-file], --profile[=prof-file]
175 Start a profiling session, and send the profiling data to prof-
176 file. The default is awkprof.out in the current directory. The
177 profile contains execution counts of each statement in the pro‐
178 gram in the left margin and function call counts for each user-
179 defined function. Gawk runs more slowly in this mode. This op‐
180 tion implies --no-optimize.
181 -P, --posix
183 This turns on compatibility mode, and disables a number of com‐
184 mon extensions.
185 -r, --re-interval
187 Enable the use of interval expressions in regular expression
188 matching. Interval expressions are enabled by default, but this
189 option remains for backwards compatibility.
190 -s, --no-optimize
192 Disable gawk's default optimizations upon the internal represen‐
193 tation of the program.
194 -S, --sandbox
196 Run gawk in sandbox mode, disabling the system() function, input
197 redirection with getline, output redirection with print and
198 printf, and loading dynamic extensions. Command execution
199 (through pipelines) is also disabled.
200 -t, --lint-old
202 Provide warnings about constructs that are not portable to the
203 original version of UNIX awk.
204 -V, --version
206 Print version information for this particular copy of gawk on
207 the standard output. This is useful when reporting bugs. Per
208 the GNU Coding Standards, these options cause an immediate, suc‐
209 cessful exit.
210 -- Signal the end of options. This is useful to allow further argu‐
212 ments to the AWK program itself to start with a “-”.
213 In compatibility mode, any other options are flagged as invalid, but
215 are otherwise ignored. In normal operation, as long as program text
216 has been supplied, unknown options are passed on to the AWK program in
217 the ARGV array for processing.
218 For POSIX compatibility, the -W option may be used, followed by the
220 name of a long option.
221
223 An AWK program consists of a sequence of optional directives, pattern-
224 action statements, and optional function definitions.
225 @include "filename"
227 @load "filename"
228 @namespace "name"
229 pattern { action statements }
230 function name(parameter list) { statements }
231 Gawk first reads the program source from the program-file(s) if speci‐
233 fied, from arguments to --source, or from the first non-option argument
234 on the command line. The -f and --source options may be used multiple
235 times on the command line. Gawk reads the program text as if all the
236 program-files and command line source texts had been concatenated to‐
237 gether.
238 In addition, lines beginning with @include may be used to include other
240 source files into your program. This is equivalent to using the --in‐
241 clude option.
242 Lines beginning with @load may be used to load extension functions into
244 your program. This is equivalent to using the --load option.
245 The environment variable AWKPATH specifies a search path to use when
247 finding source files named with the -f and --include options. If this
248 variable does not exist, the default path is ".:/usr/local/share/awk".
249 (The actual directory may vary, depending upon how gawk was built and
250 installed.) If a file name given to the -f option contains a “/” char‐
251 acter, no path search is performed.
252 The environment variable AWKLIBPATH specifies a search path to use when
254 finding source files named with the --load option. If this variable
255 does not exist, the default path is "/usr/local/lib/gawk". (The actual
256 directory may vary, depending upon how gawk was built and installed.)
257 Gawk executes AWK programs in the following order. First, all variable
259 assignments specified via the -v option are performed. Next, gawk com‐
260 piles the program into an internal form. Then, gawk executes the code
261 in the BEGIN rule(s) (if any), and then proceeds to read each file
262 named in the ARGV array (up to ARGV[ARGC-1]). If there are no files
263 named on the command line, gawk reads the standard input.
264 If a filename on the command line has the form var=val it is treated as
266 a variable assignment. The variable var will be assigned the value
267 val. (This happens after any BEGIN rule(s) have been run.)
268 If the value of a particular element of ARGV is empty (""), gawk skips
270 over it.
271 For each input file, if a BEGINFILE rule exists, gawk executes the as‐
273 sociated code before processing the contents of the file. Similarly,
274 gawk executes the code associated with ENDFILE rules after processing
275 the file.
276 For each record in the input, gawk tests to see if it matches any pat‐
278 tern in the AWK program. For each pattern that the record matches,
279 gawk executes the associated action. The patterns are tested in the
280 order they occur in the program.
281 Finally, after all the input is exhausted, gawk executes the code in
283 the END rule(s) (if any).
284 Command Line Directories
286 According to POSIX, files named on the awk command line must be text
287 files. The behavior is ``undefined'' if they are not. Most versions
288 of awk treat a directory on the command line as a fatal error.
289 For gawk, a directory on the command line produces a warning, but is
291 otherwise skipped. If either of the --posix or --traditional options
292 is given, then gawk reverts to treating directories on the command line
293 as a fatal error.
294
296 AWK variables are dynamic; they come into existence when they are first
297 used. Their values are either floating-point numbers or strings, or
298 both, depending upon how they are used. Additionally, gawk allows
299 variables to have regular-expression type. AWK also has one dimen‐
300 sional arrays; arrays with multiple dimensions may be simulated. How‐
301 ever, gawk provides true arrays of arrays. Several pre-defined vari‐
302 ables are set as a program runs; these are described as needed and sum‐
303 marized below.
304 Records
306 Normally, records are separated by newline characters. You can control
307 how records are separated by assigning values to the built-in variable
308 RS. See https://www.gnu.org/software/gawk/man‐
309 ual/html_node/Records.html for the details.
310 Fields
312 As each input record is read, gawk splits the record into fields, using
313 the value of the FS variable as the field separator. Additionally,
314 FIELDWIDTHS and FPAT may be used to control input field splitting. See
315 the details, starting at https://www.gnu.org/software/gawk/man‐
316 ual/html_node/Fields.html.
317 Each field in the input record may be referenced by its position: $1,
319 $2, and so on. $0 is the whole record, including leading and trailing
320 whitespace.
321 The variable NF is set to the total number of fields in the input
323 record.
324 References to non-existent fields (i.e., fields after $NF) produce the
326 null string. However, assigning to a non-existent field (e.g., $(NF+2)
327 = 5) increases the value of NF, creates any intervening fields with the
328 null string as their values, and causes the value of $0 to be recom‐
329 puted, with the fields being separated by the value of OFS. References
330 to negative numbered fields cause a fatal error. Decrementing NF
331 causes the values of fields past the new value to be lost, and the
332 value of $0 to be recomputed, with the fields being separated by the
333 value of OFS.
334 Assigning a value to an existing field causes the whole record to be
336 rebuilt when $0 is referenced. Similarly, assigning a value to $0
337 causes the record to be resplit, creating new values for the fields.
338 Built-in Variables
340 Gawk's built-in variables are listed below. This list is purposely
341 terse. For details, see https://www.gnu.org/software/gawk/man‐
342 ual/html_node/Built_002din-Variables.
343 ARGC The number of command line arguments.
345 ARGIND The index in ARGV of the current file being processed.
347 ARGV Array of command line arguments. The array is indexed from
349 0 to ARGC - 1.
350 BINMODE On non-POSIX systems, specifies use of “binary” mode for
352 all file I/O. See https://www.gnu.org/software/gawk/man‐
353 ual/html_node/PC-Using.html for the details.
354 CONVFMT The conversion format for numbers, "%.6g", by default.
356 ENVIRON An array containing the values of the current environment.
358 The array is indexed by the environment variables, each el‐
359 ement being the value of that variable.
360 ERRNO If a system error occurs either doing a redirection for
362 getline, during a read for getline, or during a close(),
363 then ERRNO is set to a string describing the error. The
364 value is subject to translation in non-English locales.
365 FIELDWIDTHS A whitespace-separated list of field widths. When set,
367 gawk parses the input into fields of fixed width, instead
368 of using the value of the FS variable as the field separa‐
369 tor. Each field width may optionally be preceded by a
370 colon-separated value specifying the number of characters
371 to skip before the field starts.
372 FILENAME The name of the current input file. If no files are speci‐
374 fied on the command line, the value of FILENAME is “-”.
375 However, FILENAME is undefined inside the BEGIN rule (un‐
376 less set by getline).
377 FNR The input record number in the current input file.
379 FPAT A regular expression describing the contents of the fields
381 in a record. When set, gawk parses the input into fields,
382 where the fields match the regular expression, instead of
383 using the value of FS as the field separator.
384 FS The input field separator, a space by default. See
386 https://www.gnu.org/software/gawk/manual/html_node/Field-
387 Separators.html for the details.
388 FUNCTAB An array whose indices and corresponding values are the
390 names of all the user-defined or extension functions in the
391 program. NOTE: You may not use the delete statement with
392 the FUNCTAB array.
393 IGNORECASE Controls the case-sensitivity of all regular expression and
395 string operations. See https://www.gnu.org/soft‐
396 ware/gawk/manual/html_node/Case_002dsensitivity.html for
397 details.
398 LINT Provides dynamic control of the --lint option from within
400 an AWK program.
401 NF The number of fields in the current input record.
403 NR The total number of input records seen so far.
405 OFMT The output format for numbers, "%.6g", by default.
407 OFS The output field separator, a space by default.
409 ORS The output record separator, by default a newline.
411 PREC The working precision of arbitrary precision floating-point
413 numbers, 53 by default.
414 PROCINFO The elements of this array provide access to information
416 about the running AWK program. See
417 https://www.gnu.org/software/gawk/man‐
418 ual/html_node/Auto_002dset for the details.
419 ROUNDMODE The rounding mode to use for arbitrary precision arithmetic
421 on numbers, by default "N" (IEEE-754 roundTiesToEven mode).
422 See https://www.gnu.org/software/gawk/manual/html_node/Set‐
423 ting-the-rounding-mode for the details.
424 RS The input record separator, by default a newline.
426 RT The record terminator. Gawk sets RT to the input text that
428 matched the character or regular expression specified by
429 RS.
430 RSTART The index of the first character matched by match(); 0 if
432 no match.
433 RLENGTH The length of the string matched by match(); -1 if no
435 match.
436 SUBSEP The string used to separate multiple subscripts in array
438 elements, by default "\034".
439 SYMTAB An array whose indices are the names of all currently de‐
441 fined global variables and arrays in the program. You may
442 not use the delete statement with the SYMTAB array, nor as‐
443 sign to elements with an index that is not a variable name.
444 TEXTDOMAIN The text domain of the AWK program; used to find the local‐
446 ized translations for the program's strings.
447 Arrays
449 Arrays are subscripted with an expression between square brackets ([
450 and ]). If the expression is an expression list (expr, expr ...) then
451 the array subscript is a string consisting of the concatenation of the
452 (string) value of each expression, separated by the value of the SUBSEP
453 variable. This facility is used to simulate multiply dimensioned ar‐
454 rays. For example:
455 i = "A"; j = "B"; k = "C"
457 x[i, j, k] = "hello, world\n"
458 assigns the string "hello, world\n" to the element of the array x which
460 is indexed by the string "A\034B\034C". All arrays in AWK are associa‐
461 tive, i.e., indexed by string values.
462 The special operator in may be used to test if an array has an index
464 consisting of a particular value:
465 if (val in array)
467 print array[val]
468 If the array has multiple subscripts, use (i, j) in array.
470 The in construct may also be used in a for loop to iterate over all the
472 elements of an array. However, the (i, j) in array construct only
473 works in tests, not in for loops.
474 An element may be deleted from an array using the delete statement.
476 The delete statement may also be used to delete the entire contents of
477 an array, just by specifying the array name without a subscript.
478 gawk supports true multidimensional arrays. It does not require that
480 such arrays be ``rectangular'' as in C or C++. See
481 https://www.gnu.org/software/gawk/manual/html_node/Arrays for details.
482 Namespaces
484 Gawk provides a simple namespace facility to help work around the fact
485 that all variables in AWK are global.
486 A qualified name consists of a two simple identifiers joined by a dou‐
488 ble colon (::). The left-hand identifier represents the namespace and
489 the right-hand identifier is the variable within it. All simple (non-
490 qualified) names are considered to be in the ``current'' namespace; the
491 default namespace is awk. However, simple identifiers consisting
492 solely of uppercase letters are forced into the awk namespace, even if
493 the current namespace is different.
494 You change the current namespace with an @namespace "name" directive.
496 The standard predefined builtin function names may not be used as name‐
498 space names. The names of additional functions provided by gawk may be
499 used as namespace names or as simple identifiers in other namespaces.
500 For more details, see https://www.gnu.org/software/gawk/man‐
501 ual/html_node/Namespaces.html#Namespaces.
502 Variable Typing And Conversion
504 Variables and fields may be (floating point) numbers, or strings, or
505 both. They may also be regular expressions. How the value of a vari‐
506 able is interpreted depends upon its context. If used in a numeric ex‐
507 pression, it will be treated as a number; if used as a string it will
508 be treated as a string.
509 To force a variable to be treated as a number, add zero to it; to force
511 it to be treated as a string, concatenate it with the null string.
512 Uninitialized variables have the numeric value zero and the string
514 value "" (the null, or empty, string).
515 When a string must be converted to a number, the conversion is accom‐
517 plished using strtod(3). A number is converted to a string by using
518 the value of CONVFMT as a format string for sprintf(3), with the nu‐
519 meric value of the variable as the argument. However, even though all
520 numbers in AWK are floating-point, integral values are always converted
521 as integers.
522 Gawk performs comparisons as follows: If two variables are numeric,
524 they are compared numerically. If one value is numeric and the other
525 has a string value that is a “numeric string,” then comparisons are
526 also done numerically. Otherwise, the numeric value is converted to a
527 string and a string comparison is performed. Two strings are compared,
528 of course, as strings.
529 Note that string constants, such as "57", are not numeric strings, they
531 are string constants. The idea of “numeric string” only applies to
532 fields, getline input, FILENAME, ARGV elements, ENVIRON elements and
533 the elements of an array created by split() or patsplit() that are nu‐
534 meric strings. The basic idea is that user input, and only user input,
535 that looks numeric, should be treated that way.
536 Octal and Hexadecimal Constants
538 You may use C-style octal and hexadecimal constants in your AWK program
539 source code. For example, the octal value 011 is equal to decimal 9,
540 and the hexadecimal value 0x11 is equal to decimal 17.
541 String Constants
543 String constants in AWK are sequences of characters enclosed between
544 double quotes (like "value"). Within strings, certain escape sequences
545 are recognized, as in C. See https://www.gnu.org/software/gawk/man‐
546 ual/html_node/Escape-Sequences for the details.
547 Regexp Constants
549 A regular expression constant is a sequence of characters enclosed be‐
550 tween forward slashes (like /value/).
551 The escape sequences described in the manual may also be used inside
553 constant regular expressions (e.g., /[ \t\f\n\r\v]/ matches whitespace
554 characters).
555 Gawk provides strongly typed regular expression constants. These are
557 written with a leading @ symbol (like so: @/value/). Such constants
558 may be assigned to scalars (variables, array elements) and passed to
559 user-defined functions. Variables that have been so assigned have regu‐
560 lar expression type.
561
563 AWK is a line-oriented language. The pattern comes first, and then the
564 action. Action statements are enclosed in { and }. Either the pattern
565 may be missing, or the action may be missing, but, of course, not both.
566 If the pattern is missing, the action executes for every single record
567 of input. A missing action is equivalent to
568 { print }
570 which prints the entire record.
572 Comments begin with the # character, and continue until the end of the
574 line. Empty lines may be used to separate statements. Normally, a
575 statement ends with a newline, however, this is not the case for lines
576 ending in a comma, {, ?, :, &&, or ||. Lines ending in do or else also
577 have their statements automatically continued on the following line.
578 In other cases, a line can be continued by ending it with a “\”, in
579 which case the newline is ignored. However, a “\” after a # is not
580 special.
581 Multiple statements may be put on one line by separating them with a
583 “;”. This applies to both the statements within the action part of a
584 pattern-action pair (the usual case), and to the pattern-action state‐
585 ments themselves.
586 Patterns
588 AWK patterns may be one of the following:
589 BEGIN
591 END
592 BEGINFILE
593 ENDFILE
594 /regular expression/
595 relational expression
596 pattern && pattern
597 pattern || pattern
598 pattern ? pattern : pattern
599 (pattern)
600 ! pattern
601 pattern1, pattern2
602 BEGIN and END are two special kinds of patterns which are not tested
604 against the input. The action parts of all BEGIN patterns are merged
605 as if all the statements had been written in a single BEGIN rule. They
606 are executed before any of the input is read. Similarly, all the END
607 rules are merged, and executed when all the input is exhausted (or when
608 an exit statement is executed). BEGIN and END patterns cannot be com‐
609 bined with other patterns in pattern expressions. BEGIN and END pat‐
610 terns cannot have missing action parts.
611 BEGINFILE and ENDFILE are additional special patterns whose actions are
613 executed before reading the first record of each command-line input
614 file and after reading the last record of each file. Inside the BEGIN‐
615 FILE rule, the value of ERRNO is the empty string if the file was
616 opened successfully. Otherwise, there is some problem with the file
617 and the code should use nextfile to skip it. If that is not done, gawk
618 produces its usual fatal error for files that cannot be opened.
619 For /regular expression/ patterns, the associated statement is executed
621 for each input record that matches the regular expression. Regular ex‐
622 pressions are essentially the same as those in egrep(1). See
623 https://www.gnu.org/software/gawk/manual/html_node/Regexp.html for the
624 details on regular expressions.
625 A relational expression may use any of the operators defined below in
627 the section on actions. These generally test whether certain fields
628 match certain regular expressions.
629 The &&, ||, and ! operators are logical AND, logical OR, and logical
631 NOT, respectively, as in C. They do short-circuit evaluation, also as
632 in C, and are used for combining more primitive pattern expressions.
633 As in most languages, parentheses may be used to change the order of
634 evaluation.
635 The ?: operator is like the same operator in C. If the first pattern
637 is true then the pattern used for testing is the second pattern, other‐
638 wise it is the third. Only one of the second and third patterns is
639 evaluated.
640 The pattern1, pattern2 form of an expression is called a range pattern.
642 It matches all input records starting with a record that matches pat‐
643 tern1, and continuing until a record that matches pattern2, inclusive.
644 It does not combine with any other sort of pattern expression.
645 Actions
647 Action statements are enclosed in braces, { and }. Action statements
648 consist of the usual assignment, conditional, and looping statements
649 found in most languages. The operators, control statements, and in‐
650 put/output statements available are patterned after those in C.
651 Operators
653 The operators in AWK, in order of decreasing precedence, are:
654 (...) Grouping
656 $ Field reference.
658 ++ -- Increment and decrement, both prefix and postfix.
660 ^ Exponentiation.
662 + - ! Unary plus, unary minus, and logical negation.
664 * / % Multiplication, division, and modulus.
666 + - Addition and subtraction.
668 space String concatenation.
670 | |& Piped I/O for getline, print, and printf.
672 < > <= >= == !=
674 The regular relational operators.
675 ~ !~ Regular expression match, negated match.
677 in Array membership.
679 && Logical AND.
681 || Logical OR.
683 ?: The C conditional expression. This has the form expr1 ?
685 expr2 : expr3. If expr1 is true, the value of the expres‐
686 sion is expr2, otherwise it is expr3. Only one of expr2
687 and expr3 is evaluated.
688 = += -= *= /= %= ^=
690 Assignment. Both absolute assignment (var = value) and op‐
691 erator-assignment (the other forms) are supported.
692 Control Statements
694 The control statements are as follows:
695 if (condition) statement [ else statement ]
697 while (condition) statement
698 do statement while (condition)
699 for (expr1; expr2; expr3) statement
700 for (var in array) statement
701 break
702 continue
703 delete array[index]
704 delete array
705 exit [ expression ]
706 { statements }
707 switch (expression) {
708 case value|regex : statement
709 ...
710 [ default: statement ]
711 }
712 I/O Statements
714 The input/output statements are as follows:
715 close(file [, how]) Close an open file, pipe or coprocess. The op‐
717 tional how should only be used when closing one
718 end of a two-way pipe to a coprocess. It must be
719 a string value, either "to" or "from".
720 getline Set $0 from the next input record; set NF, NR,
722 FNR, RT.
723 getline <file Set $0 from the next record of file; set NF, RT.
725 getline var Set var from the next input record; set NR, FNR,
727 RT.
728 getline var <file Set var from the next record of file; set RT.
730 command | getline [var]
732 Run command, piping the output either into $0 or
733 var, as above, and RT.
734 command |& getline [var]
736 Run command as a coprocess piping the output ei‐
737 ther into $0 or var, as above, and RT. (The com‐
738 mand can also be a socket. See the subsection
739 Special File Names, below.)
740 fflush([file]) Flush any buffers associated with the open output
742 file or pipe file. If file is missing or if it
743 is the null string, then flush all open output
744 files and pipes.
745 next Stop processing the current input record. Read
747 the next input record and start processing over
748 with the first pattern in the AWK program. Upon
749 reaching the end of the input data, execute any
750 END rule(s).
751 nextfile Stop processing the current input file. The next
753 input record read comes from the next input file.
754 Update FILENAME and ARGIND, reset FNR to 1, and
755 start processing over with the first pattern in
756 the AWK program. Upon reaching the end of the
757 input data, execute any ENDFILE and END rule(s).
758 print Print the current record. The output record is
760 terminated with the value of ORS.
761 print expr-list Print expressions. Each expression is separated
763 by the value of OFS. The output record is termi‐
764 nated with the value of ORS.
765 print expr-list >file Print expressions on file. Each expression is
767 separated by the value of OFS. The output record
768 is terminated with the value of ORS.
769 printf fmt, expr-list Format and print.
771 printf fmt, expr-list >file
773 Format and print on file.
774 system(cmd-line) Execute the command cmd-line, and return the exit
776 status. (This may not be available on non-POSIX
777 systems.) See https://www.gnu.org/soft‐
778 ware/gawk/manual/html_node/I_002fO-Func‐
779 tions.html#I_002fO-Functions for the full details
780 on the exit status.
781 Additional output redirections are allowed for print and printf.
783 print ... >> file
785 Append output to the file.
786 print ... | command
788 Write on a pipe.
789 print ... |& command
791 Send data to a coprocess or socket. (See also the subsection
792 Special File Names, below.)
793 The getline command returns 1 on success, zero on end of file, and -1
795 on an error. If the errno(3) value indicates that the I/O operation
796 may be retried, and PROCINFO["input", "RETRY"] is set, then -2 is re‐
797 turned instead of -1, and further calls to getline may be attempted.
798 Upon an error, ERRNO is set to a string describing the problem.
799 NOTE: Failure in opening a two-way socket results in a non-fatal error
801 being returned to the calling function. If using a pipe, coprocess, or
802 socket to getline, or from print or printf within a loop, you must use
803 close() to create new instances of the command or socket. AWK does not
804 automatically close pipes, sockets, or coprocesses when they return
805 EOF.
806 The AWK versions of the printf statement and sprintf() function are
808 similar to those of C. For details, see https://www.gnu.org/soft‐
809 ware/gawk/manual/html_node/Printf.html.
810 Special File Names
812 When doing I/O redirection from either print or printf into a file, or
813 via getline from a file, gawk recognizes certain special filenames in‐
814 ternally. These filenames allow access to open file descriptors inher‐
815 ited from gawk's parent process (usually the shell). These file names
816 may also be used on the command line to name data files. The filenames
817 are:
818 - The standard input.
820 /dev/stdin The standard input.
822 /dev/stdout The standard output.
824 /dev/stderr The standard error output.
826 /dev/fd/n The file associated with the open file descriptor n.
828 The following special filenames may be used with the |& coprocess oper‐
830 ator for creating TCP/IP network connections:
831 /inet/tcp/lport/rhost/rport
833 /inet4/tcp/lport/rhost/rport
834 /inet6/tcp/lport/rhost/rport
835 Files for a TCP/IP connection on local port lport to remote host
836 rhost on remote port rport. Use a port of 0 to have the system
837 pick a port. Use /inet4 to force an IPv4 connection, and /inet6
838 to force an IPv6 connection. Plain /inet uses the system de‐
839 fault (most likely IPv4). Usable only with the |& two-way I/O
840 operator.
841 /inet/udp/lport/rhost/rport
843 /inet4/udp/lport/rhost/rport
844 /inet6/udp/lport/rhost/rport
845 Similar, but use UDP/IP instead of TCP/IP.
846 Numeric Functions
848 AWK has the following built-in arithmetic functions:
849 atan2(y, x) Return the arctangent of y/x in radians.
851 cos(expr) Return the cosine of expr, which is in radians.
853 exp(expr) The exponential function.
855 int(expr) Truncate to integer.
857 log(expr) The natural logarithm function.
859 rand() Return a random number N, between zero and one, such that
861 0 ≤ N < 1.
862 sin(expr) Return the sine of expr, which is in radians.
864 sqrt(expr) Return the square root of expr.
866 srand([expr]) Use expr as the new seed for the random number generator.
868 If no expr is provided, use the time of day. Return the
869 previous seed for the random number generator.
870 String Functions
872 Gawk has the following built-in string functions; details are provided
873 in https://www.gnu.org/software/gawk/manual/html_node/String-Functions.
874 asort(s [, d [, how] ]) Return the number of elements in the source ar‐
876 ray s. Sort the contents of s using gawk's
877 normal rules for comparing values, and replace
878 the indices of the sorted values s with sequen‐
879 tial integers starting with 1. If the optional
880 destination array d is specified, first dupli‐
881 cate s into d, and then sort d, leaving the in‐
882 dices of the source array s unchanged. The op‐
883 tional string how controls the direction and
884 the comparison mode. Valid values for how are
885 described in https://www.gnu.org/soft‐
886 ware/gawk/manual/html_node/String-Func‐
887 tions.html#String-Functions. s and d are al‐
888 lowed to be the same array; this only makes
889 sense when supplying the third argument as
890 well.
891 asorti(s [, d [, how] ])
893 Return the number of elements in the source ar‐
894 ray s. The behavior is the same as that of
895 asort(), except that the array indices are used
896 for sorting, not the array values. When done,
897 the array is indexed numerically, and the val‐
898 ues are those of the original indices. The
899 original values are lost; thus provide a second
900 array if you wish to preserve the original.
901 The purpose of the optional string how is the
902 same as for asort(). Here too, s and d are al‐
903 lowed to be the same array; this only makes
904 sense when supplying the third argument as
905 well.
906 gensub(r, s, h [, t]) Search the target string t for matches of the
908 regular expression r. If h is a string begin‐
909 ning with g or G, then replace all matches of r
910 with s. Otherwise, h is a number indicating
911 which match of r to replace. If t is not sup‐
912 plied, use $0 instead. Within the replacement
913 text s, the sequence \n, where n is a digit
914 from 1 to 9, may be used to indicate just the
915 text that matched the n'th parenthesized subex‐
916 pression. The sequence \0 represents the en‐
917 tire matched text, as does the character &.
918 Unlike sub() and gsub(), the modified string is
919 returned as the result of the function, and the
920 original target string is not changed.
921 gsub(r, s [, t]) For each substring matching the regular expres‐
923 sion r in the string t, substitute the string
924 s, and return the number of substitutions. If
925 t is not supplied, use $0. An & in the re‐
926 placement text is replaced with the text that
927 was actually matched. Use \& to get a literal
928 &. (This must be typed as "\\&"; see
929 https://www.gnu.org/software/gawk/man‐
930 ual/html_node/Gory-Details.html#Gory-Details
931 for a fuller discussion of the rules for amper‐
932 sands and backslashes in the replacement text
933 of sub(), gsub(), and gensub().)
934 index(s, t) Return the index of the string t in the string
936 s, or zero if t is not present. (This implies
937 that character indices start at one.)
938 length([s]) Return the length of the string s, or the
940 length of $0 if s is not supplied. With an ar‐
941 ray argument, length() returns the number of
942 elements in the array.
943 match(s, r [, a]) Return the position in s where the regular ex‐
945 pression r occurs, or zero if r is not present,
946 and set the values of RSTART and RLENGTH. Note
947 that the argument order is the same as for the
948 ~ operator: str ~ re. See
949 https://www.gnu.org/software/gawk/man‐
950 ual/html_node/String-Functions.html#String-
951 Functions for a description of how the array a
952 is filled if it is provided.
953 patsplit(s, a [, r [, seps] ])
955 Split the string s into the array a and the
956 separators array seps on the regular expression
957 r, and return the number of fields. Element
958 values are the portions of s that matched r.
959 The value of seps[i] is the possibly null sepa‐
960 rator that appeared after a[i]. The value of
961 seps[0] is the possibly null leading separator.
962 If r is omitted, FPAT is used instead. The ar‐
963 rays a and seps are cleared first. Splitting
964 behaves identically to field splitting with
965 FPAT.
966 split(s, a [, r [, seps] ])
968 Split the string s into the array a and the
969 separators array seps on the regular expression
970 r, and return the number of fields. If r is
971 omitted, FS is used instead. The arrays a and
972 seps are cleared first. seps[i] is the field
973 separator matched by r between a[i] and a[i+1].
974 Splitting behaves identically to field split‐
975 ting.
976 sprintf(fmt, expr-list) Print expr-list according to fmt, and return
978 the resulting string.
979 strtonum(str) Examine str, and return its numeric value. If
981 str begins with a leading 0, treat it as an oc‐
982 tal number. If str begins with a leading 0x or
983 0X, treat it as a hexadecimal number. Other‐
984 wise, assume it is a decimal number.
985 sub(r, s [, t]) Just like gsub(), but replace only the first
987 matching substring. Return either zero or one.
988 substr(s, i [, n]) Return the at most n-character substring of s
990 starting at i. If n is omitted, use the rest
991 of s.
992 tolower(str) Return a copy of the string str, with all the
994 uppercase characters in str translated to their
995 corresponding lowercase counterparts. Non-al‐
996 phabetic characters are left unchanged.
997 toupper(str) Return a copy of the string str, with all the
999 lowercase characters in str translated to their
1000 corresponding uppercase counterparts. Non-al‐
1001 phabetic characters are left unchanged.
1002 Gawk is multibyte aware. This means that index(), length(), substr()
1004 and match() all work in terms of characters, not bytes.
1005 Time Functions
1007 Gawk provides the following functions for obtaining time stamps and
1008 formatting them. Details are provided in https://www.gnu.org/soft‐
1009 ware/gawk/manual/html_node/Time-Functions.
1010 mktime(datespec [, utc-flag])
1012 Turn datespec into a time stamp of the same form as returned
1013 by systime(), and return the result. If utc-flag is present
1014 and is non-zero or non-null, the time is assumed to be in the
1015 UTC time zone; otherwise, the time is assumed to be in the
1016 local time zone. If datespec does not contain enough ele‐
1017 ments or if the resulting time is out of range, mktime() re‐
1018 turns -1. See https://www.gnu.org/software/gawk/man‐
1019 ual/html_node/Time-Functions.html#Time-Functions for the de‐
1020 tails of datespec.
1021 strftime([format [, timestamp[, utc-flag]]])
1023 Format timestamp according to the specification in format.
1024 If utc-flag is present and is non-zero or non-null, the re‐
1025 sult is in UTC, otherwise the result is in local time. The
1026 timestamp should be of the same form as returned by sys‐
1027 time(). If timestamp is missing, the current time of day is
1028 used. If format is missing, a default format equivalent to
1029 the output of date(1) is used. The default format is avail‐
1030 able in PROCINFO["strftime"]. See the specification for the
1031 strftime() function in ISO C for the format conversions that
1032 are guaranteed to be available.
1033 systime() Return the current time of day as the number of seconds since
1035 the Epoch (1970-01-01 00:00:00 UTC on POSIX systems).
1036 Bit Manipulations Functions
1038 Gawk supplies the following bit manipulation functions. They work by
1039 converting double-precision floating point values to uintmax_t inte‐
1040 gers, doing the operation, and then converting the result back to
1041 floating point. Passing negative operands to any of these functions
1042 causes a fatal error.
1043 The functions are:
1045 and(v1, v2 [, ...]) Return the bitwise AND of the values provided in
1047 the argument list. There must be at least two.
1048 compl(val) Return the bitwise complement of val.
1050 lshift(val, count) Return the value of val, shifted left by count
1052 bits.
1053 or(v1, v2 [, ...]) Return the bitwise OR of the values provided in the
1055 argument list. There must be at least two.
1056 rshift(val, count) Return the value of val, shifted right by count
1058 bits.
1059 xor(v1, v2 [, ...]) Return the bitwise XOR of the values provided in
1061 the argument list. There must be at least two.
1062 Type Functions
1064 The following functions provide type related information about their
1065 arguments.
1066 isarray(x) Return true if x is an array, false otherwise.
1068 typeof(x) Return a string indicating the type of x. The string will
1070 be one of "array", "number", "regexp", "string", "strnum",
1071 "unassigned", or "undefined".
1072 Internationalization Functions
1074 The following functions may be used from within your AWK program for
1075 translating strings at run-time. For full details, see
1076 https://www.gnu.org/software/gawk/manual/html_node/I18N-Func‐
1077 tions.html#I18N-Functions.
1078 bindtextdomain(directory [, domain])
1080 Specify the directory where gawk looks for the .gmo files, in
1081 case they will not or cannot be placed in the ``standard'' loca‐
1082 tions. It returns the directory where domain is ``bound.''
1083 The default domain is the value of TEXTDOMAIN. If directory is
1084 the null string (""), then bindtextdomain() returns the current
1085 binding for the given domain.
1086 dcgettext(string [, domain [, category]])
1088 Return the translation of string in text domain domain for lo‐
1089 cale category category. The default value for domain is the
1090 current value of TEXTDOMAIN. The default value for category is
1091 "LC_MESSAGES".
1092 dcngettext(string1, string2, number [, domain [, category]])
1094 Return the plural form used for number of the translation of
1095 string1 and string2 in text domain domain for locale category
1096 category. The default value for domain is the current value of
1097 TEXTDOMAIN. The default value for category is "LC_MESSAGES".
1098 Boolean Valued Functions
1100 You can create special Boolean-typed values; see the manual for how
1101 they work and why they exist.
1102 mkbool(expression)
1104 Based on the boolean value of expression return either a true
1105 value or a false value. True values have numeric value one.
1106 False values have numeric value zero.
1107
1109 Functions in AWK are defined as follows:
1110 function name(parameter list) { statements }
1112 Functions execute when they are called from within expressions in ei‐
1114 ther patterns or actions. Actual parameters supplied in the function
1115 call are used to instantiate the formal parameters declared in the
1116 function. Arrays are passed by reference, other variables are passed
1117 by value.
1118 Local variables are declared as extra parameters in the parameter list.
1120 The convention is to separate local variables from real parameters by
1121 extra spaces in the parameter list. For example:
1122 function f(p, q, a, b) # a and b are local
1124 {
1125 ...
1126 }
1127 /abc/ { ... ; f(1, 2) ; ... }
1129 The left parenthesis in a function call is required to immediately fol‐
1131 low the function name, without any intervening whitespace. This re‐
1132 striction does not apply to the built-in functions listed above.
1133 Functions may call each other and may be recursive. Function parame‐
1135 ters used as local variables are initialized to the null string and the
1136 number zero upon function invocation.
1137 Use return expr to return a value from a function. The return value is
1139 undefined if no value is provided, or if the function returns by “fall‐
1140 ing off” the end.
1141 Functions may be called indirectly. To do this, assign the name of the
1143 function to be called, as a string, to a variable. Then use the vari‐
1144 able as if it were the name of a function, prefixed with an @ sign,
1145 like so:
1146 function myfunc()
1147 {
1148 print "myfunc called"
1149 ...
1150 }
1151 { ...
1153 the_func = "myfunc"
1154 @the_func() # call through the_func to myfunc
1155 ...
1156 }
1157 If --lint has been provided, gawk warns about calls to undefined func‐
1159 tions at parse time, instead of at run time. Calling an undefined
1160 function at run time is a fatal error.
1161
1163 You can dynamically add new functions written in C or C++ to the run‐
1164 ning gawk interpreter with the @load statement. The full details are
1165 beyond the scope of this manual page; see https://www.gnu.org/soft‐
1166 ware/gawk/manual/html_node/Dynamic-Extensions.html#Dynamic-Extensions.
1167
1169 The gawk profiler accepts two signals. SIGUSR1 causes it to dump a
1170 profile and function call stack to the profile file, which is either
1171 awkprof.out, or whatever file was named with the --profile option. It
1172 then continues to run. SIGHUP causes gawk to dump the profile and
1173 function call stack and then exit.
1174
1176 String constants are sequences of characters enclosed in double quotes.
1177 In non-English speaking environments, it is possible to mark strings in
1178 the AWK program as requiring translation to the local natural language.
1179 Such strings are marked in the AWK program with a leading underscore
1180 (“_”). For example,
1181 gawk 'BEGIN { print "hello, world" }'
1183 always prints hello, world. But,
1185 gawk 'BEGIN { print _"hello, world" }'
1187 might print bonjour, monde in France. See https://www.gnu.org/soft‐
1189 ware/gawk/manual/html_node/Internationalization.html#Internationaliza‐
1190 tion for the steps involved in producing and running a localizable AWK
1191 program.
1192
1194 Gawk has a too-large number of extensions to POSIX awk. They are de‐
1195 scribed in https://www.gnu.org/software/gawk/man‐
1196 ual/html_node/POSIX_002fGNU.html. All the extensions can be disabled
1197 by invoking gawk with the --traditional or --posix options.
1198
1200 The AWKPATH environment variable can be used to provide a list of di‐
1201 rectories that gawk searches when looking for files named via the -f,
1202 --file, -i and --include options, and the @include directive. If the
1203 initial search fails, the path is searched again after appending .awk
1204 to the filename.
1205 The AWKLIBPATH environment variable can be used to provide a list of
1207 directories that gawk searches when looking for files named via the -l
1208 and --load options.
1209 The GAWK_PERSIST_FILE environment variable, if present, specifies a
1211 file to use as the backing store for persistent memory. This is an ex‐
1212 perimental feature. See GAWK: Effective AWK Programming for the de‐
1213 tails.
1214 The GAWK_READ_TIMEOUT environment variable can be used to specify a
1216 timeout in milliseconds for reading input from a terminal, pipe or two-
1217 way communication including sockets.
1218 For connection to a remote host via socket, GAWK_SOCK_RETRIES controls
1220 the number of retries, and GAWK_MSEC_SLEEP the interval between re‐
1221 tries. The interval is in milliseconds. On systems that do not support
1222 usleep(3), the value is rounded up to an integral number of seconds.
1223 If POSIXLY_CORRECT exists in the environment, then gawk behaves exactly
1225 as if --posix had been specified on the command line. If --lint has
1226 been specified, gawk issues a warning message to this effect.
1227
1229 If the exit statement is used with a value, then gawk exits with the
1230 numeric value given to it.
1231 Otherwise, if there were no problems during execution, gawk exits with
1233 the value of the C constant EXIT_SUCCESS. This is usually zero.
1234 If an error occurs, gawk exits with the value of the C constant
1236 EXIT_FAILURE. This is usually one.
1237 If gawk exits because of a fatal error, the exit status is 2. On non-
1239 POSIX systems, this value may be mapped to EXIT_FAILURE.
1240
1242 This man page documents gawk, version 5.2.
1243
1245 The original version of UNIX awk was designed and implemented by Alfred
1246 Aho, Peter Weinberger, and Brian Kernighan of Bell Laboratories. Brian
1247 Kernighan continues to maintain and enhance it.
1248 Paul Rubin and Jay Fenlason, of the Free Software Foundation, wrote
1250 gawk, to be compatible with the original version of awk distributed in
1251 Seventh Edition UNIX. John Woods contributed a number of bug fixes.
1252 David Trueman, with contributions from Arnold Robbins, made gawk com‐
1253 patible with the new version of UNIX awk. Arnold Robbins is the cur‐
1254 rent maintainer.
1255 See GAWK: Effective AWK Programming for a full list of the contributors
1257 to gawk and its documentation.
1258 See the README file in the gawk distribution for up-to-date information
1260 about maintainers and which ports are currently supported.
1261
1263 If you find a bug in gawk, please use the gawkbug(1) program to report
1264 it.
1265 Full instructions for reporting a bug are provided in
1267 https://www.gnu.org/software/gawk/manual/html_node/Bugs.html. Please
1268 carefully read and follow the instructions given there. This will make
1269 bug reporting and resolution much easier for everyone involved. Re‐
1270 ally.
1271
1273 The -F option is not necessary given the command line variable assign‐
1274 ment feature; it remains only for backwards compatibility.
1275 This manual page is too long; gawk has too many features.
1277
1279 egrep(1), sed(1), gawkbug(1), printf(3), and strftime(3).
1280 The AWK Programming Language, Alfred V. Aho, Brian W. Kernighan, Peter
1282 J. Weinberger, Addison-Wesley, 1988. ISBN 0-201-07981-X.
1283 GAWK: Effective AWK Programming, Edition 5.2, shipped with the gawk
1285 source. The current version of this document is available online at
1286 https://www.gnu.org/software/gawk/manual.
1287 The GNU gettext documentation, available online at
1289 https://www.gnu.org/software/gettext.
1290
1292 Print and sort the login names of all users:
1293 BEGIN { FS = ":" }
1295 { print $1 | "sort" }
1296 Count lines in a file:
1298 { nlines++ }
1300 END { print nlines }
1301 Precede each line by its number in the file:
1303 { print FNR, $0 }
1305 Concatenate and line number (a variation on a theme):
1307 { print NR, $0 }
1309 Run an external command for particular lines of data:
1311 tail -f access_log |
1313 awk '/myhome.html/ { system("nmap " $1 ">> logdir/myhome.html") }'
1314
1316 Copyright © 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
1317 2001, 2002, 2003, 2004, 2005, 2007, 2009, 2010, 2011, 2012, 2013, 2014,
1318 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022 Free Software Founda‐
1319 tion, Inc.
1320 Permission is granted to make and distribute verbatim copies of this
1322 manual page provided the copyright notice and this permission notice
1323 are preserved on all copies.
1324 Permission is granted to copy and distribute modified versions of this
1326 manual page under the conditions for verbatim copying, provided that
1327 the entire resulting derived work is distributed under the terms of a
1328 permission notice identical to this one.
1329 Permission is granted to copy and distribute translations of this man‐
1331 ual page into another language, under the above conditions for modified
1332 versions, except that this permission notice may be stated in a trans‐
1333 lation approved by the Foundation.
1334Free Software Foundation Jun 09 2022 GAWK(1)