From: Bernhard Voelker Date: Sun, 7 Jun 2020 11:58:14 +0000 (+0100) Subject: doc: timeout: improve documentation of the exit status X-Git-Tag: v9.0~237 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=189776ff3bf34708fba5ffe32aa8720659bddf04;p=thirdparty%2Fcoreutils.git 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 f0684b1c59..3432fb294f 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 14ae88da56..2b5d930e95 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);