1.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD 2.\" 3.\" Copyright (c) 2014 Baptiste Daroussin <bapt@FreeBSD.org> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" 29.Dd October 21, 2021 30.Dt TIMEOUT 1 31.Os 32.Sh NAME 33.Nm timeout 34.Nd run a command with a time limit 35.Sh SYNOPSIS 36.Nm 37.Op Fl -signal Ar sig | Fl s Ar sig 38.Op Fl -preserve-status 39.Op Fl -kill-after Ar time | Fl k Ar time 40.Op Fl -foreground 41.Ar duration 42.Ar command 43.Op Ar args ... 44.Sh DESCRIPTION 45.Nm 46starts the 47.Ar command 48with its 49.Ar args . 50If the 51.Ar command 52is still running after 53.Ar duration , 54it is killed. 55By default, 56.Dv SIGTERM 57is sent. 58The special 59.Ar duration , 60zero, signifies no limit. 61Therefore a signal is never sent if 62.Ar duration 63is 0. 64.Pp 65The options are as follows: 66.Bl -tag -width indent 67.It Fl -preserve-status 68Exit with the same status as 69.Ar command , 70even if it times out and is killed. 71.It Fl -foreground 72Do not propagate timeout to the children of 73.Ar command . 74.It Fl s Ar sig , Fl -signal Ar sig 75Specify the signal to send on timeout. 76By default, 77.Dv SIGTERM 78is sent. 79.It Fl k Ar time , Fl -kill-after Ar time 80Send a 81.Dv SIGKILL 82signal if 83.Ar command 84is still running after 85.Ar time 86after the first signal was sent. 87.El 88.Sh DURATION FORMAT 89.Ar duration 90and 91.Ar time 92are non-negative integer or real (decimal) numbers, with an optional 93unit-specifying suffix. 94Values without an explicit unit are interpreted as seconds. 95.Pp 96Supported unit symbols are: 97.Bl -tag -width indent -compact 98.It Cm s 99seconds 100.It Cm m 101minutes 102.It Cm h 103hours 104.It Cm d 105days 106.El 107.Sh EXIT STATUS 108If the timeout was not reached, the exit status of 109.Ar command 110is returned. 111.Pp 112If the timeout was reached and 113.Fl -preserve-status 114is set, the exit status of 115.Ar command 116is returned. 117If 118.Fl -preserve-status 119is not set, an exit status of 124 is returned. 120.Pp 121If 122.Ar command 123exits after receiving a signal, the exit status returned is the signal number 124plus 128. 125.Pp 126If 127.Ar command 128refers to a non-existing program, the exit status returned is 127. 129.Pp 130If 131.Ar command 132is an otherwise invalid program, the exit status returned is 126. 133.Pp 134If an invalid parameter is passed to 135.Fl s 136or 137.Fl k , 138the exit status returned is 125. 139.Sh EXAMPLES 140Run 141.Xr sleep 1 142with a time limit of 4 seconds. 143Since the command completes in 2 seconds, the exit status is 0: 144.Bd -literal -offset indent 145$ timeout 4 sleep 2 146$ echo $? 1470 148.Ed 149.Pp 150Run 151.Xr sleep 1 152for 4 seconds and terminate process after 2 seconds. 153124 is returned since no 154.Fl -preserve-status 155is used: 156.Bd -literal -offset indent 157$ timeout 2 sleep 4 158$ echo $? 159124 160.Ed 161.Pp 162Same as above but preserving status. 163Exit status is 128 + signal number (15 for 164.Va SIGTERM ) : 165.Bd -literal -offset indent 166$ timeout --preserve-status 2 sleep 4 167$ echo $? 168143 169.Ed 170.Pp 171Same as above but sending 172.Va SIGALRM 173(signal number 14) instead of 174.Va SIGTERM : 175.Bd -literal -offset indent 176$ timeout --preserve-status -s SIGALRM 2 sleep 4 177$ echo $? 178142 179.Ed 180.Pp 181Try to 182.Xr fetch 1 183the PDF version of the 184.Fx 185Handbook. 186Send a 187.Va SIGTERM 188signal after 1 minute and send a 189.Va SIGKILL 190signal 5 seconds later if the process refuses to stop: 191.Bd -literal -offset indent 192$ timeout -k 5s 1m fetch \\ 193> https://download.freebsd.org/ftp/doc/en/books/handbook/book.pdf 194.Ed 195.Sh SEE ALSO 196.Xr kill 1 , 197.Xr signal 3 198.Sh HISTORY 199The 200.Nm 201command first appeared in 202.Fx 10.3 . 203.Sh AUTHORS 204.An Baptiste Daroussin Aq Mt bapt@FreeBSD.org 205and 206.An Vsevolod Stakhov Aq Mt vsevolod@FreeBSD.org 207