From: Pádraig Brady <P@draigBrady.com>
Date: Mon, 11 Oct 2021 21:04:38 +0000 (+0100)
Subject: doc: timeout --foreground: add clarification on exit status
X-Git-Tag: v9.1~203
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d085678bd6fefa7d8aa2d44f3b604785a9ad30f9;p=thirdparty%2Fcoreutils.git

doc: timeout --foreground: add clarification on exit status

* doc/coreutils.texi (timeout invocation): Add detail on
how --foreground allows timeout(1) to use more standard
exit status as the uncatchable SIGKILL is not sent to itself.
Fixes https://bugs.gnu.org/51135
---

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 8ccee121af..e3ecbdcf86 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -18321,11 +18321,14 @@ Exit status:
 the exit status of @var{command} otherwise
 @end display
 
-In case of the @samp{KILL(9)} signal, @command{timeout} returns with
+In the 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.
+However if the @option{--foreground} option is specified then
+@command{timeout} will not send any signals to its own process,
+and so it will exit with one of the other exit status values detailed above.
 
 Examples: