DragonFly On-Line Manual Pages

TIMEOUT(1)             DragonFly General Commands Manual            TIMEOUT(1)

NAME
     timeout - run a command with a time limit

SYNOPSIS
     timeout [-f | --foreground] [-k time | --kill-after time]
             [-p | --preserve-status] [-s signal | --signal signal]
             [-v | --verbose] duration command [arg ...]

DESCRIPTION
     Timeout starts the command with its arg list.  If the command is still
     running after duration, it is killed by sending the signal, or SIGTERM if
     the -s option is unspecified.  The special duration, zero, signifies no
     limit.  Therefore, a signal is never sent if duration is 0.

     The signal dispositions inherited by the command are the same as the
     dispositions that timeout inherited, except for the signal that will be
     sent upon timeout, which is reset to take the default action and should
     terminate the process.

     If timeout receives the SIGALRM signal, it will behave as if the time
     limit has been reached and send the specified signal to command.  For any
     other signals delivered to timeout, it will propagate them to command,
     with the exception of SIGKILL and SIGSTOP.  If you want to prevent the
     command from being timed out, send SIGKILL to timeout.

     The options are as follows:

     -f, --foreground
             Only time out the command itself, but do not propagate signals to
             its descendants.  See the IMPLEMENTATION NOTES section for more
             details.

     -k time, --kill-after time
             Send a SIGKILL signal if command is still running after time
             since the first signal was sent.

     -p, --preserve-status
             Always exit with the same status as command, even if the timeout
             was reached.

     -s signal, --signal signal
             Specify the signal to send on timeout.  By default, SIGTERM is
             sent.

     -v, --verbose
             Show information to stderr(4) about timeouts, signals to be sent,
             and the command exits.

   Duration Format
     The duration and time are non-negative integer or real (decimal) numbers,
     with an optional suffix specifying the unit.  Values without an explicit
     unit are interpreted as seconds.

     Supported unit suffixes are:
           s       seconds
           m       minutes
           h       hours
           d       days

IMPLEMENTATION NOTES
     If the --foreground option is not specified, timeout runs as the reaper
     (see also procctl(2)) of the command and its descendants, and will wait
     for all the descendants to terminate.  This behavior might cause
     surprises if there are descendants running in the background, because
     they will ignore SIGINT and SIGQUIT signals.  For example, the following
     command that sends a SIGTERM signal will complete in 2 seconds:
           $ timeout -s TERM 2 sh -c 'sleep 4 & sleep 5'
     However, this command that sends a SIGINT signal will complete in 4
     seconds:
           $ timeout -s INT 2 sh -c 'sleep 4 & sleep 5'

EXIT STATUS
     If the time limit was reached and the --preserve-status option is not
     specified, the exit status is 124.  Otherwise, timeout exits with the
     same exit status as the command.  For example, timeout will terminate
     itself with the same signal if the command is terminated by a signal.

     If an error occurred, the following exit values are returned:

           125     An error other than the two described below occurred.  For
                   example, an invalid duration or signal was specified.

           126     The command was found but could not be executed.

           127     The command could not be found.

EXAMPLES
     Run sleep(1) with a time limit of 4 seconds.  Since the command completes
     in 2 seconds, the exit status is 0:

           $ timeout 4 sleep 2
           $ echo $?
           0

     Run sleep(1) for 4 seconds and terminate process after 2 seconds.  The
     exit status is 124 since --preserve-status is not used:

           $ timeout 2 sleep 4
           $ echo $?
           124

     Same as above but preserving status.  The exit status is 128 + signal
     number (15 for SIGTERM) for most shells:

           $ timeout --preserve-status 2 sleep 4
           $ echo $?
           143

     Same as above but sending SIGALRM (signal number 14) instead of SIGTERM:

           $ timeout --preserve-status -s SIGALRM 2 sleep 4
           $ echo $?
           142

     Try to fetch(1) the single page version of the FreeBSD Handbook.  Send a
     SIGTERM signal after 1 minute and send a SIGKILL signal 5 seconds later
     if the process refuses to stop:

           $ timeout -k 5s 1m fetch \
                 https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/book.html

SEE ALSO
     kill(1), nohup(1), signal(3), daemon(8)

STANDARDS
     The timeout utility is expected to conform to the specification.

HISTORY
     The timeout command first appeared in FreeBSD 10.3, and was imported into
     DragonFly 5.9.

     The initial FreeBSD work was compatible with GNU timeout by Padraig
     Brady, from GNU Coreutils 8.21.  The timeout utility first appeared in
     GNU Coreutils 7.0.

AUTHORS
     Baptiste Daroussin <bapt@FreeBSD.org>,
     Vsevolod Stakhov <vsevolod@FreeBSD.org> and
     Aaron LI <aly@aaronly.me>

DragonFly 6.5-DEVELOPMENT       March 13, 2025       DragonFly 6.5-DEVELOPMENT