Linux laptop showing a bash prompt
Fatmawati Achmad Zaenuri/Shutterstock.com

OK, that’s enough computer time. You can give processes time limits, setting a maximum time they can run for with the timeoutcommand. Here’s a tutorial to putting limits on running programs with this command.

What Does timeout Do For You?

The  timeout command allows you to set a limit on the length of time a program will run for. But why would you want to do that?

One case is when you know exactly how long you want a process to run for. A common use-case is to have timeout control a logging or data-capture program so that the log files don’t relentlessly devour your hard drive space.

Another case is when you don’t know how long you want a process to run for, but you do know you don’t want it to run indefinitely. You might have a habit of setting processes running, minimizing the terminal window, and forgetting about them.

Some programs–even simple utilities—can generate network traffic at levels that can impede the performance of your network. Or they can tie up the resources on a target device, slowing down its performance. (ping, I’m looking at you.) Leaving these types of programs running for extended periods while you’re away from your computer is bad practice.

timeout is part of the GNU Core Utils so Linux and Unix-like operating systems such as macOS all have timeout built right in. There’s nothing to install; you can use it right out of the box.

Getting Started With timeout

Here’s a simple example. For example, with its default command-line options, the ping command will run until you stop it by hitting Ctrl+C. If you don’t interrupt it, it’ll just keep going.

ping 192.168.4.28

ping 192.168.4.28 in a terminal window

By using timeout, we can make sure ping doesn’t run on and on, chewing up network bandwidth and pestering whatever device is being pinged.

This next command uses timeout to time-limit ping. We’re allowing 15 seconds of run time for  ping.

timeout 15 ping 192.168.4.28

timeout 15 ping 192.168.4.28 in a terminal window

After 15 seconds timeout terminates the ping session and we are returned to the command line prompt.

terminated ping session in a terminal window

Using timeout With Other Time Units

Note that we didn’t have to add an “s” behind the 15. timeout assumes the value is in seconds. You could add an “s,” but it really makes no difference.

To use a time value measured in minutes, hours or days add an “m,” an “h,” or a “d.”

To have ping run for three minutes, use the following command:

timeout 3m ping 192.168.4.28

timeout 3m ping 192.168.4.28 in a terminal window

ping will run for three minutes before timeout steps in and halts the ping session.

ping session running in a terminal widow

Limiting Data Capture With timeout

Some data capture files can grow big very quickly. To prevent such files becoming unwieldy or even problematic in size, limit the amount of time the capture program is allowed to run.

In this example, we’re using tcpdump, a network traffic capture tool. On the test machines that this article was researched on, tcpdump was already installed in Ubuntu Linux and Fedora Linux. It had to be installed on Manjaro Linux and Arch Linux, with the following command:

sudo pacman -Syu tcpdump

sudo pacman -Syu tcpdump in a terminal window

We can run tcpdump for 10 seconds with its default options, and redirect its output to a file called capture.txt with the following command:

timeout 10 sudo tcpdump > capture.txt

timeout 10 sudo tcpdump > capture.txt in a terminal window

(tcpdump has its own options to save captured network traffic to a file. This is a quick hack because we’re discussing timeout, not tcpdump.)

tcpdump starts capturing network traffic and we wait for 10 seconds. And 10 seconds comes and goes and tcpdump is still running, and capture.txt is still growing in size. It’s going to take a hasty Ctrl+C to halt tcpdump.

Checking the size of capture.txt with ls shows that it grew to 209K in a matter of seconds. That file was growing fast!

ls -lh capture.txt

ls -lh capture.txt in a terminal window

What happened? Why didn’t timeout stop tcpdump?

It’s all to do with signals.

Sending The Right Signal

When timeout wants to stop a program it sends the SIGTERM signal. This politely asks the program to terminate. Some programs may choose to ignore the SIGTERM signal. When that happens, we need to tell timeout to be a little more forceful.

We can do that by asking timeout to send the SIGKILL signal instead.

The SIGKILL signal cannot be “caught, blocked or ignored”—it always gets through. SIGKILL doesn’t politely ask the program to stop. SIGKILL hides around the corner with a stopwatch and a cosh.

We can use the -s (signal) option to tell timeout to send the SIGKILL signal.

timeout -s SIGKILL 10 sudo tcpdump > capture.txt

timeout -s SIGKILL 10 sudo tcpdump > capture.txt in a terminal window

This time, as soon as 10 seconds have elapsed, tcpdump is stopped.

tcpdump killed in a terminal window

Asking Politely First

We can ask timeout to try to stop the program using SIGTERM, and to only send in SIGKILL if SIGTERM didn’t work.

To do this, we use the -k (kill after) option. The -k option requires a time value as a parameter.

In this command, we’re asking timeout to let dmesg run for 30 seconds, and to then terminate it with the SIGTERM signal. If dmesg is still running after 40 seconds, it means the diplomatic SIGTERM was ignored and timeout should send in SIGKILL to finish the job.

dmesg is a utility that can monitor the kernel ring buffer messages and display them in a terminal window.

timeout -k 40 30 dmseg -w

timeout -k 40 30 dmseg -w in a terminal window

dmesg runs for 30 seconds and stops when it receives the SIGTERM signal.

Output from dmesg in a terminal window

We know it wasn’t SIGKILL that stopped dmesg because SIGKILL always leaves a one-word obituary in the terminal window: “Killed.” That didn’t happen in this case.

Retrieving the Program’s Exit Code

Well-behaved programs pass a value back to the shell when they terminate. This is known as an exit code. Typically this is used to tell the shell–or whatever process launched the program— whether problems were encountered by the program as it ran.

timeout provides its own exit code, but we may not care about that. We are probably more interested in the exit code from the process that timeout is controlling.

This command lets ping run for five seconds. It is pinging a computer called Nostromo, which is on the test network that was used to research this article.

timeout 5 ping Nostromo.local

timeout 5 ping Nostromo.local in a terminal window

The command runs for five seconds and timeout terminates it. We can then check the exit code using this command:

echo $?

output of ping and echo $? in a terminal window

The exit code is 124. This is the value timeout uses to indicate the program was terminated using SIGTERM. If SIGKILL terminates the program, the exit code is 137.

If we interrupt the program with Ctrl+C the exit code from timeout is zero.

timeout 5 ping Nostromo.local
echo $?

timeout 5 ping Nostromo.local in a terminal window using Ctrl+C

If the execution of the program ends before timeout terminates it, timeout can pass the exit code from the program back to the shell.

For this to happen the program must come to a halt of its own accord (in other words, it is not terminated by timeout), and we must use the --preserve-status option.

If we use the -c (count) option with a value of five ping will only fire off five requests. If we give timeout a duration of one minute, ping will have definitely terminated by itself. We can then check the exit value using echo.

timeout --preserve-status 1m ping -c 5 Nostromo.local
echo $?

timeout --preserve-status 1m ping -c 5 Nostromo.local in a terminal window

ping completes its five ping requests and terminates. The exit code is zero.

To verify the exit code is coming from ping, let’s force ping to generate a different exit code. If we try to send ping requests to a non-existent IP address, ping will fail with an error exit code. We can then use echo to check that the exit code is non-zero.

timeout --preserve-status 1m ping -c 5 NotHere.local
echo $?

timeout --preserve-status 1m ping -c 5 NotHere.local in a terminal window

The ping command obviously cannot reach the non-existent device, so it reports the error and closes down. The exit code is two. This is the exit code ping uses for general errors.

Setting Ground Rules

timeout is all about providing some boundaries to running programs. If there’s a danger the log files might overrun your hard drive or that you might forget you left a network tool running, wrap them in timeout and let your computer self-regulate.

Dave McKay Dave McKay
Dave McKay first used computers when punched paper tape was in vogue, and he has been programming ever since. He is now a Data Protection Officer and has worked as a freelance programmer, manager of an international software development team, and an IT services project manager. Dave is a Linux evangelist and open source advocate.
Read Full Bio »