timeout invocation (GNU Coreutils 9.0)
Previous: stdbuf invocation, Up: Modified command invocation [Contents][Index]
23.6 timeout: Run a command with a time limit
timeout
runs the given command
and kills it if it is still running after the specified time interval. Synopsis:
timeout [option] duration command [arg]…
command
must not be a special built-in utility (see Special built-in utilities).
The program accepts the following options. Also see Common options. Options must precede operands.
- ‘
--preserve-status
’ Return the exit status of the managed
command
on timeout, rather than a specific exit status indicating a timeout. This is useful if the managedcommand
supports running for an indeterminate amount of time.- ‘
--foreground
’ Don’t create a separate background program group, so that the managed
command
can use the foreground TTY normally. This is needed to support two situations when timing out commands, when not invokingtimeout
from an interactive shell.command
is interactive and needs to read from the terminal for example- the user wants to support sending signals directly to
command
from the terminal (like Ctrl-C for example)
Note in this mode of operation, any children of
command
will not be timed out. Also SIGCONT will not be sent tocommand
, as it’s generally not needed with foreground processes, and can cause intermittent signal delivery issues with programs that are monitors themselves (like GDB for example).- ‘
-k duration
’
‘--kill-after=duration
’ Ensure the monitored
command
is killed by also sending a ‘KILL
’ signal.The specified
duration
starts from the point in time whentimeout
sends the initial signal tocommand
, i.e., not from the beginning when thecommand
is started.This option has no effect if
timeout
’s duration is 0 which disables the associated timeout.This option may be useful if the selected signal did not kill the
command
, either because the signal was blocked or ignored, or if thecommand
takes too long (e.g. for cleanup work) to terminate itself within a certain amount of time.- ‘
-s signal
’
‘--signal=signal
’ Send this
signal
tocommand
on timeout, rather than the default ‘TERM
’ signal.signal
may be a name like ‘HUP
’ or a number. See Signal specifications.- ‘
-v
’
‘--verbose
’ Diagnose to standard error, any signal sent upon timeout.
duration
is a floating point number in either the current or the C locale (see Floating point) followed by an optional unit:
‘s’ for seconds (the default) ‘m’ for minutes ‘h’ for hours ‘d’ for days
A duration of 0 disables the associated timeout. Note that the actual timeout duration is dependent on system conditions, which should be especially considered when specifying sub-second timeouts.
Exit status:
124 if command times out, and --preserve-status is not specified 125 if timeout itself fails 126 if command is found but cannot be invoked 127 if command cannot be found 137 if command or timeout is sent the KILL(9) signal (128+9) the exit status of command otherwise
In case of the ‘KILL(9)
’ signal, timeout
returns with exit status 137, regardless of whether that signal is sent to command
or to timeout
itself, i.e., these cases cannot be distinguished. In the latter case, the command
process may still be alive after timeout
has forcefully been terminated.
Examples:
# Send the default TERM signal after 20s to a short-living 'sleep 1'. # As that terminates long before the given duration, 'timeout' returns # with the same exit status as the command, 0 in this case. timeout 20 sleep 1 # Send the INT signal after 5s to the 'sleep' command. Returns after # 5 seconds with exit status 124 to indicate the sending of the signal. timeout -s INT 5 sleep 20 # Likewise, but the command ignoring the INT signal due to being started # via 'env --ignore-signal'. Thus, 'sleep' terminates regularly after # the full 20 seconds, still 'timeout' returns with exit status 124. timeout -s INT 5s env --ignore-signal=INT sleep 20 # Likewise, but sending the KILL signal 3 seconds after the initial # INT signal. Hence, 'sleep' is forcefully terminated after about # 8 seconds (5+3), and 'timeout' returns with an exit status of 137. timeout -s INT -k 3s 5s env --ignore-signal=INT sleep 20
Previous: stdbuf invocation, Up: Modified command invocation [Contents][Index]