diff options
Diffstat (limited to 'doc/gawk.texi')
| -rw-r--r-- | doc/gawk.texi | 25 |
1 files changed, 24 insertions, 1 deletions
diff --git a/doc/gawk.texi b/doc/gawk.texi index dcd49e6e..cfb40b6a 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -18338,7 +18338,7 @@ it is all buffered and sent down the pipe to @command{cat} in one shot. @cindex interacting with other programs Execute the operating system command @var{command} and then return to the @command{awk} program. -Return @var{command}'s exit status. +Return @var{command}'s exit status (see further on). For example, if the following fragment of code is put in your @command{awk} program: @@ -18377,6 +18377,29 @@ When @option{--sandbox} is specified, the @code{system()} function is disabled (@pxref{Options}). @end quotation +On POSIX systems, a command's exit status is a 16-bit number. The exit +value passed to the C @code{exit()} function is held in the high-order +eight bits. The low-order bits indicate if the process was killed by a +signal (bit 7) and if so, the signal number (bits 0--6). + +Traditionally, @command{awk}'s @code{system()} function has simply +returned the exit status value and ignored death-by-signal. POSIX +states that @command{awk}'s @code{system()} should return the full +16-bit value. + +@command{gawk} steers a middle ground. With @option{--posix}, it returns +the full 16-bit value. By default, it returns just the exit status. The +@option{--traditional} option forces @command{gawk} to ignore +death-by-signal, in which case @code{system()} returns zero. + +If the process was killed by a signal, @command{gawk}'s @code{system()} +returns 256 + @var{sig}, where @var{sig} is the number of the signal +that killed the process. Since exit values are eight bits, where the +values range from 0--255, using 256 + @var{sig} lets you clearly distinguish +normal exit from death-by-signal. + +If some kind of error occurred, @code{system()} returns @minus{}1. + @end table @cindex sidebar, Controlling Output Buffering with @code{system()} |