gawk: Options
1
1 2.2 Command-Line Options
1 ========================
1
1 Options begin with a dash and consist of a single character. GNU-style
1 long options consist of two dashes and a keyword. The keyword can be
1 abbreviated, as long as the abbreviation allows the option to be
1 uniquely identified. If the option takes an argument, either the
1 keyword is immediately followed by an equals sign ('=') and the
1 argument's value, or the keyword and the argument's value are separated
1 by whitespace. If a particular option with a value is given more than
1 once, it is the last value that counts.
1
1 Each long option for 'gawk' has a corresponding POSIX-style short
1 option. The long and short options are interchangeable in all contexts.
1 The following list describes options mandated by the POSIX standard:
1
1 '-F FS'
1 '--field-separator FS'
1 Set the 'FS' variable to FS (⇒Field Separators).
1
1 '-f SOURCE-FILE'
1 '--file SOURCE-FILE'
1 Read the 'awk' program source from SOURCE-FILE instead of in the
1 first nonoption argument. This option may be given multiple times;
1 the 'awk' program consists of the concatenation of the contents of
1 each specified SOURCE-FILE.
1
1 '-v VAR=VAL'
1 '--assign VAR=VAL'
1 Set the variable VAR to the value VAL _before_ execution of the
1 program begins. Such variable values are available inside the
1 'BEGIN' rule (⇒Other Arguments).
1
1 The '-v' option can only set one variable, but it can be used more
1 than once, setting another variable each time, like this: 'awk
1 -v foo=1 -v bar=2 ...'.
1
1 CAUTION: Using '-v' to set the values of the built-in
1 variables may lead to surprising results. 'awk' will reset
1 the values of those variables as it needs to, possibly
1 ignoring any initial value you may have given.
1
1 '-W GAWK-OPT'
1 Provide an implementation-specific option. This is the POSIX
1 convention for providing implementation-specific options. These
1 options also have corresponding GNU-style long options. Note that
1 the long options may be abbreviated, as long as the abbreviations
1 remain unique. The full list of 'gawk'-specific options is
1 provided next.
1
1 '--'
1 Signal the end of the command-line options. The following
1 arguments are not treated as options even if they begin with '-'.
1 This interpretation of '--' follows the POSIX argument parsing
1 conventions.
1
1 This is useful if you have file names that start with '-', or in
1 shell scripts, if you have file names that will be specified by the
1 user that could start with '-'. It is also useful for passing
1 options on to the 'awk' program; see ⇒Getopt Function.
1
1 The following list describes 'gawk'-specific options:
1
1 '-b'
1 '--characters-as-bytes'
1 Cause 'gawk' to treat all input data as single-byte characters. In
1 addition, all output written with 'print' or 'printf' is treated as
1 single-byte characters.
1
1 Normally, 'gawk' follows the POSIX standard and attempts to process
1 its input data according to the current locale (⇒Locales).
1 This can often involve converting multibyte characters into wide
1 characters (internally), and can lead to problems or confusion if
1 the input data does not contain valid multibyte characters. This
1 option is an easy way to tell 'gawk', "Hands off my data!"
1
1 '-c'
1 '--traditional'
1 Specify "compatibility mode", in which the GNU extensions to the
1 'awk' language are disabled, so that 'gawk' behaves just like BWK
1 'awk'. ⇒POSIX/GNU, which summarizes the extensions. Also
1 see ⇒Compatibility Mode.
1
1 '-C'
1 '--copyright'
1 Print the short version of the General Public License and then
1 exit.
1
1 '-d'[FILE]
1 '--dump-variables'['='FILE]
1 Print a sorted list of global variables, their types, and final
1 values to FILE. If no FILE is provided, print this list to a file
1 named 'awkvars.out' in the current directory. No space is allowed
1 between the '-d' and FILE, if FILE is supplied.
1
1 Having a list of all global variables is a good way to look for
1 typographical errors in your programs. You would also use this
1 option if you have a large program with a lot of functions, and you
1 want to be sure that your functions don't inadvertently use global
1 variables that you meant to be local. (This is a particularly easy
1 mistake to make with simple variable names like 'i', 'j', etc.)
1
1 '-D'[FILE]
1 '--debug'['='FILE]
1 Enable debugging of 'awk' programs (⇒Debugging). By
1 default, the debugger reads commands interactively from the
1 keyboard (standard input). The optional FILE argument allows you
1 to specify a file with a list of commands for the debugger to
1 execute noninteractively. No space is allowed between the '-D' and
1 FILE, if FILE is supplied.
1
1 '-e' PROGRAM-TEXT
1 '--source' PROGRAM-TEXT
1 Provide program source code in the PROGRAM-TEXT. This option
1 allows you to mix source code in files with source code that you
1 enter on the command line. This is particularly useful when you
1 have library functions that you want to use from your command-line
1 programs (⇒AWKPATH Variable).
1
1 Note that 'gawk' treats each string as if it ended with a newline
1 character (even if it doesn't). This makes building the total
1 program easier.
1
1 CAUTION: At the moment, there is no requirement that each
1 PROGRAM-TEXT be a full syntactic unit. I.e., the following
1 currently works:
1
1 $ gawk -e 'BEGIN { a = 5 ;' -e 'print a }'
1 -| 5
1
1 However, this could change in the future, so it's not a good
1 idea to rely upon this feature.
1
1 '-E' FILE
1 '--exec' FILE
1 Similar to '-f', read 'awk' program text from FILE. There are two
1 differences from '-f':
1
1 * This option terminates option processing; anything else on the
1 command line is passed on directly to the 'awk' program.
1
1 * Command-line variable assignments of the form 'VAR=VALUE' are
1 disallowed.
1
1 This option is particularly necessary for World Wide Web CGI
1 applications that pass arguments through the URL; using this option
1 prevents a malicious (or other) user from passing in options,
1 assignments, or 'awk' source code (via '-e') to the CGI
1 application.(1) This option should be used with '#!' scripts
1 (⇒Executable Scripts), like so:
1
1 #! /usr/local/bin/gawk -E
1
1 AWK PROGRAM HERE ...
1
1 '-g'
1 '--gen-pot'
1 Analyze the source program and generate a GNU 'gettext' portable
1 object template file on standard output for all string constants
11 that have been marked for translation. ⇒
Internationalization, for information about this option.
1
1 '-h'
1 '--help'
1 Print a "usage" message summarizing the short- and long-style
1 options that 'gawk' accepts and then exit.
1
1 '-i' SOURCE-FILE
1 '--include' SOURCE-FILE
1 Read an 'awk' source library from SOURCE-FILE. This option is
1 completely equivalent to using the '@include' directive inside your
1 program. It is very similar to the '-f' option, but there are two
1 important differences. First, when '-i' is used, the program
1 source is not loaded if it has been previously loaded, whereas with
1 '-f', 'gawk' always loads the file. Second, because this option is
1 intended to be used with code libraries, 'gawk' does not recognize
1 such files as constituting main program input. Thus, after
1 processing an '-i' argument, 'gawk' still expects to find the main
1 source code via the '-f' option or on the command line.
1
1 '-l' EXT
1 '--load' EXT
1 Load a dynamic extension named EXT. Extensions are stored as
1 system shared libraries. This option searches for the library
1 using the 'AWKLIBPATH' environment variable. The correct library
1 suffix for your platform will be supplied by default, so it need
1 not be specified in the extension name. The extension
1 initialization routine should be named 'dl_load()'. An alternative
1 is to use the '@load' keyword inside the program to load a shared
11 library. This advanced feature is described in detail in ⇒
Dynamic Extensions.
1
1 '-L'[VALUE]
1 '--lint'['='VALUE]
1 Warn about constructs that are dubious or nonportable to other
1 'awk' implementations. No space is allowed between the '-L' and
1 VALUE, if VALUE is supplied. Some warnings are issued when 'gawk'
1 first reads your program. Others are issued at runtime, as your
1 program executes. With an optional argument of 'fatal', lint
1 warnings become fatal errors. This may be drastic, but its use
1 will certainly encourage the development of cleaner 'awk' programs.
1 With an optional argument of 'invalid', only warnings about things
1 that are actually invalid are issued. (This is not fully
1 implemented yet.)
1
1 Some warnings are only printed once, even if the dubious constructs
1 they warn about occur multiple times in your 'awk' program. Thus,
1 when eliminating problems pointed out by '--lint', you should take
1 care to search for all occurrences of each inappropriate construct.
1 As 'awk' programs are usually short, doing so is not burdensome.
1
1 '-M'
1 '--bignum'
1 Select arbitrary-precision arithmetic on numbers. This option has
1 no effect if 'gawk' is not compiled to use the GNU MPFR and MP
1 libraries (⇒Arbitrary Precision Arithmetic).
1
1 '-n'
1 '--non-decimal-data'
1 Enable automatic interpretation of octal and hexadecimal values in
1 input data (⇒Nondecimal Data).
1
1 CAUTION: This option can severely break old programs. Use
1 with care. Also note that this option may disappear in a
1 future version of 'gawk'.
1
1 '-N'
1 '--use-lc-numeric'
1 Force the use of the locale's decimal point character when parsing
1 numeric input data (⇒Locales).
1
1 '-o'[FILE]
1 '--pretty-print'['='FILE]
1 Enable pretty-printing of 'awk' programs. Implies '--no-optimize'.
1 By default, the output program is created in a file named
1 'awkprof.out' (⇒Profiling). The optional FILE argument
1 allows you to specify a different file name for the output. No
1 space is allowed between the '-o' and FILE, if FILE is supplied.
1
1 NOTE: In the past, this option would also execute your
1 program. This is no longer the case.
1
1 '-O'
1 '--optimize'
1 Enable 'gawk''s default optimizations on the internal
1 representation of the program. At the moment, this includes simple
1 constant folding and tail recursion elimination in function calls.
1
1 These optimizations are enabled by default. This option remains
1 primarily for backwards compatibility. However, it may be used to
1 cancel the effect of an earlier '-s' option (see later in this
1 list).
1
1 '-p'[FILE]
1 '--profile'['='FILE]
1 Enable profiling of 'awk' programs (⇒Profiling). Implies
1 '--no-optimize'. By default, profiles are created in a file named
1 'awkprof.out'. The optional FILE argument allows you to specify a
1 different file name for the profile file. No space is allowed
1 between the '-p' and FILE, if FILE is supplied.
1
1 The profile contains execution counts for each statement in the
1 program in the left margin, and function call counts for each
1 function.
1
1 '-P'
1 '--posix'
1 Operate in strict POSIX mode. This disables all 'gawk' extensions
1 (just like '--traditional') and disables all extensions not allowed
1 by POSIX. ⇒Common Extensions for a summary of the extensions
1 in 'gawk' that are disabled by this option. Also, the following
1 additional restrictions apply:
1
11 * Newlines are not allowed after '?' or ':' (⇒Conditional
Exp).
1
1 * Specifying '-Ft' on the command line does not set the value of
1 'FS' to be a single TAB character (⇒Field Separators).
1
1 * The locale's decimal point character is used for parsing input
1 data (⇒Locales).
1
1 If you supply both '--traditional' and '--posix' on the command
1 line, '--posix' takes precedence. 'gawk' issues a warning if both
1 options are supplied.
1
1 '-r'
1 '--re-interval'
1 Allow interval expressions (⇒Regexp Operators) in regexps.
1 This is now 'gawk''s default behavior. Nevertheless, this option
1 remains (both for backward compatibility and for use in combination
1 with '--traditional').
1
1 '-s'
1 '--no-optimize'
1 Disable 'gawk''s default optimizations on the internal
1 representation of the program.
1
1 '-S'
1 '--sandbox'
1 Disable the 'system()' function, input redirections with 'getline',
1 output redirections with 'print' and 'printf', and dynamic
1 extensions. This is particularly useful when you want to run 'awk'
1 scripts from questionable sources and need to make sure the scripts
1 can't access your system (other than the specified input data
1 file).
1
1 '-t'
1 '--lint-old'
1 Warn about constructs that are not available in the original
1 version of 'awk' from Version 7 Unix (⇒V7/SVR3.1).
1
1 '-V'
1 '--version'
1 Print version information for this particular copy of 'gawk'. This
1 allows you to determine if your copy of 'gawk' is up to date with
1 respect to whatever the Free Software Foundation is currently
1 distributing. It is also useful for bug reports (⇒Bugs).
1
1 As long as program text has been supplied, any other options are
1 flagged as invalid with a warning message but are otherwise ignored.
1
1 In compatibility mode, as a special case, if the value of FS supplied
1 to the '-F' option is 't', then 'FS' is set to the TAB character
1 ('"\t"'). This is true only for '--traditional' and not for '--posix'
1 (⇒Field Separators).
1
1 The '-f' option may be used more than once on the command line. If
1 it is, 'awk' reads its program source from all of the named files, as if
1 they had been concatenated together into one big file. This is useful
1 for creating libraries of 'awk' functions. These functions can be
1 written once and then retrieved from a standard place, instead of having
1 to be included in each individual program. The '-i' option is similar
1 in this regard. (As mentioned in ⇒Definition Syntax, function
1 names must be unique.)
1
1 With standard 'awk', library functions can still be used, even if the
1 program is entered at the keyboard, by specifying '-f /dev/tty'. After
1 typing your program, type 'Ctrl-d' (the end-of-file character) to
1 terminate it. (You may also use '-f -' to read program source from the
1 standard input, but then you will not be able to also use the standard
1 input as a source of data.)
1
1 Because it is clumsy using the standard 'awk' mechanisms to mix
1 source file and command-line 'awk' programs, 'gawk' provides the '-e'
1 option. This does not require you to preempt the standard input for
1 your source code; it allows you to easily mix command-line and library
1 source code (⇒AWKPATH Variable). As with '-f', the '-e' and '-i'
1 options may also be used multiple times on the command line.
1
1 If no '-f' or '-e' option is specified, then 'gawk' uses the first
1 nonoption command-line argument as the text of the program source code.
1
1 If the environment variable 'POSIXLY_CORRECT' exists, then 'gawk'
1 behaves in strict POSIX mode, exactly as if you had supplied '--posix'.
1 Many GNU programs look for this environment variable to suppress
1 extensions that conflict with POSIX, but 'gawk' behaves differently: it
1 suppresses all extensions, even those that do not conflict with POSIX,
1 and behaves in strict POSIX mode. If '--lint' is supplied on the
1 command line and 'gawk' turns on POSIX mode because of
1 'POSIXLY_CORRECT', then it issues a warning message indicating that
1 POSIX mode is in effect. You would typically set this variable in your
1 shell's startup file. For a Bourne-compatible shell (such as Bash), you
1 would add these lines to the '.profile' file in your home directory:
1
1 POSIXLY_CORRECT=true
1 export POSIXLY_CORRECT
1
1 For a C shell-compatible shell,(2) you would add this line to the
1 '.login' file in your home directory:
1
1 setenv POSIXLY_CORRECT true
1
1 Having 'POSIXLY_CORRECT' set is not recommended for daily use, but it
1 is good for testing the portability of your programs to other
1 environments.
1
1 ---------- Footnotes ----------
1
1 (1) For more detail, please see Section 4.4 of RFC 3875
1 (http://www.ietf.org/rfc/rfc3875). Also see the explanatory note sent
1 to the 'gawk' bug mailing list
1 (https://lists.gnu.org/archive/html/bug-gawk/2014-11/msg00022.html).
1
1 (2) Not recommended.
1