timeout

Run sleep 10 and terminate it after 3 seconds

$ timeout 3s sleep 10

$ timeout [[-s|--signal]] [INT|HUP|KILL|...] [5s] [sleep 10]

$ timeout [[-v|--verbose]] [0.5s|1m|1h|1d|...] [command]

$ timeout [[-p|--preserve-status]] [1s|1m|1h|1d|...] [command]

$ timeout [[-k|--kill-after]] [5m] [30s] [command]

timeout [OPTION] DURATION COMMAND [ARG]...
Where DURATION is a number followed by an optional unit: s (seconds, default), m (minutes), h (hours), d (days).

--foreground
    Do not terminate timeout if COMMAND exits; only kill COMMAND itself.

-k DURATION, --kill-after=DURATION
    Send SIGKILL after this DURATION if COMMAND is still running after the initial signal.

--preserve-status
    Exit with the status of COMMAND if it exits before timeout, otherwise with 124 (timeout status).

-s SIGNAL, --signal=SIGNAL
    Specify the signal to send upon timeout. SIGNAL can be a name (e.g., HUP, INT, TERM) or a number. Default is SIGTERM (15).

--verbose
    Display more information about status on stderr.

--help
    Display help message and exit.

--version
    Output version information and exit.

The timeout command is a utility in Linux that allows you to run a command and automatically terminate it if it runs for a specified duration. This is particularly useful for controlling processes that might hang indefinitely, consume excessive resources, or when you need to enforce a maximum execution time for scripts or applications.

When the specified time limit is reached, timeout sends a SIGTERM signal to the command by default, giving it a chance to gracefully shut down. If the command does not exit after an additional grace period (specified by --kill-after), a SIGKILL signal is sent, which forcibly terminates the process.

It's an essential tool for robust shell scripting, continuous integration environments, and managing system resources, ensuring that long-running or misbehaving commands do not indefinitely block other operations or exhaust system memory and CPU. It helps in creating more resilient and predictable automation workflows.

Process Groups: By default, timeout sends signals to the entire process group of the COMMAND. If COMMAND spawns background processes not in its original process group, they might not be terminated. Consider using --foreground or managing sub-processes within the command.

Signal Handling: The COMMAND might catch and ignore SIGTERM or other specified signals. The --kill-after option is crucial in such cases to ensure eventual termination with SIGKILL.

Exit Status: timeout returns 124 if the command times out. If the command exits before timeout, timeout returns the command's exit status. This behavior can be altered by --preserve-status.

By default, timeout sends SIGTERM (signal 15) when the time limit expires. This signal can be caught by programs, allowing them to perform cleanup before exiting.

If a program does not exit after receiving SIGTERM (or the signal specified by --signal), and --kill-after is used, timeout will send SIGKILL (signal 9), which cannot be caught or ignored by the process, ensuring its termination.

A return code of 124 indicates that the command timed out. Any other return code is typically the exit status of the COMMAND itself, unless timeout itself encountered an error.

The timeout command is part of the GNU Coreutils package, a fundamental set of utilities for Unix-like operating systems. It was introduced to provide a standardized and reliable way to enforce execution time limits, filling a common need in scripting and automation where a simple sleep and kill sequence might be race-prone or overly complex to implement robustly for different scenarios. Its inclusion in coreutils ensures its wide availability and consistent behavior across Linux distributions.

kill(1), sleep(1), nohup(1), setsid(1)