usr.bin/timeout/timeout.1

   1 .\" Copyright (c) 2014 Baptiste Daroussin <bapt@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd Oct 28, 2014
  28 .Dt TIMEOUT 1
  29 .Os
  30 .Sh NAME
  31 .Nm timeout
  32 .Nd run a command with a time limit
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Op Fl -signal Ar sig | Fl s Ar sig
  36 .Op Fl -preserve-status
  37 .Op Fl -kill-after Ar time | Fl k Ar time
  38 .Op Fl -foreground
  39 .Ao Ar duration Ac
  40 .Ao Ar command Ac
  41 .Ao Ar args ... Ac
  42 .Sh DESCRIPTION
  43 .Nm
  44 starts the
  45 .Ar command
  46 with its
  47 .Ar args.
  48 If
  49 .Ar command
  50 is still running after
  51 .Ar duration ,
  52 it is killed.
  53 By default,
  54 .Ar SIGTERM.
  55 is sent.
  56 .Bl -tag -width "-k time, --kill-after time"
  57 .It Fl -preserve-status
  58 Always exits with the same status as
  59 .Ar command
  60 even if it times out.
  61 .It Fl -foreground
  62 Do not propagate timeout to the
  63 .Ar command
  64 children.
  65 .It Fl s Ar sig , Fl -signal Ar sig
  66 Specify the signal to send on timeout.
  67 By default,
  68 .Ar SIGTERM .
  69 is sent.
  70 .It Fl k Ar time , Fl -kill-after Ar time
  71 Send a second kill signal if
  72 .Ar command
  73 is still running after
  74 .Ar time
  75 after the first signal was sent.
  76 .El
  77 .Sh DURATION FORMAT
  78 .Ar duration
  79 and
  80 .Ar time
  81 can be integer or decimal numbers.
  82 Values without unit symbols are interpreted as seconds.
  83 .Pp
  84 Supported unit symbols are:
  85 .Bl -tag -width indent -compact
  86 .It s
  87 seconds
  88 .It m
  89 minutes
  90 .It h
  91 hours
  92 .It d
  93 days
  94 .El
  95 .Sh EXIT STATUS
  96 If the timeout was not reached, the exit status of
  97 .Ar command
  98 is returned.
  99 .Pp
 100 If the timeout was reached and
 101 .Fl -preserve-status
 102 is set, the exit status of
 103 .Ar command
 104 is returned.
 105 If
 106 .Fl -preserve-status
 107 is not set, an exit status of 124 is returned.
 108 .Pp
 109 If
 110 .Ar command
 111 exits after receiving a signal, the exit status returned is the signal number
 112 plus 128.
 113 .Pp
 114 If
 115 .Ar command
 116 is an invalid command, the exit status returned is 126.
 117 .Pp
 118 If
 119 .Ar command
 120 is a non existing command, the exit status returned is 127.
 121 .Pp
 122 If an invalid parameter is passed to
 123 .Fl s
 124 or
 125 .Fl k ,
 126 the exit status return is 125.
 127 .Sh SEE ALSO
 128 .Xr kill 1 ,
 129 .Xr signal 3