Subject: Re: bug#41634: 'timeout' returning 124 and 133

From: Bernhard Voelker <[email-masked]>
Date: Sat, 6 Jun 2020 01:37:46 +0200

On 2020-06-01 10:01, Jonny Grant wrote:
> My mistake missing that. But could the 137 be listed explicitly?
> ie.
> "It may be  necessary  to  use the KILL (9) signal, since this signal cannot be caught, in which case the exit status is 
> 137 (128+9) rather than 124."

thanks for the suggestion.

I think this could still be improved:
there is still the open question what happens when the KILL signal
is sent either to timeout(1) or to COMMAND.
The attached patch tries to clarify.

Have a nice day,
Berny
>From d4ee1f8ace585124e80a3d6e11c6902e37e9e71f Mon Sep 17 00:00:00 2001
From: Bernhard Voelker <[email-masked]>
Date: Sat, 6 Jun 2020 01:22:00 +0200
Subject: [PATCH] doc: timeout: further clarify exit status after KILL signal

* doc/coreutils.texi (timeout invocation): Document that the exit
status is 137 when the KILL signal is used, regardless of wether that
signal is sent to COMMAND or timeout.
* src/timeout.c (usage): Likewise.

Discussed at https://bugs.gnu.org/41634
---
 doc/coreutils.texi | 8 +++++++-
 src/timeout.c      | 6 +++---
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index f0684b1c5..07494ab0f 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -18143,10 +18143,16 @@ Exit status:
 125 if @command{timeout} itself fails
 126 if @var{command} is found but cannot be invoked
 127 if @var{command} cannot be found
-137 if @var{command} is sent the KILL(9) signal (128+9)
+137 if @var{command} or @command{timeout} is sent the KILL(9) signal (128+9)
 the exit status of @var{command} otherwise
 @end display
 
+In case of the @samp{KILL(9)} signal, @command{timeout} returns with
+exit status 137, regardless of whether that signal is sent to @var{command}
+or to @command{timeout} itself, i.e., these cases cannot be distinguished.
+In the latter case, the @var{command} process may still be alive after
+@command{timeout} has forcefully been terminated.
+
 
 @node Process control
 @chapter Process control
diff --git a/src/timeout.c b/src/timeout.c
index 14ae88da5..9e7cef8f9 100644
--- a/src/timeout.c
+++ b/src/timeout.c
@@ -272,9 +272,9 @@ DURATION is a floating point number with an optional suffix:\n\
 If the command times out, and --preserve-status is not set, then exit with\n\
 status 124.  Otherwise, exit with the status of COMMAND.  If no signal\n\
 is specified, send the TERM signal upon timeout.  The TERM signal kills\n\
-any process that does not block or catch that signal.  It may be necessary\n\
-to use the KILL (9) signal, since this signal cannot be caught, in which\n\
-case the exit status is 128+9 rather than 124.\n"), stdout);
+any process that does not block or catch that signal.\n\
+If the KILL (9) signal - which cannot be caught - is sent to COMMAND or\n\
+timeout, then the exit status is 137 (128+9) rather than 124.\n"), stdout);
       emit_ancillary_info (PROGRAM_NAME);
     }
   exit (status);
-- 
2.26.2