usr.bin/timeout/timeout.1

   1 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   2 .\"
   3 .\" Copyright (c) 2014 Baptiste Daroussin <bapt@FreeBSD.org>
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\"
  29 .Dd July 7, 2020
  30 .Dt TIMEOUT 1
  31 .Os
  32 .Sh NAME
  33 .Nm timeout
  34 .Nd run a command with a time limit
  35 .Sh SYNOPSIS
  36 .Nm
  37 .Op Fl -signal Ar sig | Fl s Ar sig
  38 .Op Fl -preserve-status
  39 .Op Fl -kill-after Ar time | Fl k Ar time
  40 .Op Fl -foreground
  41 .Ar duration
  42 .Ar command
  43 .Op Ar args ...
  44 .Sh DESCRIPTION
  45 .Nm
  46 starts the
  47 .Ar command
  48 with its
  49 .Ar args .
  50 If the
  51 .Ar command
  52 is still running after
  53 .Ar duration ,
  54 it is killed.
  55 By default,
  56 .Dv SIGTERM
  57 is sent.
  58 The special
  59 .Ar duration ,
  60 zero, signifies no limit.
  61 Therefore a signal is never sent if
  62 .Ar duration
  63 is 0.
  64 .Pp
  65 The options are as follows:
  66 .Bl -tag -width indent
  67 .It Fl -preserve-status
  68 Exit with the same status as
  69 .Ar command ,
  70 even if it times out and is killed.
  71 .It Fl -foreground
  72 Do not propagate timeout to the children of
  73 .Ar command .
  74 .It Fl s Ar sig , Fl -signal Ar sig
  75 Specify the signal to send on timeout.
  76 By default,
  77 .Dv SIGTERM
  78 is sent.
  79 .It Fl k Ar time , Fl -kill-after Ar time
  80 Send a
  81 .Dv SIGKILL
  82 signal if
  83 .Ar command
  84 is still running after
  85 .Ar time
  86 after the first signal was sent.
  87 .El
  88 .Sh DURATION FORMAT
  89 .Ar duration
  90 and
  91 .Ar time
  92 are non-negative integer or real (decimal) numbers, with an optional
  93 unit-specifying suffix.
  94 Values without an explicit unit are interpreted as seconds.
  95 .Pp
  96 Supported unit symbols are:
  97 .Bl -tag -width indent -compact
  98 .It Cm s
  99 seconds
 100 .It Cm m
 101 minutes
 102 .It Cm h
 103 hours
 104 .It Cm d
 105 days
 106 .El
 107 .Sh EXIT STATUS
 108 If the timeout was not reached, the exit status of
 109 .Ar command
 110 is returned.
 111 .Pp
 112 If the timeout was reached and
 113 .Fl -preserve-status
 114 is set, the exit status of
 115 .Ar command
 116 is returned.
 117 If
 118 .Fl -preserve-status
 119 is not set, an exit status of 124 is returned.
 120 .Pp
 121 If
 122 .Ar command
 123 exits after receiving a signal, the exit status returned is the signal number
 124 plus 128.
 125 .Pp
 126 If
 127 .Ar command
 128 refers to a non-existing program, the exit status returned is 127.
 129 .Pp
 130 If
 131 .Ar command
 132 is an otherwise invalid program, the exit status returned is 126.
 133 .Pp
 134 If an invalid parameter is passed to
 135 .Fl s
 136 or
 137 .Fl k ,
 138 the exit status returned is 125.
 139 .Sh EXAMPLES
 140 Run
 141 .Xr sleep 1
 142 with a time limit of 4 seconds.
 143 Since the command completes in 2 seconds, the exit status is 0:
 144 .Bd -literal -offset indent
 145 $ timeout 4 sleep 2
 146 $ echo $?
 147 0
 148 .Ed
 149 .Pp
 150 Run
 151 .Xr sleep 1
 152 for 4 seconds and terminate process after 2 seconds.
 153 124 is returned since no
 154 .Fl -preserve-status
 155 is used:
 156 .Bd -literal -offset indent
 157 $ timeout 2 sleep 4
 158 $ echo $?
 159 124
 160 .Ed
 161 .Pp
 162 Same as above but preserving status.
 163 Exit status is 128 + signal number (15 for
 164 .Va SIGTERM )
 165 .Bd -literal -offset indent
 166 $ timeout --preserve-status 2 sleep 4
 167 $ echo $?
 168 143
 169 .Ed
 170 .Pp
 171 Same as above but sending
 172 .Va SIGALRM
 173 (signal number 14) instead of
 174 .Va SIGTERM
 175 .Bd -literal -offset indent
 176 $ timeout --preserve-status -s SIGALRM 2 sleep 4
 177 $ echo $?
 178 142
 179 .Ed
 180 .Pp
 181 Try to
 182 .Xr fetch 1
 183 the single page version of the
 184 .Fx
 185 Handbook.
 186 Send a
 187 .Va SIGTERM
 188 signal after 1 minute and send a
 189 .Va SIGKILL
 190 signal 5 seconds later if the process refuses to stop:
 191 .Bd -literal -offset indent
 192 timeout -k 5s 1m fetch \\
 193 https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/book.html
 194 .Ed
 195 .Sh SEE ALSO
 196 .Xr kill 1 ,
 197 .Xr signal 3
 198 .Sh HISTORY
 199 The
 200 .Nm
 201 command first appeared in
 202 .Fx 10.3 .
 203 .Sh AUTHORS
 204 .An Baptiste Daroussin Aq Mt bapt@FreeBSD.org
 205 and
 206 .An Vsevolod Stakhov Aq Mt vsevolod@FreeBSD.org