11.2 Command-Line Options

Options begin with a dash and consist of a single character. GNU-style long options consist of two dashes and a keyword. The keyword can be abbreviated, as long as the abbreviation allows the option to be uniquely identified. If the option takes an argument, then the keyword is either immediately followed by an equals sign (`=') and the argument's value, or the keyword and the argument's value are separated by whitespace. If a particular option with a value is given more than once, it is the last value that counts.

Each long option for gawk has a corresponding POSIX-style option. The long and short options are interchangeable in all contexts. The options and their meanings are as follows:

-F fs

--field-separator fs

Sets the FS variable to fs (see Field Separators).

-f source-file

--file source-file

Indicates that the awk program is to be found in source-file instead of in the first non-option argument.

-v var=val

--assign var=val

Sets the variable var to the value val before execution of the program begins. Such variable values are available inside the BEGIN rule (see Other Arguments).

The -v option can only set one variable, but it can be used more than once, setting another variable each time, like this: `awk -v foo=1 -v bar=2 ...'.

Caution: Using -v to set the values of the built-in variables may lead to surprising results. awk will reset the values of those variables as it needs to, possibly ignoring any predefined value you may have given.

-mf N

-mr N

Sets various memory limits to the value N. The `f' flag sets the maximum number of fields and the `r' flag sets the maximum record size. These two flags and the -m option are from the Bell Laboratories research version of Unix awk. They are provided for compatibility but otherwise ignored by gawk, since gawk has no predefined limits. (The Bell Laboratories awk no longer needs these options; it continues to accept them to avoid breaking old programs.)

-W gawk-opt

Following the POSIX standard, implementation-specific options are supplied as arguments to the -W option. These options also have corresponding GNU-style long options. Note that the long options may be abbreviated, as long as the abbreviations remain unique. The full list of gawk-specific options is provided next.

--

Signals the end of the command-line options. The following arguments are not treated as options even if they begin with `-'. This interpretation of -- follows the POSIX argument parsing conventions.

This is useful if you have file names that start with `-', or in shell scripts, if you have file names that will be specified by the user that could start with `-'.

The previous list described options mandated by the POSIX standard, as well as options available in the Bell Laboratories version of awk. The following list describes gawk-specific options:

-W compat

-W traditional

--compat

--traditional

Specifies compatibility mode, in which the GNU extensions to the awk language are disabled, so that gawk behaves just like the Bell Laboratories research version of Unix awk. --traditional is the preferred form of this option. See POSIX/GNU, which summarizes the extensions. Also see Compatibility Mode.

-W copyright

--copyright

Print the short version of the General Public License and then exit.

-W copyleft

--copyleft

Just like --copyright. This option may disappear in a future version of gawk.

-W dump-variables[=file]

--dump-variables[=file]

Prints a sorted list of global variables, their types, and final values to file. If no file is provided, gawk prints this list to the file named awkvars.out in the current directory.

Having a list of all 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, etc.)

-W gen-po

--gen-po

Analyzes the source program and generates a GNU gettext Portable Object file on standard output for all string constants that have been marked for translation. See Internationalization, for information about this option.

-W help

-W usage

--help

--usage

Prints a “usage” message summarizing the short and long style options that gawk accepts and then exit.

-W lint[=fatal]

--lint[=fatal]

Warns about constructs that are dubious or nonportable to other awk implementations. Some warnings are issued when gawk first reads your program. Others are issued at runtime, as your program executes. 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.)

-W lint-old

--lint-old

Warns about constructs that are not available in the original version of awk from Version 7 Unix (see V7/SVR3.1).

-W non-decimal-data

--non-decimal-data

Enable automatic interpretation of octal and hexadecimal values in input data (see Nondecimal Data).

Caution: This option can severely break old programs. Use with care.

-W posix

--posix

Operates in strict POSIX mode. This disables all gawk extensions (just like --traditional) and adds the following additional restrictions:

• \x escape sequences are not recognized (see Escape Sequences).

• Newlines do not act as whitespace to separate fields when FS is equal to a single space (see Fields).
• Newlines are not allowed after `?' or `:' (see Conditional Exp).
• The synonym func for the keyword function is not recognized (see Definition Syntax).

• The `**' and `**=' operators cannot be used in place of `^' and `^=' (see Arithmetic Ops, and also see Assignment Ops).

• Specifying `-Ft' on the command-line does not set the value of FS to be a single TAB character (see Field Separators).

• The fflush built-in function is not supported (see I/O Functions).

If you supply both --traditional and --posix on the command line, --posix takes precedence. gawk also issues a warning if both options are supplied.

-W profile[=file]

--profile[=file]

Enable profiling of awk programs (see Profiling). By default, profiles are created in a file named awkprof.out. The optional file argument allows you to specify a different file name for the profile file.

When run with gawk, the profile is just a “pretty printed” version of the program. When run with pgawk, the profile contains execution counts for each statement in the program in the left margin, and function call counts for each function.

-W re-interval

--re-interval

Allows interval expressions (see Regexp Operators) in regexps. Because interval expressions were traditionally not available in awk, gawk does not provide them by default. This prevents old awk programs from breaking.

-W source program-text

--source program-text

Allows you to mix source code in files with source code that you enter on the command line. Program source code is taken from the program-text. This is particularly useful when you have library functions that you want to use from your command-line programs (see AWKPATH Variable).

-W version

--version

Prints version information for this particular copy of gawk. This allows you to determine if your copy of gawk is up to date with respect to whatever the Free Software Foundation is currently distributing. It is also useful for bug reports (see Bugs).

As long as program text has been supplied, any other options are flagged as invalid with a warning message but are otherwise ignored.

In compatibility mode, as a special case, if the value of fs supplied to the -F option is `t', then FS is set to the TAB character ("\t"). This is true only for --traditional and not for --posix (see Field Separators).

The -f option may be used more than once on the command line. If it is, awk reads its program source from all of the named files, as if they had been concatenated together into one big file. This is useful for creating libraries of awk functions. These functions can be written once and then retrieved from a standard place, instead of having to be included into each individual program. (As mentioned in Definition Syntax, function names must be unique.)

Library functions can still be used, even if the program is entered at the terminal, by specifying `-f /dev/tty'. After typing your program, type Ctrl-d (the end-of-file character) to terminate it. (You may also use `-f -' to read program source from the standard input but then you will not be able to also use the standard input as a source of data.)

Because it is clumsy using the standard awk mechanisms to mix source file and command-line awk programs, gawk provides the --source option. This does not require you to pre-empt the standard input for your source code; it allows you to easily mix command-line and library source code (see AWKPATH Variable).

If no -f or --source option is specified, then gawk uses the first non-option command-line argument as the text of the program source code.

If the environment variable POSIXLY_CORRECT exists, then gawk behaves in strict POSIX mode, exactly as if you had supplied the --posix command-line option. Many GNU programs look for this environment variable to turn on strict POSIX mode. If --lint is supplied on the command line and gawk turns on POSIX mode because of POSIXLY_CORRECT, then it issues a warning message indicating that POSIX mode is in effect. You would typically set this variable in your shell's startup file. For a Bourne-compatible shell (such as bash), you would add these lines to the .profile file in your home directory:

     POSIXLY_CORRECT=true
     export POSIXLY_CORRECT

For a csh-compatible shell,¹ you would add this line to the .login file in your home directory:

     setenv POSIXLY_CORRECT true

Having POSIXLY_CORRECT set is not recommended for daily use, but it is good for testing the portability of your programs to other environments.