Command Line Options
====================

   Options begin with a minus sign, and consist of a single character.
GNU style long named options consist of two minus signs and a keyword
that can be abbreviated if the abbreviation allows the option to be
uniquely identified.  If the option takes an argument, then the keyword
is immediately followed by an equals sign (`=') and the argument's
value.  For brevity, the discussion below only refers to the
traditional short options; however the long and short options are
interchangeable in all contexts.

   Each long named option for `gawk' has a corresponding POSIX-style
option.  The options and their meanings are as follows:

`-F FS'
`--field-separator=FS'
     Sets the `FS' variable to FS (*note Specifying how Fields are
     Separated: 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 below for a fuller explanation).

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

`-W GAWK-OPT'
     Following the POSIX standard, options that are implementation
     specific are supplied as arguments to the `-W' option.  With
     `gawk', these arguments may be separated by commas, or quoted and
     separated by whitespace.  Case is ignored when processing these
     options.  These options also have corresponding GNU style long
     named options.  The following `gawk'-specific options are
     available:

    `-W compat'
    `--compat'
          Specifies "compatibility mode", in which the GNU extensions in
          `gawk' are disabled, so that `gawk' behaves just like Unix
          `awk'.  See Extensions in `gawk' not in POSIX `awk': POSIX/GNU, which summarizes the extensions.  Also see *Note
          Downward Compatibility and Debugging: Compatibility Mode.

    `-W copyleft'
    `-W copyright'
    `--copyleft'
    `--copyright'
          Print the short version of the General Public License.  This
          option may disappear in a future version of `gawk'.

    `-W help'
    `-W usage'
    `--help'
    `--usage'
          Print a "usage" message summarizing the short and long style
          options that `gawk' accepts, and then exit.

    `-W lint'
    `--lint'
          Provide warnings about constructs that are dubious or
          non-portable to other `awk' implementations.  Some warnings
          are issued when `gawk' first reads your program.  Others are
          issued at run-time, as your program executes.

    `-W posix'
    `--posix'
          Operate in strict POSIX mode.  This disables all `gawk'
          extensions (just like `-W compat'), and adds the following
          additional restrictions:

             * `\x' escape sequences are not recognized (*note Constant
               Expressions: Constants.).

             * The synonym `func' for the keyword `function' is not
               recognized (see Syntax of Function Definitions: Definition Syntax.).

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

             * Specifying `-Ft' on the command line does not set the
               value of `FS' to be a single tab character (
see Specifying how Fields are Separated: Field Separators.).

          Although you can supply both `-W compat' and `-W posix' on the
          command line, `-W posix' will take precedence.

    `-W source=PROGRAM-TEXT'
    `--source=PROGRAM-TEXT'
          Program source code is taken from the PROGRAM-TEXT.  This
          option allows you to mix `awk' source code in files with
          program source code that you would enter on the command line.
          This is particularly useful when you have library functions
          that you wish to use from your command line programs (
see The `AWKPATH' Environment Variable: AWKPATH Variable.).

    `-W version'
    `--version'
          Prints version information for this particular copy of `gawk'.
          This is so you can determine if your copy of `gawk' is up to
          date with respect to whatever the Free Software Foundation is
          currently distributing.  This option may disappear in a
          future version of `gawk'.

`--'
     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 which could start with `-'.

   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 only true for `-W compat', and not for `-W posix'
(see Specifying how Fields are Separated: Field Separators.).

   If the `-f' option is *not* used, then the first non-option command
line argument is expected to be the program text.

   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.  Useful functions can
be written once, and then retrieved from a standard place, instead of
having to be included into each individual program.  You can still type
in a program at the terminal and use library functions, by specifying
`-f /dev/tty'.  `awk' will read a file from the terminal to use as part
of the `awk' program.  After typing your program, type `Control-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, and allows you to easily mix command line
and library source code (see The `AWKPATH' Environment Variable: AWKPATH Variable.).

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