9.2.4 The return Statement

As seen in several earlier examples, the body of a user-defined function can contain a return statement. This statement returns control to the calling part of the awk program. It can also be used to return a value for use in the rest of the awk program. It looks like this:

return [expression]

The expression part is optional. Due most likely to an oversight, POSIX does not define what the return value is if you omit the expression. Technically speaking, this makes the returned value undefined, and therefore, unpredictable. In practice, though, all versions of awk simply return an uninitialized value, which acts like the null string when used as a string, and like zero if used in a numeric context.

A return statement without an expression is assumed at the end of every function definition. So, if control reaches the end of the function body, then technically the function returns an unpredictable value. In practice, here too it returns an uninitialized value. awk does not warn you if you use the return value of such a function.

In both cases (returning without an expression and reaching the end of the function body), the return value is different from

return ""

which return an explicit null string.

Most versions of awk issue a fatal error message if you use a return statement outside of a function body.

Sometimes, you want to write a function for what it does, not for what it returns. Such a function corresponds to a void function in C, C++, or Java, or to a procedure in Ada. Thus, it may be appropriate to not return any value; simply bear in mind that you should not be using the return value of such a function.

The following is an example of a user-defined function that returns a value for the largest number among the elements of an array:

function maxelt(vec,   i, ret)
{
     for (i in vec) {
          if (ret == "" || vec[i] > ret)
               ret = vec[i]
     }
     return ret
}

You call maxelt() with one argument, which is an array name. The local variables i and ret are not intended to be arguments; there is nothing to stop you from passing more than one argument to maxelt() but the results would be strange. The extra space before i in the function parameter list indicates that i and ret are local variables. You should follow this convention when defining functions.

The following program uses the maxelt() function. It loads an array, calls maxelt(), and then reports the maximum number in that array:

function maxelt(vec,   i, ret)
{
     for (i in vec) {
          if (ret == "" || vec[i] > ret)
               ret = vec[i]
     }
     return ret
}

# Load all fields of each record into nums.
{
     for(i = 1; i <= NF; i++)
          nums[NR, i] = $i
}

END {
     print maxelt(nums)
}

Given the following input:

 1 5 23 8 16
44 3 5 2 8 26
256 291 1396 2962 100
-6 467 998 1101
99385 11 0 225

the program reports (predictably) that 99,385 is the largest value in the array.