Introduction
In the day-to-day of a system administrator or developer, it is common to encounter commands that may take longer than expected or become blocked waiting for input that never arrives. To prevent these processes from consuming resources indefinitely, Linux provides the timeout tool. This command allows setting a maximum time limit for the execution of any other program, sending a termination signal when the time expires. In this article we will see how it works, its syntax, the most useful options, and several practical examples that you can apply immediately in your environment.
What is timeout?
The timeout command belongs to the coreutils package and is available in practically all modern Linux distributions. Its main function is to execute a specified command and terminate it if it exceeds a determined time period. When the time expires, timeout sends by default the SIGTERM signal to the child process; if the process does not respond, you can force the sending of SIGKILL after an additional interval.
Basic Syntax
The simplest way to use timeout is:
timeout duration command [arguments]
The duration can be expressed in seconds (default value), minutes with the suffix m, hours with h, or days with d. For example, 10s, 5m, or 1h30m are valid.
Most Used Options
-s signalor--signal=signal: specifies the signal that will be sent when the time expires (for example, -s SIGKILL).-k timeor--kill-after=time: after sending the initial signal, wait this interval before sending SIGKILL if the process is still active.--preserve-status: returns the exit code of the executed command, even if it was terminated by timeout.--foreground: when the command runs in the background, timeout waits for it to finish in the foreground.
Practical Examples
Below are several scenarios where timeout is especially useful.
Limiting a download with wget
Suppose we want to download a large file but we do not want the operation to extend beyond ten minutes:
timeout 10m wget -c https://example.com/largefile.iso
If the download does not finish in ten minutes, timeout will send SIGTERM to wget, attempting to finish the transfer cleanly.
Running a network test with ping
A continuous ping can consume output indefinitely. To get only ten packets and then stop, we can combine timeout with ping:
timeout 5s ping -i 1 google.com
This will cause ping to run for approximately five seconds, sending one packet per second.
Testing a script that could become blocked
Imagine a backup script that, under certain conditions, gets stuck waiting for a tape that is not available:
timeout 30m ./backup.sh
If the script exceeds thirty minutes, it will be stopped and you can check the logs to identify the cause of the delay.
Combining with the –kill-after option
In some cases, a process ignores SIGTERM and needs a stronger signal. With –kill-after you can specify a grace interval:
timeout -s SIGTERM --kill-after=30s 2m ./slow_process
here, after two minutes SIGTERM is sent; if after thirty seconds the process is still alive, SIGKILL is sent.
Typical Use Cases
- Avoid cron jobs running too long and affecting server performance.
- Limit the execution time of automated tests in continuous integration environments.
- Control the duration of interactive commands that could wait for user input indefinitely.
- Ensure deployment scripts do not hang waiting for responses from external services.
Considerations and Limitations
Although timeout is very useful, there are some points to keep in mind:
- The time counts from the start of the process; if the process spawns children that become detached (for example, via fork and setsid), those children may continue running after timeout has terminated the parent.
- Some programs handle signals in a custom way and may ignore SIGTERM; in those cases it is necessary to use -s SIGKILL or combine with –kill-after.
- The exit code of timeout is 124 when the command is terminated due to exceeding the time; otherwise, it returns the exit code of the executed command (unless –preserve-status is used).
- In very restricted environments (such as containers without a full coreutils) it might not be available; in that case, you can resort to solutions based on signal alarms or tools like expect.
Conclusion
The timeout command is a simple yet powerful tool for adding a time limit to any process in Linux. Whether you need to avoid endless downloads, control automated tests, or ensure your scripts do not get stuck, timeout provides a reliable and configurable way to intervene. By knowing its basic and advanced options, you can easily incorporate it into your daily workflows and improve the stability and predictability of your systems.
This post is also available in ESPAÑOL.