A Complete Guide to the timeout Command in Linux: Syntax, Usage, and Examples

A few months ago, I was managing a Linux server that hosted several critical applications, including a PostgreSQL database.

As part of routine maintenance, I was tasked with setting up automated backups for the database. Everything was going smoothly, until one day I noticed that the backup process was hanging indefinitely and consuming system resources.

This was especially problematic because it was a production server, and any downtime due to high resource usage could have caused performance issues for the users.

After some investigation, I identified that the issue was happening with the pg_dump command, which is used to create a backup of PostgreSQL databases. The command was occasionally hanging when trying to back up large tables, causing the entire backup process to stall

. While the backup was meant to run overnight, sometimes it would take much longer than expected, leaving the server running at full capacity during peak hours.

I knew I needed a way to ensure that if the backup process took too long, it would automatically terminate without impacting the performance of the rest of the server. This is where the timeout command came to my rescue.

I decided to integrate the timeout command into the backup script to ensure the pg_dump command wouldn’t run for longer than a set duration. This would automatically kill the backup process if it ran beyond the expected time limit (e.g., 60 minutes).

In Linux, managing processes and controlling their execution time is essential for system administration and scripting tasks.

The timeout command is a useful utility that allows you to run a command with a time limit.

If the command exceeds the specified time, timeout terminates it, helping prevent runaway processes and resource hogs.

This article will explain the timeout command, its syntax, options, and provide real-world examples of how to use it effectively.

What is the timeout Command?

The timeout command in Linux is used to execute a command with a time constraint. If the command takes longer than the specified duration, timeout will automatically terminate it. This is particularly useful in scenarios where you need to ensure that a program doesn’t hang indefinitely or consume too many system resources.

The basic syntax of the timeout command is as follows:

timeout [OPTION] DURATION COMMAND [ARGUMENTS...]

Where:

• DURATION is the time limit for the command to run (in seconds, minutes, hours, or days).
• COMMAND is the program or script you want to run.
• ARGUMENTS are the arguments passed to the command.

Basic Syntax and Usage

1. Running a Command with a Timeout

To run a command with a specific timeout, simply specify the duration before the command. The duration can be expressed in seconds (default), minutes (m), hours (h), or days (d).

Example 1: Run a command for 10 seconds

timeout 10s sleep 15

In this example:

• The sleep 15 command would normally pause for 15 seconds, but timeout will terminate it after 10 seconds because we specified a timeout of 10 seconds (10s).
• The command will be terminated before completing its 15-second sleep.

2. Running a Command for a Specified Time in Minutes

Example 2: Run a command for 5 minutes

timeout 5m ping google.com

In this example:

• The ping command will run for 5 minutes and then be terminated.
• This is useful when you need to limit the duration of repetitive network commands, such as ping or traceroute.

Understanding timeout Command Options

The timeout command comes with several options to fine-tune its behavior. Some of the most commonly used options are:

1. -s (or --signal): Specify a Signal to Terminate the Command

By default, timeout sends the SIGTERM signal to terminate a command. However, you can specify a different signal if needed using the -s option.

Example 3: Send a SIGKILL signal after 10 seconds

timeout -s SIGKILL 10s sleep 15

In this example:

• The sleep 15 command will be terminated after 10 seconds using the SIGKILL signal, which forcefully kills the process.

You can use any signal name or signal number (e.g., 9 for SIGKILL, 15 for SIGTERM, etc.).

2. -v (or --verbose): Show Verbose Output

The -v option enables verbose output, which provides more information about the command’s termination.

Example 4: Show verbose output

timeout -v 10s sleep 15

This will print messages about the signal sent to the process, such as:

sleep 15 terminated by SIGTERM

3. -t (or --time): Specify the Timeout Time in Seconds

The -t option is the same as specifying the time directly in the command, but it can be used for clarity in scripts or more complex commands.

Example 5: Using -t for timeout

timeout -t 10 sleep 15

This will behave the same as the previous examples with 10s duration, terminating the command after 10 seconds.

4. --preserve-status: Return Exit Status of the Command

By default, timeout returns an exit status indicating whether the command ran to completion or was terminated. The exit status can be 0 for success, 124 if the command times out, or 137 if the command is killed with a signal.

Using --preserve-status allows the exit status of the command to be retained, rather than using the default timeout status.

Example 6: Preserve the status of the command

timeout --preserve-status 10s sleep 15

In this case, the exit status of sleep 15 will be the same as if it had run to completion, which may be helpful for scripts that need to evaluate the success or failure of the original command.

Practical Examples of Using timeout

1. Preventing Long-Running Commands from Hanging

If you have a command that sometimes hangs indefinitely, you can use timeout to ensure it terminates after a specified time.

Example 7: Run tar command with a timeout

timeout 30m tar -czf backup.tar.gz /large/directory

In this case, the tar command is limited to running for 30 minutes. If it exceeds that time (perhaps due to a large file or slow disk), it will be terminated.

2. Limiting Resource-Intensive Commands

For commands that are resource-intensive (such as database backups or data processing), you may want to prevent them from running too long and consuming excessive CPU or memory.

Example 8: Limiting a find command

timeout 5m find / -name "*.log" -exec rm -f {} \;

In this example:

• The find command searches for .log files across the system.
• If the operation takes longer than 5 minutes, timeout terminates it.
• This is helpful for cleaning up large datasets without worrying about the command hanging.

3. Automating Time-Limited Tests

In testing environments, it’s common to want to run a test for a fixed period. You can use timeout to ensure tests don’t run too long.

Example 9: Running automated tests with a timeout

timeout 1h ./run_tests.sh

This ensures that the run_tests.sh script will be terminated after 1 hour, preventing endless test runs.

4. Using timeout in Scripts

You can use timeout in bash scripts to manage long-running processes.

Example 10: Bash script with timeout

#!/bin/bash
# Run the database backup with a timeout

timeout 20m pg_dump mydatabase > backup.sql
if [ $? -eq 124 ]; then
    echo "Backup failed: Timeout reached"
else
    echo "Backup completed successfully"
fi

In this script:

• pg_dump will run for 20 minutes. If it exceeds that time, it will be terminated.
• The script checks the exit status and reports whether the backup was successful or timed out.

Handling Timeout Errors

The exit status of the timeout command can be used to determine the outcome of a command:

• Exit status 0: The command ran successfully and completed within the allotted time.
• Exit status 124: The command was terminated because it exceeded the time limit.
• Exit status 137: The command was killed by a signal (e.g., SIGKILL).

You can check these statuses in scripts to handle timeouts gracefully.

Example 11: Handling timeout exit status in a script

timeout 10s some_command
status=$?

if [ $status -eq 124 ]; then
    echo "The command timed out."
elif [ $status -eq 0 ]; then
    echo "The command completed successfully."
else
    echo "The command failed with status $status."
fi

Conclusion

The timeout command in Linux is a powerful utility for managing process execution times. Whether you’re preventing commands from running indefinitely, limiting resource consumption, or ensuring timely completion of tasks, timeout provides an easy and effective way to handle time-based process management.

By using its various options, such as specifying signals, verbose output, and preserving exit statuses, you can tailor the command’s behavior to meet your specific needs. From system administration to scripting, the timeout command is an invaluable tool for managing long-running processes efficiently and safely.