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 <m...@bernhard-voelker.de>
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 <j...@jguk.org>.
---
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
