File: gawk.info,  Node: Getline,  Next: Read Timeout,  Prev: Multiple Line,  Up: Reading Files

4.10 Explicit Input with 'getline'
==================================

So far we have been getting our input data from 'awk''s main input
stream--either the standard input (usually your keyboard, sometimes the
output from another program) or the files specified on the command line.
The 'awk' language has a special built-in command called 'getline' that
can be used to read input under your explicit control.

   The 'getline' command is used in several different ways and should
_not_ be used by beginners.  The examples that follow the explanation of
the 'getline' command include material that has not been covered yet.
Therefore, come back and study the 'getline' command _after_ you have
reviewed the rest of this Info file and have a good knowledge of how
'awk' works.

   The 'getline' command returns 1 if it finds a record and 0 if it
encounters the end of the file.  If there is some error in getting a
record, such as a file that cannot be opened, then 'getline' returns -1.
In this case, 'gawk' sets the variable 'ERRNO' to a string describing
the error that occurred.

   If 'ERRNO' indicates that the I/O operation may be retried, and
'PROCINFO["INPUT", "RETRY"]' is set, then 'getline' returns -2 instead
of -1, and further calls to 'getline' may be attempted.  *Note Retrying
Input:: for further information about this feature.

   In the following examples, COMMAND stands for a string value that
represents a shell command.

     NOTE: When '--sandbox' is specified (*note Options::), reading
     lines from files, pipes, and coprocesses is disabled.

* Menu:

* Plain Getline::               Using 'getline' with no arguments.
* Getline/Variable::            Using 'getline' into a variable.