xref: /freebsd/bin/timeout/timeout.1 (revision f126890a) 
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 June 26, 2023
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 -signal Ar sig | Fl s Ar sig
36.Op Fl -preserve-status
37.Op Fl -kill-after Ar time | Fl k Ar time
38.Op Fl -foreground
39.Ar duration
40.Ar command
41.Op Ar args ...
42.Sh DESCRIPTION
43.Nm
44starts the
45.Ar command
46with its
47.Ar args .
48If the
49.Ar command
50is still running after
51.Ar duration ,
52it is killed.
53By default,
54.Dv SIGTERM
55is sent.
56The special
57.Ar duration ,
58zero, signifies no limit.
59Therefore a signal is never sent if
60.Ar duration
61is 0.
62.Pp
63The options are as follows:
64.Bl -tag -width indent
65.It Fl -preserve-status
66Exit with the same status as
67.Ar command ,
68even if it times out and is killed.
69.It Fl -foreground
70Do not propagate timeout to the children of
71.Ar command .
72.It Fl s Ar sig , Fl -signal Ar sig
73Specify the signal to send on timeout.
74By default,
75.Dv SIGTERM
76is sent.
77.It Fl k Ar time , Fl -kill-after Ar time
78Send a
79.Dv SIGKILL
80signal if
81.Ar command
82is still running after
83.Ar time
84after the first signal was sent.
85.El
86.Sh DURATION FORMAT
87.Ar duration
88and
89.Ar time
90are non-negative integer or real (decimal) numbers, with an optional
91unit-specifying suffix.
92Values without an explicit unit are interpreted as seconds.
93.Pp
94Supported unit symbols are:
95.Bl -tag -width indent -compact
96.It Cm s
97seconds
98.It Cm m
99minutes
100.It Cm h
101hours
102.It Cm d
103days
104.El
105.Sh EXIT STATUS
106If the timeout was not reached, the exit status of
107.Ar command
108is returned.
109.Pp
110If the timeout was reached and
111.Fl -preserve-status
112is set, the exit status of
113.Ar command
114is returned.
115If
116.Fl -preserve-status
117is not set, an exit status of 124 is returned.
118.Pp
119If
120.Ar command
121exits after receiving a signal, the exit status returned is the signal number
122plus 128.
123.Pp
124If
125.Ar command
126refers to a non-existing program, the exit status returned is 127.
127.Pp
128If
129.Ar command
130is an otherwise invalid program, the exit status returned is 126.
131.Pp
132If an invalid parameter is passed to
133.Fl s
134or
135.Fl k ,
136the exit status returned is 125.
137.Sh EXAMPLES
138Run
139.Xr sleep 1
140with a time limit of 4 seconds.
141Since the command completes in 2 seconds, the exit status is 0:
142.Bd -literal -offset indent
143$ timeout 4 sleep 2
144$ echo $?
1450
146.Ed
147.Pp
148Run
149.Xr sleep 1
150for 4 seconds and terminate process after 2 seconds.
151124 is returned since no
152.Fl -preserve-status
153is used:
154.Bd -literal -offset indent
155$ timeout 2 sleep 4
156$ echo $?
157124
158.Ed
159.Pp
160Same as above but preserving status.
161Exit status is 128 + signal number (15 for
162.Va SIGTERM ) :
163.Bd -literal -offset indent
164$ timeout --preserve-status 2 sleep 4
165$ echo $?
166143
167.Ed
168.Pp
169Same as above but sending
170.Va SIGALRM
171(signal number 14) instead of
172.Va SIGTERM :
173.Bd -literal -offset indent
174$ timeout --preserve-status -s SIGALRM 2 sleep 4
175$ echo $?
176142
177.Ed
178.Pp
179Try to
180.Xr fetch 1
181the PDF version of the
182.Fx
183Handbook.
184Send a
185.Va SIGTERM
186signal after 1 minute and send a
187.Va SIGKILL
188signal 5 seconds later if the process refuses to stop:
189.Bd -literal -offset indent
190$ timeout -k 5s 1m fetch \\
191> https://download.freebsd.org/ftp/doc/en/books/handbook/book.pdf
192.Ed
193.Sh SEE ALSO
194.Xr kill 1 ,
195.Xr nohup 1 ,
196.Xr signal 3 ,
197.Xr daemon 8
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