xref: /openbsd-src/usr.bin/timeout/timeout.1 (revision 97a2084b7643ffa49227777ffdd6f8b3f93aec21)
1*97a2084bSjob.\"	$OpenBSD: timeout.1,v 1.9 2024/06/16 18:33:56 job Exp $
22b403d74Sjob.\"	$NetBSD: timeout.1,v 1.4 2016/10/13 06:22:26 dholland Exp $
32b403d74Sjob.\"
42b403d74Sjob.\" Copyright (c) 2014 Baptiste Daroussin <bapt@FreeBSD.org>
52b403d74Sjob.\" All rights reserved.
62b403d74Sjob.\"
72b403d74Sjob.\" Redistribution and use in source and binary forms, with or without
82b403d74Sjob.\" modification, are permitted provided that the following conditions
92b403d74Sjob.\" are met:
102b403d74Sjob.\" 1. Redistributions of source code must retain the above copyright
112b403d74Sjob.\"    notice, this list of conditions and the following disclaimer.
122b403d74Sjob.\" 2. Redistributions in binary form must reproduce the above copyright
132b403d74Sjob.\"    notice, this list of conditions and the following disclaimer in the
142b403d74Sjob.\"    documentation and/or other materials provided with the distribution.
152b403d74Sjob.\"
162b403d74Sjob.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
172b403d74Sjob.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
182b403d74Sjob.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
192b403d74Sjob.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
202b403d74Sjob.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
212b403d74Sjob.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
222b403d74Sjob.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
232b403d74Sjob.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
242b403d74Sjob.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
252b403d74Sjob.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
262b403d74Sjob.\" SUCH DAMAGE.
272b403d74Sjob.\"
282b403d74Sjob.\" $FreeBSD: head/usr.bin/timeout/timeout.1 268861 2014-07-18 22:56:59Z bapt $
292b403d74Sjob.\"
30*97a2084bSjob.Dd $Mdocdate: June 16 2024 $
312b403d74Sjob.Dt TIMEOUT 1
322b403d74Sjob.Os
332b403d74Sjob.Sh NAME
342b403d74Sjob.Nm timeout
352b403d74Sjob.Nd run a command with a time limit
362b403d74Sjob.Sh SYNOPSIS
372b403d74Sjob.Nm
38846b88a7Sjob.Op Fl fp
398e6ed8b7Sjmc.Op Fl k Ar time
4077a16aa3Sjmc.Op Fl s Ar signal
418e6ed8b7Sjmc.Ar duration
428e6ed8b7Sjmc.Ar command
43881f6c5fSkn.Op Ar arg ...
442b403d74Sjob.Sh DESCRIPTION
458e6ed8b7SjmcThe
462b403d74Sjob.Nm
478e6ed8b7Sjmcutility executes
48881f6c5fSkn.Ar command
498e6ed8b7Sjmcand kills it if it is still running after the
508e6ed8b7Sjmcspecified
518e6ed8b7Sjmc.Ar duration .
522b403d74SjobIf
538e6ed8b7Sjmc.Ar duration
548e6ed8b7Sjmcis 0, the timeout is disabled.
558e6ed8b7Sjmc.Pp
568e6ed8b7SjmcThe options are as follows:
578e6ed8b7Sjmc.Bl -tag -width Ds
58846b88a7Sjob.It Fl f , -foreground
59846b88a7SjobDo not propagate the timeout signal to children processes.
608e6ed8b7Sjmc.It Fl k Ar time , Fl -kill-after Ns = Ns Ar time
61f4b494fbSschwarzeSend a second signal,
62f4b494fbSschwarze.Dv SIGKILL ,
63f4b494fbSschwarzeif the command is still running
6403a52c9bSjmc.Ar time
6503a52c9bSjmcafter the first signal was sent.
66846b88a7Sjob.It Fl p , -preserve-status
67846b88a7SjobAlways exit with the same status as
68846b88a7Sjob.Ar command ,
69846b88a7Sjobeven if the timeout was reached.
7077a16aa3Sjmc.It Fl s Ar signal , Fl -signal Ns = Ns Ar signal
7177a16aa3SjmcA non-negative decimal number or symbolic signal name specifying
7277a16aa3Sjmcthe signal to send on timeout, instead of the default
738e6ed8b7Sjmc.Dv SIGTERM .
742b403d74Sjob.El
752b403d74Sjob.Sh DURATION FORMAT
762b403d74Sjob.Ar duration
772b403d74Sjoband
782b403d74Sjob.Ar time
798e6ed8b7Sjmcmay contain a decimal fraction.
808e6ed8b7SjmcThe value defaults to seconds unless a unit suffix is given.
812b403d74Sjob.Pp
828e6ed8b7SjmcThe supported unit suffixes are:
838e6ed8b7Sjmc.Pp
848e6ed8b7Sjmc.Bl -tag -width Ds -offset indent -compact
852b403d74Sjob.It s
862b403d74Sjobseconds
872b403d74Sjob.It m
882b403d74Sjobminutes
892b403d74Sjob.It h
902b403d74Sjobhours
912b403d74Sjob.It d
922b403d74Sjobdays
932b403d74Sjob.El
942b403d74Sjob.Sh EXIT STATUS
9517e3ddc9SchelohaThe
9617e3ddc9Scheloha.Nm
9717e3ddc9Schelohautility may return one of the following statuses:
98f4b494fbSschwarze.Pp
9917e3ddc9Scheloha.Bl -tag -width indent -compact
10017e3ddc9Scheloha.It 124
10117e3ddc9SchelohaThe time limit expired and the
102846b88a7Sjob.Fl p
10317e3ddc9Schelohaflag was not set.
10417e3ddc9Scheloha.It 126
10517e3ddc9SchelohaThe
1062b403d74Sjob.Ar command
10717e3ddc9Schelohawas found but could not be executed.
10817e3ddc9Scheloha.It 127
10917e3ddc9SchelohaThe
11017e3ddc9Scheloha.Ar command
11117e3ddc9Schelohawas not found.
11217e3ddc9Scheloha.El
11317e3ddc9Scheloha.Pp
11417e3ddc9SchelohaOtherwise,
11517e3ddc9Scheloha.Nm
11617e3ddc9Schelohareturns the exit status of the
11717e3ddc9Scheloha.Ar command .
1182b403d74Sjob.Sh SEE ALSO
1192b403d74Sjob.Xr kill 1 ,
1202b403d74Sjob.Xr signal 3
121*97a2084bSjob.Sh STANDARDS
122*97a2084bSjobThe
123*97a2084bSjob.Nm
124*97a2084bSjobutility is compliant with the
125*97a2084bSjob.St -p1003.1-2024
126*97a2084bSjobspecification.
1272b403d74Sjob.Sh HISTORY
1282b403d74SjobThe
1292b403d74Sjob.Nm
130f4b494fbSschwarzeutility first appeared in GNU Coreutils 7.0 and has been available since
131f4b494fbSschwarze.Ox 7.0 .
132