xref: /dragonfly/usr.bin/timeout/timeout.1 (revision e4adeac1) 
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