Return to timeout.1 CVS log

Up to [local] / src / usr.bin / timeout

Denote multiple arguments with 'arg ...' not 'args'

A few programs used the plural in their synopsis which doesn't read as
clear as the obvious triple-dot notation.

mdoc(7) .Ar defaults to "file ..." if no arguments are given and consistent
use of 'arg ...' matches that behaviour.

Cleanup a few markups of the same argument so the text keeps reading
naturally;  omit unhelpful parts like 'if optional arguments are given,
they are passed along' for tools like time(1) and timeout(1) that obviously
execute commands with whatever arguments where given -- just like doas(1)
which doesn't mention arguments in its DESCRIPTION in the first place.

For expr(1) the difference between 'expressions' and 'expression ...' is
crucial, as arguments must be passed as individual words.

Feedback millert jmc schwarze deraadt
OK jmc

.\"	$OpenBSD: timeout.1,v 1.4 2022/12/22 19:53:23 kn 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: December 22 2022 $
.Dt TIMEOUT 1
.Os
.Sh NAME
.Nm timeout
.Nd run a command with a time limit
.Sh SYNOPSIS
.Nm
.Op Fl k Ar time
.Op Fl s Ar sig
.Op Fl -foreground
.Op Fl -preserve-status
.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 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 s Ar sig , Fl -signal Ns = Ns Ar sig
Specify the signal to send on timeout, instead of the default
.Dv SIGTERM .
.It Fl -foreground
Do not propagate the timeout signal to children processes.
.It Fl -preserve-status
Always exit with the same status as
.Ar command ,
even if the timeout was reached.
.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
If the timeout was not reached or
.Fl -preserve-status
was set, the exit status of
.Ar command
is returned.
.Pp
If the timeout was reached and
.Fl -preserve-status
was not set, an exit status of 124 is returned.
.Pp
If
.Ar command
exited after receiving a signal, the exit status returned is the signal number
plus 128.
.Sh SEE ALSO
.Xr kill 1 ,
.Xr signal 3
.Sh HISTORY
The
.Nm
utility first appeared in GNU Coreutils 7.0 and has been available since
.Ox 7.0 .