chiark - git - mdw - misc/blob - timeout.1

   1 .TH "timeout" 1 "5 June 2011" "Mark Wooding" "Toys"
   2 .SH NAME
   3 timeout \- run a program for at most a given amount of time
   4 .
   5 .SH SYNOPSIS
   6 .B timeout
   7 .RB [ \-s
   8 .IR signal ]
   9 .I seconds
  10 .I command
  11 .RI [ arguments ...]
  12 .
  13 .SH DESCRIPTION
  14 The
  15 .B timeout
  16 command runs a specified program for at most a given number of
  17 .IR seconds .
  18 .PP
  19 It works by running the given command as a separate process group.  It
  20 then waits either for the top-level process (only) to exit, or for the
  21 timeout to expire, whichever happens first.  If the process exits, then
  22 .B timeout
  23 exits too, setting its exit status to match.  Any other processes which
  24 may have been started are left unmolested.
  25 .PP
  26 On the other hand, if the timeout goes off, then
  27 .B timeout
  28 sends its child process group the specified signal, by default
  29 .BR SIGTERM ,
  30 though you can choose a different one with the
  31 .B \-s
  32 option.  It then waits an additional five seconds.  If the child still
  33 hasn't exited, it sends
  34 .B SIGKILL
  35 to the process group and waits a further five seconds.  If the child
  36 still hasn't exited in this time, then
  37 .B timeout
  38 gives up and exits.
  39 .PP
  40 The following command-line options are recognized.
  41 .TP
  42 .B \-h, \-\-help
  43 Prints a reasonably full help message describing the arguments and
  44 options to standard output, and exits successfully.
  45 .TP
  46 .B \-v, \-\-version
  47 Prints the program's version number to standard output, and exits
  48 successfully.
  49 .TP
  50 .B \-u, \-\-usage
  51 Prints a brief usage summary to standard output, and exits successfully.
  52 .TP
  53 .BI "\-s, \-\-signal=" signal
  54 Send
  55 .I signal
  56 to the child process if it takes too long.  The default is to send
  57 .BR SIGTERM .
  58 A signal may be given numerically (e.g., 9 for
  59 .BR SIGKILL )
  60 or by name (e.g.,
  61 .BR KILL ).
  62 .
  63 .SH BUGS
  64 Because
  65 .B timeout
  66 works by running its child process in a separate process group, it
  67 interacts oddly with interactive shells.  If the child process group
  68 attempts to do terminal I/O (particularly reading from a terminal) then
  69 it may be sent signals to suspend it.  This may or may not make matters
  70 worse.
  71 .PP
  72 The
  73 .B timeout
  74 program makes an effort to propagate interesting signals to its child
  75 process group.  Currently, it propagates
  76 .BR SIGTSTP ,
  77 .BR SIGCONT ,
  78 .BR SIGINT ,
  79 .BR SIGHUP ,
  80 and
  81 .BR SIGQUIT .
  82 This list is subject to change: I don't think I'm likely to remove any
  83 of the current signals from it, but I might add some; or I might add an
  84 option to control this list.
  85 .PP
  86 If you suspend
  87 .B timeout
  88 and its child process group, the timer continues running anyway.  (I'm
  89 not quite sure whether this is the right behaviour.)
  90 .PP
  91 Nested timeouts don't work in a useful way if the outer timeout expires
  92 earlier than the inner one.  Since
  93 .B SIGTERM
  94 isn't propagated (currently, at least), the inner
  95 .B timeout
  96 is killed by the outer one, and loses control of its child process
  97 group.  You could possibly work around this by sending
  98 .B SIGQUIT
  99 instead.
 100 .PP
 101 Perhaps it would be useful to allow configuration of the `panic'
 102 timeouts after the initial timeout signal is sent.
 103 .
 104 .SH AUTHOR
 105 Mark Wooding, <mdw@distorted.org.uk>