gawk: Nextfile Statement

1 
1 7.4.9 The 'nextfile' Statement
1 ------------------------------
1 
1 The 'nextfile' statement is similar to the 'next' statement.  However,
1 instead of abandoning processing of the current record, the 'nextfile'
1 statement instructs 'awk' to stop processing the current data file.
1 
1    Upon execution of the 'nextfile' statement, 'FILENAME' is updated to
1 the name of the next data file listed on the command line, 'FNR' is
1 reset to one, and processing starts over with the first rule in the
1 program.  If the 'nextfile' statement causes the end of the input to be
1 reached, then the code in any 'END' rules is executed.  An exception to
1 this is when 'nextfile' is invoked during execution of any statement in
1 an 'END' rule; in this case, it causes the program to stop immediately.
1 ⇒BEGIN/END.
1 
1    The 'nextfile' statement is useful when there are many data files to
1 process but it isn't necessary to process every record in every file.
1 Without 'nextfile', in order to move on to the next data file, a program
1 would have to continue scanning the unwanted records.  The 'nextfile'
1 statement accomplishes this much more efficiently.
1 
1    In 'gawk', execution of 'nextfile' causes additional things to
1 happen: any 'ENDFILE' rules are executed if 'gawk' is not currently in
1 an 'END' or 'BEGINFILE' rule, 'ARGIND' is incremented, and any
1 'BEGINFILE' rules are executed.  ('ARGIND' hasn't been introduced yet.
1 ⇒Built-in Variables.)
1 
1    With 'gawk', 'nextfile' is useful inside a 'BEGINFILE' rule to skip
1 over a file that would otherwise cause 'gawk' to exit with a fatal
11 error.  In this case, 'ENDFILE' rules are not executed.  ⇒
 BEGINFILE/ENDFILE.
1 
1    Although it might seem that 'close(FILENAME)' would accomplish the
1 same as 'nextfile', this isn't true.  'close()' is reserved for closing
1 files, pipes, and coprocesses that are opened with redirections.  It is
1 not related to the main processing that 'awk' does with the files listed
1 in 'ARGV'.
1 
1      NOTE: For many years, 'nextfile' was a common extension.  In
1      September 2012, it was accepted for inclusion into the POSIX
1      standard.  See the Austin Group website
1      (http://austingroupbugs.net/view.php?id=607).
1 
1    The current version of BWK 'awk' and 'mawk' also support 'nextfile'.
1 However, they don't allow the 'nextfile' statement inside function
1 bodies (⇒User-defined).  'gawk' does; a 'nextfile' inside a
1 function body reads the first record from the next file and starts
1 processing it with the first rule in the program, just as any other
1 'nextfile' statement.
1