xref: /openbsd-src/usr.bin/timeout/timeout.1 (revision 97a2084b7643ffa49227777ffdd6f8b3f93aec21)
1.\"	$OpenBSD: timeout.1,v 1.9 2024/06/16 18:33:56 job Exp $
2.\"	$NetBSD: timeout.1,v 1.4 2016/10/13 06:22:26 dholland Exp $
3.\"
4.\" Copyright (c) 2014 Baptiste Daroussin <bapt@FreeBSD.org>
5.\" All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\" $FreeBSD: head/usr.bin/timeout/timeout.1 268861 2014-07-18 22:56:59Z bapt $
29.\"
30.Dd $Mdocdate: June 16 2024 $
31.Dt TIMEOUT 1
32.Os
33.Sh NAME
34.Nm timeout
35.Nd run a command with a time limit
36.Sh SYNOPSIS
37.Nm
38.Op Fl fp
39.Op Fl k Ar time
40.Op Fl s Ar signal
41.Ar duration
42.Ar command
43.Op Ar arg ...
44.Sh DESCRIPTION
45The
46.Nm
47utility executes
48.Ar command
49and kills it if it is still running after the
50specified
51.Ar duration .
52If
53.Ar duration
54is 0, the timeout is disabled.
55.Pp
56The options are as follows:
57.Bl -tag -width Ds
58.It Fl f , -foreground
59Do not propagate the timeout signal to children processes.
60.It Fl k Ar time , Fl -kill-after Ns = Ns Ar time
61Send a second signal,
62.Dv SIGKILL ,
63if the command is still running
64.Ar time
65after the first signal was sent.
66.It Fl p , -preserve-status
67Always exit with the same status as
68.Ar command ,
69even if the timeout was reached.
70.It Fl s Ar signal , Fl -signal Ns = Ns Ar signal
71A non-negative decimal number or symbolic signal name specifying
72the signal to send on timeout, instead of the default
73.Dv SIGTERM .
74.El
75.Sh DURATION FORMAT
76.Ar duration
77and
78.Ar time
79may contain a decimal fraction.
80The value defaults to seconds unless a unit suffix is given.
81.Pp
82The supported unit suffixes are:
83.Pp
84.Bl -tag -width Ds -offset indent -compact
85.It s
86seconds
87.It m
88minutes
89.It h
90hours
91.It d
92days
93.El
94.Sh EXIT STATUS
95The
96.Nm
97utility may return one of the following statuses:
98.Pp
99.Bl -tag -width indent -compact
100.It 124
101The time limit expired and the
102.Fl p
103flag was not set.
104.It 126
105The
106.Ar command
107was found but could not be executed.
108.It 127
109The
110.Ar command
111was not found.
112.El
113.Pp
114Otherwise,
115.Nm
116returns the exit status of the
117.Ar command .
118.Sh SEE ALSO
119.Xr kill 1 ,
120.Xr signal 3
121.Sh STANDARDS
122The
123.Nm
124utility is compliant with the
125.St -p1003.1-2024
126specification.
127.Sh HISTORY
128The
129.Nm
130utility first appeared in GNU Coreutils 7.0 and has been available since
131.Ox 7.0 .
132