On 06/06/2020 00:37, Bernhard Voelker wrote:
On 2020-06-01 10:01, Jonny Grant wrote:
My mistake missing that. But could the 137 be listed explicitly?
ie.
"It may be necessary to use the KILL (9) signal, since this signal cannot be
caught, in which case the exit status is
137 (128+9) rather than 124."
thanks for the suggestion.
I think this could still be improved:
there is still the open question what happens when the KILL signal
is sent either to timeout(1) or to COMMAND.
The attached patch tries to clarify.
Thanks for improving that Bernhard.
It's generally easier to scan tables of values, than blocks of text.
How about we add the exit code table to the man page also?
I've adjusted your patch to do that (along with some other tweaks) in the
attached.
cheers,
Pádraig
>From 267e0ce456dda4d468da4a2d002eaf226b35c5d8 Mon Sep 17 00:00:00 2001
From: Bernhard Voelker <m...@bernhard-voelker.de>
Date: Sun, 7 Jun 2020 12:58:14 +0100
Subject: [PATCH] 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
---
doc/coreutils.texi | 9 +++++++--
src/timeout.c | 21 +++++++++++++++------
2 files changed, 22 insertions(+), 8 deletions(-)
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index f0684b1c5..3432fb294 100644
--- 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 14ae88da5..abe00c729 100644
--- 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);
--
2.26.2
