Improve return value of system.

1 files changed, 24 insertions, 1 deletions

diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index ff5672a5..4b0af55b 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -17530,7 +17530,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:
@@ -17569,6 +17569,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
 
 @sidebar Controlling Output Buffering with @code{system()}