awk(1)

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 …

DESCRIPTION

Gawk is the GNU Project’s implementation of the AWK programming language. It conforms to the definition of the language in the POSIX 1003.1 standard. This version in turn is based on the description in The AWK Programming Language, by Aho, Kernighan, and Weinberger. Gawk provides the additional features found in the current version of Brian Kernighan’s awk and numerous GNU-specific extensions.

The command line consists of options to gawk itself, the AWK program text (if not supplied via the -f or –include options), and values to be made available in the ARGC and ARGV pre-defined AWK variables.

When gawk is invoked with the –profile option, it starts gathering profiling statistics from the execution of the program. Gawk runs more slowly in this mode, and automatically produces an execution profile in the file awkprof.out when done. See the –profile option, below.

Gawk also has an integrated debugger. An interactive debugging session can be started by supplying the –debug option to the command line. In this mode of execution, gawk loads the AWK source code and then prompts for debugging commands. Gawk can only debug AWK program source provided with the -f and –include options. The debugger is documented in GAWK: Effective AWK Programming.

OPTION FORMAT

Gawk options may be either traditional POSIX-style one letter options, or GNU-style long options. POSIX options start with a single “-”, while long options start with “–”. Long options are provided for both GNU-specific features and for POSIX-mandated features.

Gawk-specific options are typically used in long-option form. Arguments to long options are either joined with the option by an = sign, with no intervening spaces, or they may be provided in the next command line argument. Long options may be abbreviated, as long as the abbreviation remains unique.

Additionally, every long option has a corresponding short option, so that the option’s functionality may be used from within #! executable scripts.

OPTIONS

Gawk accepts the following options. Standard options are listed first, followed by options for gawk extensions, listed alphabetically by short option.

-f program-file

–file program-file

Read the AWK program source from the file program-file, instead of from the first command line argument. Multiple -f (or –file) options may be used. Files read with -f are treated as if they begin with an implicit @namespace "awk" statement.

-F fs

–field-separator fs

Use fs for the input field separator (the value of the FS predefined variable).

-v var=val

–assign var=val Assign the value val to the variable var, before execution of the program begins. Such variable values are available to the BEGIN rule of an AWK program.

-b

–characters-as-bytes

Treat all input data as single-byte characters. In other words, don’t pay any attention to the locale information when attempting to process strings as multibyte characters. The –posix option overrides this one.

-c

–traditional

Run in compatibility mode. In compatibility mode, gawk behaves identically to Brian Kernighan’s awk; none of the GNU-specific extensions are recognized. See GNU EXTENSIONS, below, for more information.

-C

–copyright

Print the short version of the GNU copyright information message on the standard output and exit successfully.

-d[file]

–dump-variables[=file] Print a sorted list of global variables, their types and final values to file. If no file is provided, gawk uses a file named awkvars.out in the current directory.

Having a list of all the global variables is a good way to look for typographical errors in your programs. You would also use this option if you have a large program with a lot of functions, and you want to be sure that your functions don’t inadvertently use global variables that you meant to be local. (This is a particularly easy mistake to make with simple variable names like i, j, and so on.)

-D[file]

–debug[=file] Enable debugging of AWK programs. By default, the debugger reads commands interactively from the keyboard (standard input). The optional file argument specifies a file with a list of commands for the debugger to execute non-interactively.

-e program-text

–source program-text

Use program-text as AWK program source code. This option allows the easy intermixing of library functions (used via the -f and –include options) with source code entered on the command line. It is intended primarily for medium to large AWK programs used in shell scripts. Each argument supplied via -e is treated as if it begins with an implicit @namespace "awk" statement.

-E file

–exec file

Similar to -f, however, this is option is the last one processed. This should be used with #! scripts, particularly for CGI applications, to avoid passing in options or source code (!) on the command line from a URL. This option disables command-line variable assignments.

-g

–gen-pot

Scan and parse the AWK program, and generate a GNU .pot (Portable Object Template) format file on standard output with entries for all localizable strings in the program. The program itself is not executed. See the GNU gettext distribution for more information on .pot files.

-h

–help

Print a relatively short summary of the available options on the standard output. (Per the GNU Coding Standards, these options cause an immediate, successful exit.)

-i include-file

–include include-file

Load an awk source library. This searches for the library using the AWKPATH environment variable. If the initial search fails, another attempt will be made after appending the .awk suffix. The file will be loaded only once (i.e., duplicates are eliminated), and the code does not constitute the main program source. Files read with –include are treated as if they begin with an implicit @namespace "awk" statement.

-l lib

–load lib

Load a gawk extension from the shared library lib. This searches for the library using the AWKLIBPATH environment variable. If the initial search fails, another attempt will be made after appending the default shared library suffix for the platform. The library initialization routine is expected to be named dl_load().

-L [value]

–lint[=value]

Provide warnings about constructs that are dubious or non-portable to other AWK implementations. With an optional argument of fatal, lint warnings become fatal errors. This may be drastic, but its use will certainly encourage the development of cleaner AWK programs. With an optional argument of invalid, only warnings about things that are actually invalid are issued. (This is not fully implemented yet.) With an optional argument of no-ext, warnings about gawk extensions are disabled.

-M

–bignum

Force arbitrary precision arithmetic on numbers. This option has no effect if gawk is not compiled to use the GNU MPFR and GMP libraries. (In such a case, gawk issues a warning.)

-n

–non-decimal-data

Recognize octal and hexadecimal values in input data. Use this option with great caution!

-N

–use-lc-numeric

Force gawk to use the locale’s decimal point character when parsing input data. Although the POSIX standard requires this behavior, and gawk does so when –posix is in effect, the default is to follow traditional behavior and use a period as the decimal point, even in locales where the period is not the decimal point character. This option overrides the default behavior, without the full draconian strictness of the –posix option.

-o[file]

–pretty-print[=file] Output a pretty printed version of the program to file. If no file is provided, gawk uses a file named awkprof.out in the current directory. This option implies –no-optimize.

-O

–optimize

Enable gawk‘s default optimizations upon the internal representation of the program. Currently, this just includes simple constant folding. This option is on by default.

-p[prof-file]

–profile[=prof-file] Start a profiling session, and send the profiling data to prof-file. The default is awkprof.out. The profile contains execution counts of each statement in the program in the left margin and function call counts for each user-defined function. This option implies –no-optimize.

-P

–posix

This turns on compatibility mode, with the following additional restrictions:

•