timeoutx
Run a command with a time limit.
Mirrors GNU timeout. Run it as timeoutx, or as gnux timeoutx.
Synopsis
timeoutx [OPTION] DURATION COMMAND [ARG]...GNU reference
Description
timeoutx runs COMMAND and, if it is still running after DURATION, sends it the TERM signal, or the signal -s names. DURATION is a number, possibly decimal or hexadecimal, with an optional unit: s (seconds, the default), m (minutes), h (hours) or d (days); 0 means no limit. -k DURATION also sends KILL if COMMAND is still running that long after the first signal. By default the signal goes to COMMAND's whole process group, so the processes it started stop too; --foreground signals COMMAND alone and leaves it in the terminal's process group, so it can read from the terminal. A signal sent to timeoutx is passed on to COMMAND, and -v reports each signal sent. The exit status is 124 when COMMAND timed out (unless --preserve-status, which keeps COMMAND's own status), 125 when timeoutx itself failed, 126 when COMMAND was found but could not be run, 127 when it was not found, and otherwise COMMAND's status (128+N when signal N ended it, 137 after KILL). Options must come before DURATION. On Windows, which has no signals, the limit still works: TERM and KILL both end COMMAND, so timeoutx is a portable way to bound a step in a script on every platform.
Permissions
Needs execute permission on COMMAND; signaling it needs no more, since timeoutx started it.
Use cases
- Stopping a CI step or
testsuite that hangs instead of letting it run all night. - Bounding a network call such as curl or ssh that may never answer.
- Giving a service a grace period to shut down, then killing it with
-k. - Polling for a condition for at most a minute in a script.
- Limiting a job the same way on Linux, macOS and Windows.
Flags
--foreground when not running timeout directly from a shell prompt, allow COMMAND to read from the TTY and get TTY signals; in this mode, children of COMMAND will not be timed out
--help display this help and exit
-k, --kill-after DURATION also send a KILL signal if COMMAND is still running this long after the initial signal was sent (DURATION)
--preserve-status exit with the same status as COMMAND, even when the command times out
-s, --signal SIGNAL specify the SIGNAL to be sent on timeout; SIGNAL may be a name like 'HUP' or a number
-v, --verbose diagnose to stderr any signal sent upon timeout
--version output version information and exitExamples
Give a test suite 10 minutes before stopping it
timeoutx 10m go test ./...Stop waiting on a slow server after 5 seconds
timeoutx 5 curl -s https://example.com/healthTell a timeout apart from a failure
timeoutx 30s ./migrate.sh; [ $? -eq 124 ] && echox 'migration timed out'Send INT, like Ctrl-C, instead of TERM
timeoutx -s INT 1h ./crawlerKill a server that ignores TERM 10 seconds after asking it to stop
timeoutx -k 10s 1h ./serverReport the signals as they are sent
timeoutx -v 2s sleepx 60Keep the command's own exit status after a timeout
timeoutx --preserve-status 1m ./bench.shLet an interactive command keep reading from the terminal
timeoutx --foreground 5m ssh build-hostWait at most a minute for a file to appear
timeoutx 1m sh -c 'until [ -e ready.flag ]; do sleepx 1; done'Use a fractional limit
timeoutx 0.5 ./probeBound a step in the portable gnux shell (external programs run through envx)
gnux shell -c 'timeoutx 30s envx make test || echox "tests failed or timed out"'Options
Each option has a page of its own, with its usage and examples.
- --foreground: When not running
timeoutdirectly from a shell prompt, allow COMMAND to read from the TTY and get TTY signals; in this mode, children of COMMAND will not be timed out. - -k, --kill-after: Also send a KILL signal if COMMAND is still running this long after the initial signal was sent (DURATION).
- --preserve-status: Exit with the same status as COMMAND, even when the command times out.
- -s, --signal: Specify the SIGNAL to be sent on
timeout; SIGNAL may be a name like 'HUP' or a number. - -v, --verbose: Diagnose to stderr any signal sent upon
timeout.
Exit status
| Status | Meaning |
|---|---|
| 124 | COMMAND timed out (and --preserve-status was not given) |
| 125 | timeoutx itself failed |
| 126 | COMMAND was found but could not be run |
| 127 | COMMAND was not found |
| 137 | COMMAND (or timeoutx) was sent the KILL signal |
| other | the exit status of COMMAND |
Help in the terminal
timeoutx --help # options, first examples, exit status
gnux help timeoutx # this page: the full manual
gnux help timeoutx --OPTION # one option in depth, with its examples