xref: /openbsd-src/usr.bin/timeout/timeout.1 (revision 97a2084b7643ffa49227777ffdd6f8b3f93aec21)

.\"	$OpenBSD: timeout.1,v 1.9 2024/06/16 18:33:56 job Exp $
.\"	$NetBSD: timeout.1,v 1.4 2016/10/13 06:22:26 dholland Exp $
.\"
.\" Copyright (c) 2014 Baptiste Daroussin <bapt@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: head/usr.bin/timeout/timeout.1 268861 2014-07-18 22:56:59Z bapt $
.\"
.Dd $Mdocdate: June 16 2024 $
.Dt TIMEOUT 1
.Os
.Sh NAME
.Nm timeout
.Nd run a command with a time limit
.Sh SYNOPSIS
.Nm
.Op Fl fp
.Op Fl k Ar time
.Op Fl s Ar signal
.Ar duration
.Ar command
.Op Ar arg ...
.Sh DESCRIPTION
The
.Nm
utility executes
.Ar command
and kills it if it is still running after the
specified
.Ar duration .
If
.Ar duration
is 0, the timeout is disabled.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl f , -foreground
Do not propagate the timeout signal to children processes.
.It Fl k Ar time , Fl -kill-after Ns = Ns Ar time
Send a second signal,
.Dv SIGKILL ,
if the command is still running
.Ar time
after the first signal was sent.
.It Fl p , -preserve-status
Always exit with the same status as
.Ar command ,
even if the timeout was reached.
.It Fl s Ar signal , Fl -signal Ns = Ns Ar signal
A non-negative decimal number or symbolic signal name specifying
the signal to send on timeout, instead of the default
.Dv SIGTERM .
.El
.Sh DURATION FORMAT
.Ar duration
and
.Ar time
may contain a decimal fraction.
The value defaults to seconds unless a unit suffix is given.
.Pp
The supported unit suffixes are:
.Pp
.Bl -tag -width Ds -offset indent -compact
.It s
seconds
.It m
minutes
.It h
hours
.It d
days
.El
.Sh EXIT STATUS
The
.Nm
utility may return one of the following statuses:
.Pp
.Bl -tag -width indent -compact
.It 124
The time limit expired and the
.Fl p
flag was not set.
.It 126
The
.Ar command
was found but could not be executed.
.It 127
The
.Ar command
was not found.
.El
.Pp
Otherwise,
.Nm
returns the exit status of the
.Ar command .
.Sh SEE ALSO
.Xr kill 1 ,
.Xr signal 3
.Sh STANDARDS
The
.Nm
utility is compliant with the
.St -p1003.1-2024
specification.
.Sh HISTORY
The
.Nm
utility first appeared in GNU Coreutils 7.0 and has been available since
.Ox 7.0 .