File: gawk.info,  Node: Nextfile Statement,  Next: Exit Statement,  Prev: Next Statement,  Up: Statements

7.4.9 The 'nextfile' Statement
------------------------------

The 'nextfile' statement is similar to the 'next' statement.  However,
instead of abandoning processing of the current record, the 'nextfile'
statement instructs 'awk' to stop processing the current data file.

   Upon execution of the 'nextfile' statement, 'FILENAME' is updated to
the name of the next data file listed on the command line, 'FNR' is
reset to one, and processing starts over with the first rule in the
program.  If the 'nextfile' statement causes the end of the input to be
reached, then the code in any 'END' rules is executed.  An exception to
this is when 'nextfile' is invoked during execution of any statement in
an 'END' rule; in this case, it causes the program to stop immediately.
*Note BEGIN/END::.

   The 'nextfile' statement is useful when there are many data files to
process but it isn't necessary to process every record in every file.
Without 'nextfile', in order to move on to the next data file, a program
would have to continue scanning the unwanted records.  The 'nextfile'
statement accomplishes this much more efficiently.

   In 'gawk', execution of 'nextfile' causes additional things to
happen: any 'ENDFILE' rules are executed if 'gawk' is not currently in
an 'END' rule, 'ARGIND' is incremented, and any 'BEGINFILE' rules are
executed.  ('ARGIND' hasn't been introduced yet.  *Note Built-in
Variables::.)

   There is an additional, special, use case with 'gawk'.  'nextfile' is
useful inside a 'BEGINFILE' rule to skip over a file that would
otherwise cause 'gawk' to exit with a fatal error.  In this special
case, 'ENDFILE' rules are not executed.  *Note BEGINFILE/ENDFILE::.

   Although it might seem that 'close(FILENAME)' would accomplish the
same as 'nextfile', this isn't true.  'close()' is reserved for closing
files, pipes, and coprocesses that are opened with redirections.  It is
not related to the main processing that 'awk' does with the files listed
in 'ARGV'.

     NOTE: For many years, 'nextfile' was a common extension.  In
     September 2012, it was accepted for inclusion into the POSIX
     standard.  See the Austin Group website
     (http://austingroupbugs.net/view.php?id=607).

   The current version of BWK 'awk' and 'mawk' also support 'nextfile'.
However, they don't allow the 'nextfile' statement inside function
bodies (*note User-defined::).  'gawk' does; a 'nextfile' inside a
function body reads the first record from the next file and starts
processing it with the first rule in the program, just as any other
'nextfile' statement.