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 8ccee121af011879597d495d7067fd21b63aa2f8..e3ecbdcf8657aaf33c3884631445bdb91a8a6ba5 100644 (file)
--- 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: