xref: /freebsd/bin/timeout/timeout.1 (revision 0e8011faf58b743cc652e3b2ad0f7671227610df) 
1.\" SPDX-License-Identifier: BSD-2-Clause
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.Dd December 28, 2024
28.Dt TIMEOUT 1
29.Os
30.Sh NAME
31.Nm timeout
32.Nd run a command with a time limit
33.Sh SYNOPSIS
34.Nm
35.Op Fl k Ar time | Fl -kill-after Ar time
36.Op Fl s Ar sig | Fl -signal Ar sig
37.Op Fl -kill-after Ar time | Fl k Ar time
38.Op Fl -foreground
39.Op Fl -preserve-status
40.Ar duration
41.Ar command
42.Op Ar args ...
43.Sh DESCRIPTION
44.Nm
45starts the
46.Ar command
47with its
48.Ar args .
49If the
50.Ar command
51is still running after
52.Ar duration ,
53it is killed.
54By default,
55.Dv SIGTERM
56is sent.
57The special
58.Ar duration ,
59zero, signifies no limit.
60Therefore a signal is never sent if
61.Ar duration
62is 0.
63.Pp
64The options are as follows:
65.Bl -tag -width indent
66.It Fl k Ar time , Fl -kill-after Ar time
67Send a
68.Dv SIGKILL
69signal if
70.Ar command
71is still running after
72.Ar time
73after the first signal was sent.
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 -foreground
80Do not propagate timeout to the children of
81.Ar command .
82.It Fl -preserve-status
83Exit with the same status as
84.Ar command ,
85even if it times out and is killed.
86.El
87.Sh DURATION FORMAT
88The
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 -offset indent -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 an invalid parameter is passed to
122.Fl s
123or
124.Fl k ,
125the exit status returned is 125.
126.Pp
127If
128.Ar command
129is an otherwise invalid program, the exit status returned is 126.
130.Pp
131If
132.Ar command
133refers to a non-existing program, the exit status returned is 127.
134.Pp
135If
136.Ar command
137exits after receiving a signal, the exit status returned is the signal number
138plus 128.
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 nohup 1 ,
198.Xr signal 3 ,
199.Xr daemon 8
200.Sh STANDARDS
201The
202.Nm
203utility is compliant with the
204.St -p1003.1-2024
205specification.
206.Sh HISTORY
207The
208.Nm
209command first appeared in
210.Fx 10.3 .
211.Pp
212The
213.Fx
214work is compatible with GNU
215.Nm
216by
217.An Padraig Brady ,
218from GNU Coreutils 8.21.
219The
220.Nm
221utility first appeared in GNU Coreutils 7.0.
222.Sh AUTHORS
223.An Baptiste Daroussin Aq Mt bapt@FreeBSD.org
224and
225.An Vsevolod Stakhov Aq Mt vsevolod@FreeBSD.org
226