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