doc: timeout: improve documentation of the exit status

* doc/coreutils.texi (timeout invocation): Document that the exit
status is 137 when the KILL signal is used, regardless of whether that
signal is sent to COMMAND or timeout.
* src/timeout.c (usage): Likewise. Also split out and expand
on the possible exit status values to a separate table.

Discussed at https://bugs.gnu.org/41634

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index f0684b1c5997ff8090df67a8f644a10ed421cf8e..3432fb294f1f6188fca17049f10b8562ee9ea741 100644 (file)
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -18139,14 +18139,19 @@ which should be especially considered when specifying sub-second timeouts.
 Exit status:
 
 @display
-124 if @var{command} times out
+124 if @var{command} times out, and @option{--preserve-status} is not specified
 125 if @command{timeout} itself fails
 126 if @var{command} is found but cannot be invoked
 127 if @var{command} cannot be found
-137 if @var{command} is sent the KILL(9) signal (128+9)
+137 if @var{command} or @command{timeout} is sent the KILL(9) signal (128+9)
 the exit status of @var{command} otherwise
 @end display
 
+In 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.
 
 @node Process control
 @chapter Process control

diff --git a/src/timeout.c b/src/timeout.c
index 14ae88da563574f1c4376b775afaa2dd31883921..2b5d930e959d7ab6cea0acc1bf9aa43eb3242f6d 100644 (file)
--- a/src/timeout.c
+++ b/src/timeout.c
@@ -269,12 +269,21 @@ DURATION is a floating point number with an optional suffix:\n\
 'd' for days.\nA duration of 0 disables the associated timeout.\n"), stdout);
 
       fputs (_("\n\
-If the command times out, and --preserve-status is not set, then exit with\n\
-status 124.  Otherwise, exit with the status of COMMAND.  If no signal\n\
-is specified, send the TERM signal upon timeout.  The TERM signal kills\n\
-any process that does not block or catch that signal.  It may be necessary\n\
-to use the KILL (9) signal, since this signal cannot be caught, in which\n\
-case the exit status is 128+9 rather than 124.\n"), stdout);
+Upon timeout, send the TERM signal to COMMAND, if no other SIGNAL specified.\n\
+The TERM signal kills any process that does not block or catch that signal.\n\
+It may be necessary to use the KILL signal, since this signal can't be caught.\
+\n"), stdout);
+
+      fputs (_("\n\
+EXIT status:\n\
+  124  if COMMAND times out, and --preserve-status is not specified\n\
+  125  if the timeout command itself fails\n\
+  126  if COMMAND is found but cannot be invoked\n\
+  127  if COMMAND cannot be found\n\
+  137  if COMMAND (or timeout itself) is sent the KILL (9) signal (128+9)\n\
+  -    the exit status of COMMAND otherwise\n\
+"), stdout);
+
       emit_ancillary_info (PROGRAM_NAME);
     }
   exit (status);