From: Bernhard Voelker <mail@bernhard-voelker.de>
Date: Sat, 4 Jul 2020 23:20:10 +0000 (+0200)
Subject: doc: clarify 'timeout -k' behavior
X-Git-Tag: v9.0~214
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=49bd08aea52f88187c5a54475e5b44c7c3f6b6ec;p=thirdparty%2Fcoreutils.git

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 <jg@jguk.org>.
---

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 656b8bc791..15514f1bf3 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -18107,9 +18107,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 which
+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}