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
This commit is contained in:
Bernhard Voelker committed 2020-06-07 15:41:48 +02:00
1 parent b4ab357e42
commit 189776ff3b
2 files changed
+22 -8

No files matched your search

+7 -2
View File
@@ -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
+15 -6
View File
@@ -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);