timeout and sleep
Limit how long a command runs (timeout -s -k, code 124) and pause (sleep with units s, m, h, d)
timeout runs a command and, if it hasn't finished within the allotted time, sends it a signal (SIGTERM by default). You need it so that a hung curl, check or script doesn't hang forever — in cron, CI, wait loops. sleep simply waits for the given time; together they make the classic "check every second, but no longer than a minute" loop.
Syntax
timeout [options] duration command [arguments…]
sleep number[unit]…
Duration
| Syntax | Meaning |
|---|---|
5 or 5s | 5 seconds (seconds are the default) |
0.5 | half a second — fractional numbers are allowed |
2m / 1h / 1d | minutes / hours / days |
sleep 1m 30s | sleep's multiple arguments add up: 90 seconds |
sleep infinity | wait forever (handy to keep a container from exiting) |
timeout 0 … | the limit is disabled |
timeout options
| Option | What it does |
|---|---|
-s signal | which signal to send when time runs out: TERM (default), INT, HUP, KILL or a number |
-k time | if the command is still alive this long after the first signal — send SIGKILL |
--preserve-status | return the command's own code (e.g. 143 = killed by SIGTERM) instead of 124 |
--foreground | don't move the command to the background: it can read from the terminal and receive Ctrl+C; child processes are then not killed on timeout |
-v | report to stderr which signal was sent |
timeout exit codes
| Code | When |
|---|---|
| the command's code | the command finished on its own in time |
124 | time ran out and the command was sent a signal (other than KILL) |
125 | an error in timeout itself (invalid option or duration) |
126 | the command was found but can't be run (no x permission) |
127 | the command wasn't found |
137 | the command was killed by SIGKILL (-s KILL or -k fired): 128 + 9 |
Examples
# don't wait for the server's reply longer than 5 seconds
timeout 5 curl -s http://localhost:8080/health
# tell "timed out" from "failed"
timeout 10 ./check.sh
rc=$?
if [ "$rc" -eq 124 ]; then echo "timed out"; elif [ "$rc" -ne 0 ]; then echo "error $rc"; fi
# politely ask it to exit, kill it 5 seconds later
timeout -k 5 30 ./long-job.sh
# send the Ctrl+C signal instead of TERM (the program gets to save its state)
timeout -s INT 60 ./collector
# wait for a port to open, but no longer than 30 seconds
timeout 30 bash -c 'until ss -ltn | grep -q ":8080 "; do sleep 1; done'
# the same for a file
timeout 10 bash -c 'while [ ! -f /tmp/ready ]; do sleep 0.5; done' || echo "gave up waiting"
# pauses
sleep 2
sleep 0.2
sleep 1m 30s
sleep infinity &
# collect data for exactly 3 seconds
timeout 3 tail -f /var/log/syslog > sample.log
Pitfalls
- Code 124 isn't the command's error. In
set -escripts and CI checks,timeoutgives a non-zero code 124 when time runs out, even for a "normal"tail -f. Handle it explicitly:timeout 3 tail -f log || [ $? -eq 124 ]. - Functions, aliases and builtins don't work.
timeout 5 cd /tmportimeout 5 my_function— "failed to run command", code 127:timeoutonly runs programs. Wrap them inbash -c '…'. - A signal can be ignored. If the command traps or ignores
SIGTERM, it runs to completion, andtimeoutstill returns 124. The safeguard is-k 5(an extraSIGKILL) or-s KILL. - With
-s KILLand-kthe code is 137, not 124. Check both values. timeoutmoves the command into a background process group. Interactive programs (a password prompt,readfrom the terminal) can't read input, and Ctrl+C doesn't reach them. For those —--foreground.- Inside a pipeline only one element is limited.
cat big | timeout 1 head …limitshead;catgetsSIGPIPE(code 141) after it exits. To limit the whole pipeline —timeout 1 bash -c 'a | b'. sleep 1xandsleep -1are an error with code 1, not a pause. Units are onlys,m,h,d.- A
while sleep 1loop withouttimeoutor a counter can wait forever if the condition is never met.
See also
background · kill · exit-codes · conditions-loops · curl · date