Linux timeout Command Explained for Beginners (with Examples)

Sometimes, when you execute a command in Linux, you might want to run it for a set amount of time. There exists a command line utility - timeout - that's specifically developed for this purpose. In this article, we will discuss the basics of this command using some easy to understand examples.

But before we do that, it's worth mentioning that all examples in this tutorial have been tested on an Ubuntu 18.04 LTS machine.

Linux timeout command

As the name suggests, the timeout command in Linux allows you to execute a command with a time limit. Following is its syntax:

timeout [OPTION] DURATION COMMAND [ARG]...

And here's how the tool's man page explains it:

timeout - run a command with a time limit
Start COMMAND, and kill it if still running after DURATION

Following are some Q&A styled examples that should give you a better idea of how this tool works.

Q1. How to use timeout command?

Basic usage is pretty easy - just execute 'timeout' by specifying in input a timeout value (considered in seconds) as well as the command you want to run.

For example, if you want to timeout a ping command after 5 seconds, here's how you can use timeout in this case.

timeout 5 ping google.com

Q2. How to get the command's exit status in output?

By default, if the timeout command is successful, it returns 124 as the exit status. Following is an example:

In the first case, I let the timeout command run successfully, and as you can see, the exit status was 124. However, during the second run, I forcefully killed the command using Ctrl+C, and in that case, the exit status was 0.

But in case you want timeout to return the input command's status even if timeout runs successfully, you'll have to use the --preserve-status command line option.

For example:

timeout --preserve-status 5 ping google.com

Q3. How to change the signal timeout sends?

No point in guessing that timeout works by sending a signal to the input command so that the latter stops executing by the time deadline approaches. By default, SIGTERM is used by the command.

However, if you want, you can change the signal that's sent by timeout. For this, you'll have to use the -s command-line option and specify as input the signal you want timeout to send.

For example:

timeout -s SIGKILL [COMMAND]

To fetch a list of available signals that you can send, run the following command:

kill -l

Q4. How to make timeout automatically send KILL signal?

Sometimes, you may encounter an input command that continues to run even after timeout sends the initial signal. For cases like these, timeout offers an option '--kill-after'.

Here's how the man page explains it:

-k, --kill-after=DURATION

              also send a KILL signal if COMMAND is still running

              this long after the initial signal was sent

So as you can see, you need to specify a duration to let timeout know after how much time this signal is to be sent.

Conclusion

Depending on the kind of work you do, the timeout command can prove to be quite a handy tool. Here, in this tutorial, we have discussed the majority of the options this utility offers. Once you're done practicing these, you can learn more about timeout by heading to its man page.