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 January 2, 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 k Ar time | Fl -kill-after Ar time 38.Op Fl s Ar sig | Fl -signal Ar sig 39.Op Fl v | Fl -verbose 40.Op Fl -foreground 41.Op Fl -preserve-status 42.Ar duration 43.Ar command 44.Op Ar args ... 45.Sh DESCRIPTION 46.Nm 47starts the 48.Ar command 49with its 50.Ar args . 51If the 52.Ar command 53is still running after 54.Ar duration , 55it is killed. 56By default, 57.Dv SIGTERM 58is sent. 59The special 60.Ar duration , 61zero, signifies no limit. 62Therefore a signal is never sent if 63.Ar duration 64is 0. 65.Pp 66The options are as follows: 67.Bl -tag -width indent 68.It Fl k Ar time , Fl -kill-after Ar time 69Send a 70.Dv SIGKILL 71signal if 72.Ar command 73is still running after 74.Ar time 75after the first signal was sent. 76.It Fl s Ar sig , Fl -signal Ar sig 77Specify the signal to send on timeout. 78By default, 79.Dv SIGTERM 80is sent. 81.It Fl v , Fl -verbose 82Show information to stderr about any signal sent on timeout. 83.It Fl -foreground 84Do not propagate timeout to the children of 85.Ar command . 86.It Fl -preserve-status 87Exit with the same status as 88.Ar command , 89even if it times out and is killed. 90.El 91.Sh DURATION FORMAT 92The 93.Ar duration 94and 95.Ar time 96are non-negative integer or real (decimal) numbers, with an optional 97unit-specifying suffix. 98Values without an explicit unit are interpreted as seconds. 99.Pp 100Supported unit symbols are: 101.Bl -tag -offset indent -width indent -compact 102.It Cm s 103seconds 104.It Cm m 105minutes 106.It Cm h 107hours 108.It Cm d 109days 110.El 111.Sh EXIT STATUS 112If the timeout was not reached, the exit status of 113.Ar command 114is returned. 115.Pp 116If the timeout was reached and 117.Fl -preserve-status 118is set, the exit status of 119.Ar command 120is returned. 121If 122.Fl -preserve-status 123is not set, an exit status of 124 is returned. 124.Pp 125If an invalid parameter is passed to 126.Fl s 127or 128.Fl k , 129the exit status returned is 125. 130.Pp 131If 132.Ar command 133is an otherwise invalid program, the exit status returned is 126. 134.Pp 135If 136.Ar command 137refers to a non-existing program, the exit status returned is 127. 138.Pp 139If 140.Ar command 141exits after receiving a signal, the exit status returned is the signal number 142plus 128. 143.Sh EXAMPLES 144Run 145.Xr sleep 1 146with a time limit of 4 seconds. 147Since the command completes in 2 seconds, the exit status is 0: 148.Bd -literal -offset indent 149$ timeout 4 sleep 2 150$ echo $? 1510 152.Ed 153.Pp 154Run 155.Xr sleep 1 156for 4 seconds and terminate process after 2 seconds. 157124 is returned since no 158.Fl -preserve-status 159is used: 160.Bd -literal -offset indent 161$ timeout 2 sleep 4 162$ echo $? 163124 164.Ed 165.Pp 166Same as above but preserving status. 167Exit status is 128 + signal number (15 for 168.Va SIGTERM ) 169.Bd -literal -offset indent 170$ timeout --preserve-status 2 sleep 4 171$ echo $? 172143 173.Ed 174.Pp 175Same as above but sending 176.Va SIGALRM 177(signal number 14) instead of 178.Va SIGTERM 179.Bd -literal -offset indent 180$ timeout --preserve-status -s SIGALRM 2 sleep 4 181$ echo $? 182142 183.Ed 184.Pp 185Try to 186.Xr fetch 1 187the single page version of the 188.Fx 189Handbook. 190Send a 191.Va SIGTERM 192signal after 1 minute and send a 193.Va SIGKILL 194signal 5 seconds later if the process refuses to stop: 195.Bd -literal -offset indent 196timeout -k 5s 1m fetch \\ 197https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/book.html 198.Ed 199.Sh SEE ALSO 200.Xr kill 1 , 201.Xr signal 3 202.Sh HISTORY 203The 204.Nm 205command first appeared in 206.Fx 10.3 , 207and was imported into 208.Dx 5.9 . 209.Pp 210The 211.Fx 212work is compatible with GNU 213.Nm 214by 215.An Padraig Brady , 216from GNU Coreutils 8.21. 217The 218.Nm 219utility first appeared in GNU Coreutils 7.0. 220.Sh AUTHORS 221.An Baptiste Daroussin Aq Mt bapt@FreeBSD.org 222and 223.An Vsevolod Stakhov Aq Mt vsevolod@FreeBSD.org 224