4.11 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 function called getline that you can use to read input under your explicit control.

The getline function is used in several different ways; it is best avoided until after you are more familiar with the language. The examples that follow include material that has not been covered yet. Therefore, come back and study the getline function after you have reviewed the rest of this Web page and have a good knowledge of how awk works.

The getline function returns one if it finds a record and zero 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. The value is subject to translation in non-English locales.

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. See Retrying Reads After Certain Input Errors 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 (see Command-Line Options), reading lines from files, pipes, and coprocesses is disabled.