How to use the command 'timeout' (with examples)

The timeout command is a powerful utility in Unix-like operating systems that allows users to run a specified command but enforce a strict time limit for its execution. The main purpose of this tool is to prevent a command from running indefinitely. If a command exceeds its allotted time, timeout will terminate it, allowing system resources to be managed more effectively. This tool is particularly useful in scripting and automation scenarios where commands might hang or take longer than anticipated.

Use case 1: Run sleep 10 and terminate it after 3 seconds

Code:

timeout 3s sleep 10

Motivation:

In various scenarios, you might want to execute a command but ensure it only runs for a definite period. For instance, using sleep 10 means waiting for 10 seconds before proceeding to the next command. However, if you only want this “pause” for 3 seconds, timeout is an excellent tool. This prevents needless waiting, which can be important in scripts where efficiency and time constraints matter.

Explanation:

• timeout: The command being used.
• 3s: This specifies the time limit in seconds. The command will be killed if it exceeds this duration.
• sleep 10: This part specifies the command to run. In this case, ‘sleep’ is a simple command to wait, and ‘10’ indicates it should wait for 10 seconds.

Example Output:

No output will be printed to the terminal, but the command will be terminated after 3 seconds rather than 10 seconds. You can verify this by observing the shortened waiting period.

Use case 2: Send a [s]ignal to the command after the time limit expires

Code:

timeout --signal=INT 5s sleep 10

Motivation:

Sometimes, you might want to send a specific signal to the process when the timeout period expires. By default, timeout sends the SIGTERM signal, but maybe you need a different signal depending on the application’s behavior, like SIGINT, which is akin to a keyboard interrupt (Ctrl+C).

Explanation:

• timeout: The command being used.
• --signal=INT: Specifies the type of signal to send upon timeout. INT is a common signal for interruption, and alternatives include signals like HUP, KILL, etc.
• 5s: Denotes a time limit of 5 seconds.
• sleep 10: Command to run which intends to run for 10 seconds.

Example Output:

The process will terminate upon receiving the SIGINT signal after 5 seconds. The terminal itself may not visually show the signal interaction, but the process will indeed halt due to INT.

Use case 3: Send [v]erbose output to stderr showing signal sent upon timeout

Code:

timeout --verbose 0.5s sleep 10

Motivation:

It can be exceedingly useful for diagnostic purposes to receive detailed output from timeout, informing you specifically what has been done, especially when automating complex systems or troubleshooting. This provides insight into what signal was sent and when.

Explanation:

• timeout: This is the command you’re using.
• --verbose: This option is used to enable verbose output, sending details and actions taken to stderr.
• 0.5s: Sets a short execution window of 0.5 seconds.
• sleep 10: The command to run, which aims to pause for 10 seconds.

Example Output:

The output will display the attempted sleep action and the subsequent sending of the termination signal, indicating that the process exceeded its allowed execution time.

Use case 4: Preserve the exit status of the command regardless of timing out

Code:

timeout --preserve-status 1s sleep 0

Motivation:

In some instances, the exit status of a command is critical, as it dictates how subsequent commands might execute or what conditionals might run in scripts. When using timeout, you have the option to retain this exit status using this option, even if the command is killed.

Explanation:

• timeout: This command utilizes the timeout utility.
• --preserve-status: This option ensures the original exit status of the command is kept.
• 1s: Allows the command to run for only 1 second.
• sleep 0: A zero-second wait command used here to illustrate immediate exit.

Example Output:

The command will exit with whichever status sleep had without interference, allowing scripts to react appropriately.

Use case 5: Send a forceful KILL signal after certain duration if the command ignores initial signal upon timeout

Code:

timeout --kill-after=5m 30s sleep 10

Motivation:

Sometimes, processes fail to respond to typical termination signals and need a more severe intervention, like the KILL signal. This use case ensures that even if a command ignores the first attempt to terminate it, a subsequent and indisputable KILL signal will follow.

Explanation:

• timeout: The command chosen for use here.
• --kill-after=5m: Indicates that if the initial signal isn’t respected, a forceful KILL will be applied after 5 minutes.
• 30s: This value represents the time limit before the initial termination signal.
• sleep 10: The sleep command, again trying to run longer than it is allowed.

Example Output:

Initially, the command sleep will terminate according to the 30s specification, ensuring that if ignored, --kill-after will exercise a KILL signal 5 minutes later if needed.

Conclusion:

The timeout command is a versatile tool in a Linux command-line user’s toolkit. By setting execution time constraints, fine-tuning signal specifics, or even preserving exit signals, you can control and streamline command-line operations more efficiently. By demonstrating these use cases, we reveal how timeout can effectively manage resources, boost script performance, and support robust operational environments in Unix-like systems.