How to Use the timeout Command on Linux

Linux laptop displaying a bash promptFatmawati Achmad Zaenuri /

OK, it's enough computer time. You can give processes time limits by setting a maximum time for which they can run with the timeout command. Here is a tutorial to limit current programs with this command.

What is the waiting period for you?

The timeout command allows you to set a time limit a program will be run for. But why do you want to do that?

In one case, you know exactly how long you want to execute a process. A common use case is to have timeout control a logging or data capture program so that log files do not steadily eat up the space on your hard disk.

Another case is when you do not know how long you want to run a process, but you know that you do not want it to run indefinitely. You may have the habit of defining running processes, shrinking the terminal window and forgetting them.

Some programs, even simple utilities, can generate network traffic at levels that can affect the performance of your network. They can also use the resources of a target device, which slows down its performance. (Ping, I'm looking at you.) Leaving these types of programs running for long 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 built-in turnaround time. There is nothing to install; you can use it right away.

Start with timeout

Here is a simple example. For example, with its default command-line options, the ping command will be executed until you stop it by pressing Ctrl + C. If you do not interrupt it, it will continue. .


ping in a terminal window

By using timeout, we can ensure that the ping commands do not work, which increases the network bandwidth and does not harass the device being pinged.

This next command uses timeout to limit the ping. We give 15 seconds of execution for the ping.

wait time 15 ping

wait time 15 ping in a terminal window

After 15 seconds, the ping session is complete and we return to the command line prompt.

ping session completed in a terminal window

Using the timeout with other time units

Note that we do not need to add an "s" behind the timeout 15. assumes that the value is in seconds. You can add an "s", but it really does not make any difference.

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

For ping to run for three minutes, use the following command:

wait time 3m ping

wait time of 3m ping in a terminal window

ping will run for three minutes before the timeout expires and the ping session stops.

ping session running in a terminal widow

Limit data capture with timeout

Some data capture files can grow very quickly. To prevent such files from becoming cumbersome or even problematic, limit the amount of time that the capture program is allowed to run.

In this example, we use tcpdump, a capture network traffic tool. On the test machines on which this article was studied, 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 help of the following command:

wait time 10 sudo tcpdump> capture.txt

<img class="alignnone size-full wp-image-423326" data-pagespeed-lazy-src="" alt="timeout 10 sudo tcpdump> capture.txt in a terminal window "width =" 646 "height =" 77 "src =" / pagespeed_static / 1.JiBnMqyl6S.gif "onload =" pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon ( this); "this.onerror = null; pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon (this);" />

(tcpdump has its own options for recording captured network traffic to a file.This is a hacking fast because we are talking about timeout, not tcpdump.)

tcpdump is starting to capture network traffic and we are waiting 10 seconds. And 10 seconds come and go and tcpdump is still running, and capture.txt is still growing. It will take a rushed Ctrl + C to stop tcpdump.

Checking the size of capture.txt with ls shows that it has increased to 209 KB in seconds. This file was growing fast!

ls -lh capture.txt

ls -lh capture.txt in a terminal window

What happened? Why did not the timeout stop tcpdump?

Everything is related to the signals.

Sending the right signal

When timeout wants to stop a program, it sends the message Signal SIGTERM. This politely asks the program to end. Some programs may choose to ignore the SIGTERM signal. When this happens, we must say that timeout is a little more powerful.

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

The SIGKILL signal can not be "caught, blocked, or ignored" – it always passes. SIGKILL does not politely ask the program to stop. SIGKILL is hiding in the corner with a stopwatch and a cosh.

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

wait time -s SIGKILL 10 sudo tcpdump> capture.txt

<img class="alignnone size-full wp-image-423330" data-pagespeed-lazy-src="" alt="timeout -s SIGKILL 10 sudo tcpdump> capture.txt in a terminal window "width =" 646 "height =" 167 "src =" / pagespeed_static / 1.JiBnMqyl6S.gif "onload =" pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon) "onerror = "this.onerror = null; pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon (this); "/>

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

tcpdump killed in a terminal window

Ask politely first

We can ask timeout to try to stop the program with SIGTERM and send SIGKILL only if SIGTERM did not work.

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

In this command, we ask timeout to let dmesg run for 30 seconds, and then terminate it with the SIGTERM signal. If dmesg is still running after 40 seconds, it means that the diplomatic SIGTERM has been ignored and the expiration time has to send SIGKILL to complete the job.

Dmesg is a utility that can monitor kernel circular buffer messages and display them in a terminal window.

waiting time -k 40 30 dmseg -w

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

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

Exiting dmesg in a terminal window

We know that it was not SIGKILL that stopped dmesg, because SIGKILL always leaves an obituary in the terminal window: "Killed". This did not happen in this case.

Retrieve the exit code from the program

Well-behaved programs return a value to the shell when they terminate. This is known as an exit code. Typically, this is used to tell the shell – or whatever process the program is running – if the program encountered problems running it

timeout provides its own exit code, but we may not care. We are probably more interested in the exit code of the process than control timeout.

This command allows the ping command to run for five seconds. It sends a ping request to a computer called Nostromo, which is on the test network used to find this article.

wait time 5 ping Nostromo.local

wait time 5 ping nostromo.local in a terminal window

The command runs for five seconds and the expiration time ends. We can then check the exit code using this command:

echo $?

ping output and echo $? in a terminal window

The exit code is 124. This is the value that timeout uses to indicate that the program was stopped with SIGTERM. If SIGKILL ends the program, the exit code is 137.

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

wait time 5 ping Nostromo.local
echo $?

wait time 5 ping Nostromo.local in a terminal window with the help of Ctrl + C

If the program execution ends before the timeout, the delay can return the program exit code to the shell.

For this to happen, the program must stop by itself (in other words, it is not over with timeout) and we must use the –preserve-status option.

If we use the -c (number) option with a value of five, ping will only throw five queries. If we grant the timer a duration of one minute, ping will definitely be finished by itself. We can then check the output 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 queries and ends. The exit code is zero.

To verify that the exit code comes from ping, let's force it to generate a different exit code. If we try to ping any IP address that does not exist, ping will fail with an error exit code. We can then use echo to verify 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 can not reach the non-existent device. It therefore signals the error and closes. The exit code is two. This is the exit code that ping uses for general errors.

Definition of basic rules

Timeout is about setting limits for program execution. In case of danger, the log files may saturate your hard drive or forget that you have left a network tool running, put them on hold and let your computer self-regulate.


Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.