--
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 section Specifying how Fields are Separated).
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 section The AWKPATH Environment Variable or --source option is specified, then gawk
will use the first non-option command line argument as the text of the
program source code.
Any additional arguments on the command line are normally treated as
input files to be processed in the order specified. However, an
argument that has the form var=value, means to assign
the value value to the variable var---it does not specify a
file at all.
All these arguments are made available to your awk program in the
ARGV array (see section Built-in Variables). Command line options
and the program text (if present) are omitted from the ARGV
array. All other arguments, including variable assignments, are
included.
The distinction between file name arguments and variable-assignment
arguments is made when awk is about to open the next input file.
At that point in execution, it checks the ``file name'' to see whether
it is really a variable assignment; if so, awk sets the variable
instead of reading a file.
Therefore, the variables actually receive the specified values after all
previously specified files have been read. In particular, the values of
variables assigned in this fashion are not available inside a
BEGIN rule
(see section BEGIN and END Special Patterns begins scanning the argument list.
The values given on the command line are processed for escape sequences
(see section Constant Expressions).
In some earlier implementations of awk, when a variable assignment
occurred before any file names, the assignment would happen before
the BEGIN rule was executed. Some applications came to depend
upon this ``feature.'' When awk was changed to be more consistent,
the -v option was added to accommodate applications that depended
upon this old behavior.
The variable assignment feature is most useful for assigning to variables
such as RS, OFS, and ORS, which control input and
output formats, before scanning the data files. It is also useful for
controlling state if multiple passes are needed over a data file. For
example:
awk 'pass == 1 { pass 1 stuff }
pass == 2 { pass 2 stuff }' pass=1 datafile pass=2 datafile
Given the variable assignment feature, the -F option is not
strictly necessary. It remains for historical compatibility.
The previous section described how awk program files can be named
on the command line with the -f option. In some awk
implementations, you must supply a precise path name for each program
file, unless the file is in the current directory.
But in gawk, if the file name supplied in the -f option
does not contain a /, then gawk searches a list of
directories (called the search path), one by one, looking for a
file with the specified name.
The search path is actually a string consisting of directory names
separated by colons. gawk gets its search path from the
AWKPATH environment variable. If that variable does not exist,
gawk uses the default path, which is
.:/usr/lib/awk:/usr/local/lib/awk. (Programs written by
system administrators should use an AWKPATH variable that
does not include the current directory, ..)
The search path feature is particularly useful for building up libraries
of useful awk functions. The library files can be placed in a
standard directory that is in the default path, and then specified on
the command line with a short file name. Otherwise, the full file name
would have to be typed for each file.
By combining the --source and -f options, your command line
awk programs can use facilities in awk library files.
Path searching is not done if gawk is in compatibility mode.
This is true for both -W compat and -W posix.
See section Command Line Options.
Note: if you want files in the current directory to be found,
you must include the current directory in the path, either by writing
. as an entry in the path, or by writing a null entry in the
path. (A null entry is indicated by starting or ending the path with a
colon, or by placing two colons next to each other (::).) If the
current directory is not included in the path, then files cannot be
found in the current directory. This path search mechanism is identical
to the shell's.
This section describes features and/or command line options from the
previous release of gawk that are either not available in the
current version, or that are still supported but deprecated (meaning that
they will not be in the next release).
For version 2.15 of gawk, the following command line options
from version 2.11.1 are no longer recognized.