1.\" SPDX-License-Identifier: BSD-2-Clause 2.\" 3.\" Copyright (c) 2014 Baptiste Daroussin <bapt@FreeBSD.org> 4.\" Copyright (c) 2025 Aaron LI <aly@aaronly.me> 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd April 3, 2025 29.Dt TIMEOUT 1 30.Os 31.Sh NAME 32.Nm timeout 33.Nd run a command with a time limit 34.Sh SYNOPSIS 35.Nm 36.Op Fl f | Fl -foreground 37.Op Fl k Ar time | Fl -kill-after Ar time 38.Op Fl p | Fl -preserve-status 39.Op Fl s Ar signal | Fl -signal Ar signal 40.Op Fl v | Fl -verbose 41.Ar duration 42.Ar command 43.Op Ar arg ... 44.Sh DESCRIPTION 45.Nm Timeout 46starts the 47.Ar command 48with its 49.Ar arg 50list. 51If the 52.Ar command 53is still running after 54.Ar duration , 55it is killed by sending the 56.Ar signal , 57or 58.Dv SIGTERM 59if the 60.Fl s 61option is unspecified. 62The special 63.Ar duration , 64zero, signifies no limit. 65Therefore, a signal is never sent if 66.Ar duration 67is 0. 68.Pp 69The signal dispositions inherited by the 70.Ar command 71are the same as the dispositions that 72.Nm 73inherited, except for the signal that will be sent upon timeout, 74which is reset to take the default action and should terminate 75the process. 76.Pp 77If 78.Nm 79receives the 80.Dv SIGALRM 81signal, it will behave as if the time limit has been reached 82and send the specified signal to 83.Ar command . 84For any other signals delivered to 85.Nm , 86it will propagate them to 87.Ar command , 88with the exception of 89.Dv SIGKILL 90and 91.Dv SIGSTOP . 92If you want to prevent the 93.Ar command 94from being timed out, send 95.Dv SIGKILL 96to 97.Nm . 98.Pp 99The options are as follows: 100.Bl -tag -width indent 101.It Fl f , Fl -foreground 102Only time out the 103.Ar command 104itself, but do not propagate signals to its descendants. 105See the 106.Sx IMPLEMENTATION NOTES 107section for more details. 108.It Fl k Ar time , Fl -kill-after Ar time 109Send a 110.Dv SIGKILL 111signal if 112.Ar command 113is still running after 114.Ar time 115since the first signal was sent. 116.It Fl p , Fl -preserve-status 117Always exit with the same status as 118.Ar command , 119even if the timeout was reached. 120.It Fl s Ar signal , Fl -signal Ar signal 121Specify the signal to send on timeout. 122By default, 123.Dv SIGTERM 124is sent. 125.It Fl v , Fl -verbose 126Show information to 127.Xr stderr 4 128about timeouts, signals to be sent, and the 129.Ar command 130exits. 131.El 132.Ss Duration Format 133The 134.Ar duration 135and 136.Ar time 137are non-negative integer or real (decimal) numbers, with an optional 138suffix specifying the unit. 139Values without an explicit unit are interpreted as seconds. 140.Pp 141Supported unit suffixes are: 142.Bl -tag -offset indent -width indent -compact 143.It Cm s 144seconds 145.It Cm m 146minutes 147.It Cm h 148hours 149.It Cm d 150days 151.El 152.Sh IMPLEMENTATION NOTES 153If the 154.Fl -foreground 155option is not specified, 156.Nm 157runs as the reaper (see also 158.Xr procctl 2 ) 159of the 160.Ar command 161and its descendants, and will wait for all the descendants to terminate. 162This behavior might cause surprises if there are descendants running 163in the background, because they will ignore 164.Dv SIGINT 165and 166.Dv SIGQUIT 167signals. 168For example, the following command that sends a 169.Dv SIGTERM 170signal will complete in 2 seconds: 171.Dl $ timeout -s TERM 2 sh -c 'sleep 4 & sleep 5' 172However, this command that sends a 173.Dv SIGINT 174signal will complete in 4 seconds: 175.Dl $ timeout -s INT 2 sh -c 'sleep 4 & sleep 5' 176.Sh EXIT STATUS 177If the time limit was reached and the 178.Fl -preserve-status 179option is not specified, the exit status is 124. 180Otherwise, 181.Nm 182exits with the same exit status as the 183.Ar command . 184For example, 185.Nm 186will terminate itself with the same signal if the 187.Ar command 188is terminated by a signal. 189.Pp 190If an error occurred, the following exit values are returned: 191.Bl -tag -offset indent with indent -compact 192.It 125 193An error other than the two described below occurred. 194For example, an invalid duration or signal was specified. 195.It 126 196The 197.Ar command 198was found but could not be executed. 199.It 127 200The 201.Ar command 202could not be found. 203.El 204.Sh EXAMPLES 205Run 206.Xr sleep 1 207with a time limit of 4 seconds. 208Since the command completes in 2 seconds, the exit status is 0: 209.Bd -literal -offset indent 210$ timeout 4 sleep 2 211$ echo $? 2120 213.Ed 214.Pp 215Run 216.Xr sleep 1 217for 4 seconds and terminate process after 2 seconds. 218The exit status is 124 since 219.Fl -preserve-status 220is not used: 221.Bd -literal -offset indent 222$ timeout 2 sleep 4 223$ echo $? 224124 225.Ed 226.Pp 227Same as above but preserving status. 228The exit status is 128 + signal number (15 for 229.Dv SIGTERM ) 230for most shells: 231.Bd -literal -offset indent 232$ timeout --preserve-status 2 sleep 4 233$ echo $? 234143 235.Ed 236.Pp 237Same as above but sending 238.Dv SIGALRM 239(signal number 14) instead of 240.Dv SIGTERM : 241.Bd -literal -offset indent 242$ timeout --preserve-status -s SIGALRM 2 sleep 4 243$ echo $? 244142 245.Ed 246.Pp 247Try to 248.Xr fetch 1 249the PDF version of the 250.Fx 251Handbook. 252Send a 253.Dv SIGTERM 254signal after 1 minute and send a 255.Dv SIGKILL 256signal 5 seconds later if the process refuses to stop: 257.Bd -literal -offset indent 258$ timeout -k 5s 1m fetch \\ 259> https://download.freebsd.org/ftp/doc/en/books/handbook/book.pdf 260.Ed 261.Sh SEE ALSO 262.Xr kill 1 , 263.Xr nohup 1 , 264.Xr signal 3 , 265.Xr daemon 8 266.Sh STANDARDS 267The 268.Nm 269utility is expected to conform to the 270.St -p1003.1-2024 271specification. 272.Sh HISTORY 273The 274.Nm 275command first appeared in 276.Fx 10.3 . 277.Pp 278The initial 279.Fx 280work was compatible with GNU 281.Nm 282by 283.An Padraig Brady , 284from GNU Coreutils 8.21. 285The 286.Nm 287utility first appeared in GNU Coreutils 7.0. 288.Sh AUTHORS 289.An Baptiste Daroussin Aq Mt bapt@FreeBSD.org , 290.An Vsevolod Stakhov Aq Mt vsevolod@FreeBSD.org 291and 292.An Aaron LI Aq Mt aly@aaronly.me 293