File: gawk.info,  Node: ARGC and ARGV,  Prev: Auto-set,  Up: Built-in Variables

7.5.3 Using 'ARGC' and 'ARGV'
-----------------------------

*note Auto-set:: presented the following program describing the
information contained in 'ARGC' and 'ARGV':

     $ awk 'BEGIN {
     >        for (i = 0; i < ARGC; i++)
     >            print ARGV[i]
     >      }' inventory-shipped mail-list
     -| awk
     -| inventory-shipped
     -| mail-list

In this example, 'ARGV[0]' contains 'awk', 'ARGV[1]' contains
'inventory-shipped', and 'ARGV[2]' contains 'mail-list'.  Notice that
the 'awk' program is not entered in 'ARGV'.  The other command-line
options, with their arguments, are also not entered.  This includes
variable assignments done with the '-v' option (*note Options::).
Normal variable assignments on the command line _are_ treated as
arguments and do show up in the 'ARGV' array.  Given the following
program in a file named 'showargs.awk':

     BEGIN {
         printf "A=%d, B=%d\n", A, B
         for (i = 0; i < ARGC; i++)
             printf "\tARGV[%d] = %s\n", i, ARGV[i]
     }
     END   { printf "A=%d, B=%d\n", A, B }

Running it produces the following:

     $ awk -v A=1 -f showargs.awk B=2 /dev/null
     -| A=1, B=0
     -|        ARGV[0] = awk
     -|        ARGV[1] = B=2
     -|        ARGV[2] = /dev/null
     -| A=1, B=2

   A program can alter 'ARGC' and the elements of 'ARGV'.  Each time
'awk' reaches the end of an input file, it uses the next element of
'ARGV' as the name of the next input file.  By storing a different
string there, a program can change which files are read.  Use '"-"' to
represent the standard input.  Storing additional elements and
incrementing 'ARGC' causes additional files to be read.

   If the value of 'ARGC' is decreased, that eliminates input files from
the end of the list.  By recording the old value of 'ARGC' elsewhere, a
program can treat the eliminated arguments as something other than file
names.

   To eliminate a file from the middle of the list, store the null
string ('""') into 'ARGV' in place of the file's name.  As a special
feature, 'awk' ignores file names that have been replaced with the null
string.  Another option is to use the 'delete' statement to remove
elements from 'ARGV' (*note Delete::).

   All of these actions are typically done in the 'BEGIN' rule, before
actual processing of the input begins.  *Note Split Program:: and *note
Tee Program:: for examples of each way of removing elements from 'ARGV'.

   To actually get options into an 'awk' program, end the 'awk' options
with '--' and then supply the 'awk' program's options, in the following
manner:

     awk -f myprog.awk -- -v -q file1 file2 ...

   The following fragment processes 'ARGV' in order to examine, and then
remove, the previously mentioned command-line options:

     BEGIN {
         for (i = 1; i < ARGC; i++) {
             if (ARGV[i] == "-v")
                 verbose = 1
             else if (ARGV[i] == "-q")
                 debug = 1
             else if (ARGV[i] ~ /^-./) {
                 e = sprintf("%s: unrecognized option -- %c",
                         ARGV[0], substr(ARGV[i], 2, 1))
                 print e > "/dev/stderr"
             } else
                 break
             delete ARGV[i]
         }
     }

   Ending the 'awk' options with '--' isn't necessary in 'gawk'.  Unless
'--posix' has been specified, 'gawk' silently puts any unrecognized
options into 'ARGV' for the 'awk' program to deal with.  As soon as it
sees an unknown option, 'gawk' stops looking for other options that it
might otherwise recognize.  The previous command line with 'gawk' would
be:

     gawk -f myprog.awk -q -v file1 file2 ...

Because '-q' is not a valid 'gawk' option, it and the following '-v' are
passed on to the 'awk' program.  (*Note Getopt Function:: for an 'awk'
library function that parses command-line options.)

   When designing your program, you should choose options that don't
conflict with 'gawk''s, because it will process any options that it
accepts before passing the rest of the command line on to your program.
Using '#!' with the '-E' option may help (*note Executable Scripts:: and
*note Options::).