From 0d76c6de321ecbf2cfda7d681cfce1ca80420be2 Mon Sep 17 00:00:00 2001 From: "Arnold D. Robbins" Date: Tue, 8 Mar 2016 06:36:34 +0200 Subject: Improve return value of system. --- doc/gawk.texi | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) (limited to 'doc/gawk.texi') 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()} -- cgit v1.2.3 From 3952172ea5f501a92c4ccf8595ebaee34d29377d Mon Sep 17 00:00:00 2001 From: "Arnold D. Robbins" Date: Tue, 8 Mar 2016 22:39:57 +0200 Subject: Improve algorithm for system() return value. --- doc/gawk.texi | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) (limited to 'doc/gawk.texi') diff --git a/doc/gawk.texi b/doc/gawk.texi index cfb40b6a..30826891 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -18380,17 +18380,19 @@ When @option{--sandbox} is specified, the @code{system()} function is disabled 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). +signal (bit 7) and if so, the guilty 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. +returned the exit status value divided by 256. In the normal case this +gives the exit status but in the case of death-by-signal it yields +a fractional floating-point value. POSIX states that @command{awk}'s +@code{system()} should return the full 16-bit value. + +@command{gawk} steers a middle ground. +By default, it returns just the exit status. The +@option{--traditional} option causes @command{gawk} to divide +the return vaue by 356, just as Brian Kernighan's @command{awk} does. +With @option{--posix}, it returns the full 16-bit value. 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 -- cgit v1.2.3 From 8b7c7f8cc2e37a72cd71771575cf2c37a9c8d59d Mon Sep 17 00:00:00 2001 From: "Arnold D. Robbins" Date: Thu, 10 Mar 2016 22:21:11 +0200 Subject: Add info to ChangeLog. Update doc some more. --- doc/gawk.texi | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'doc/gawk.texi') diff --git a/doc/gawk.texi b/doc/gawk.texi index 30826891..2c24c8af 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -18385,13 +18385,15 @@ signal (bit 7) and if so, the guilty signal number (bits 0--6). Traditionally, @command{awk}'s @code{system()} function has simply returned the exit status value divided by 256. In the normal case this gives the exit status but in the case of death-by-signal it yields -a fractional floating-point value. POSIX states that @command{awk}'s +a fractional floating-point value.@footnote{In private correspondance, +Dr.@: Kernighan has indicated to me that the way this was done +was probably a mistake.} POSIX states that @command{awk}'s @code{system()} should return the full 16-bit value. @command{gawk} steers a middle ground. By default, it returns just the exit status. The @option{--traditional} option causes @command{gawk} to divide -the return vaue by 356, just as Brian Kernighan's @command{awk} does. +the return vaue by 256, just as Brian Kernighan's @command{awk} does. With @option{--posix}, it returns the full 16-bit value. If the process was killed by a signal, @command{gawk}'s @code{system()} -- cgit v1.2.3 From e3cc36f1f2f7172ea561664e34bec54c3436297a Mon Sep 17 00:00:00 2001 From: "Arnold D. Robbins" Date: Fri, 11 Mar 2016 12:01:44 +0200 Subject: Further improvements in system return value and doc. --- doc/gawk.texi | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) (limited to 'doc/gawk.texi') diff --git a/doc/gawk.texi b/doc/gawk.texi index 2c24c8af..8a523389 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -18391,19 +18391,20 @@ was probably a mistake.} POSIX states that @command{awk}'s @code{system()} should return the full 16-bit value. @command{gawk} steers a middle ground. -By default, it returns just the exit status. The -@option{--traditional} option causes @command{gawk} to divide -the return vaue by 256, just as Brian Kernighan's @command{awk} does. -With @option{--posix}, it returns the full 16-bit value. - -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. +The return values are summarized in @ref{table-system-return-values}. +@float Table,table-system-return-values +@caption{Return values from @code{system()}} +@multitable @columnfractions .40 .60 +@headitem Situation @tab Return value from @code{system()} +@item @option{--traditional} @tab C @code{system()}'s value divided by 256 +@item @option{--posix} @tab C @code{system()}'s value +@item Normal exit of command @tab Command's exit status +@item Death by signal of command @tab 256 + number of murderous signal +@item Death by signal of command with core dump @tab 512 + number of murderous signal +@item Some kind of error @tab @minus{}1 +@end multitable +@end float @end table @cindex sidebar, Controlling Output Buffering with @code{system()} -- cgit v1.2.3