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

From: Bernhard Voelker <[email-masked]>
Date: Sun, 5 Jul 2020 01:25:25 +0200

On 2020-07-04 00:57, Jonny Grant wrote:
> May I ask if that exit status 137 could be clarified as 128+9, where 9 is
> the KILL signal number in this example please. I've pasted a patch below.

Thanks for the patch - this is always a great basis for discussions.

Well, this 128+9 arithmetic is explained just a couple of lines above,
i.e., where all the value for the exit status are described.
So adding it here again looks like repetition to me.

> Another question, for me it wasn't clear that the "-k 3s" was cumulative
> with the duration 5, so the total being 8. I thought both durations
> both counted from when the command was invoked.
> 
> https://www.gnu.org/software/coreutils/manual/html_node/timeout-invocation.html#timeout-invocation
> ‘-k duration’
> ‘--kill-after=duration’
> Ensure the monitored command is killed by also sending a ‘KILL’ signal,
> after the specified duration. Without this option, if the selected signal
> proves not to be fatal, timeout does not kill the command.
> 
> Could this be clarified as "after the existing duration is added to
> this specified duration, cumulatively from when the command is invoked."?
> I can make another patch if this would be fine, and my understanding is correct.

Good catch, this is only documented in --help output (and therefore in timeout.1):

  -k, --kill-after=DURATION
                 also send a KILL signal if COMMAND is still running
                   this long after the initial signal was sent

What about the attached?

Thanks & have a nice day,
Berny
>From 56e4aa9d0c083b9e49747d51866e80acec1142a2 Mon Sep 17 00:00:00 2001
From: Bernhard Voelker <[email-masked]>
Date: Sun, 5 Jul 2020 01:20:10 +0200
Subject: [PATCH] doc: clarify 'timeout -k' behavior

* doc/coreutils.texi (timeout invocation): Document that the the
duration of --kill-after=DURATION begins when sending the initial
signal.  Also mention that -k does not have any effect if timeout's
duration is 0.

Suggested by Jonny Grant <[email-masked]>.
---
 doc/coreutils.texi | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index c072b1575..80ca2858c 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -18108,9 +18108,19 @@ themselves (like GDB for example).
 @opindex -k
 @opindex --kill-after
 Ensure the monitored @var{command} is killed by also sending a @samp{KILL}
-signal, after the specified @var{duration}.  Without this option, if the
-selected signal proves not to be fatal, @command{timeout} does not kill
-the @var{command}.
+signal.
+
+The specified @var{duration} starts from the point in time when
+@command{timeout} sends the initial signal to @var{command}, i.e.,
+not from the beginning when the @var{command} is started.
+
+This option has no effect if @command{timeout}'s duration is 0 and therefore
+disables the associated timeout.
+
+This option may be useful if the selected signal did not kill the @var{command},
+either because the signal was blocked or ignored, or if the @var{command} takes
+too long (e.g. for cleanup work) to terminate itself within a certain amount
+of time.
 
 @item -s @var{signal}
 @itemx --signal=@var{signal}
-- 
2.27.0