Annotation of src/usr.bin/timeout/timeout.1, Revision 1.2
1.2 ! jmc 1: .\" $OpenBSD$
1.1 job 2: .\" $NetBSD: timeout.1,v 1.4 2016/10/13 06:22:26 dholland Exp $
3: .\"
4: .\" Copyright (c) 2014 Baptiste Daroussin <bapt@FreeBSD.org>
5: .\" All rights reserved.
6: .\"
7: .\" Redistribution and use in source and binary forms, with or without
8: .\" modification, are permitted provided that the following conditions
9: .\" are met:
10: .\" 1. Redistributions of source code must retain the above copyright
11: .\" notice, this list of conditions and the following disclaimer.
12: .\" 2. Redistributions in binary form must reproduce the above copyright
13: .\" notice, this list of conditions and the following disclaimer in the
14: .\" documentation and/or other materials provided with the distribution.
15: .\"
16: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26: .\" SUCH DAMAGE.
27: .\"
28: .\" $FreeBSD: head/usr.bin/timeout/timeout.1 268861 2014-07-18 22:56:59Z bapt $
29: .\"
1.2 ! jmc 30: .Dd $Mdocdate$
1.1 job 31: .Dt TIMEOUT 1
32: .Os
33: .Sh NAME
34: .Nm timeout
35: .Nd run a command with a time limit
36: .Sh SYNOPSIS
37: .Nm
1.2 ! jmc 38: .Op Fl k Ar time
! 39: .Op Fl s Ar sig
! 40: .Op Fl -foreground
! 41: .Op Fl -preserve-status
! 42: .Ar duration
! 43: .Ar command
! 44: .Op Ar args
1.1 job 45: .Sh DESCRIPTION
1.2 ! jmc 46: The
1.1 job 47: .Nm
1.2 ! jmc 48: utility executes
! 49: .Ar command ,
! 50: with any
! 51: .Ar args ,
! 52: and kills it if it is still running after the
! 53: specified
! 54: .Ar duration .
1.1 job 55: If
1.2 ! jmc 56: .Ar duration
! 57: is 0, the timeout is disabled.
! 58: .Pp
! 59: The options are as follows:
! 60: .Bl -tag -width Ds
! 61: .It Fl k Ar time , Fl -kill-after Ns = Ns Ar time
! 62: Send a second kill signal if the command is still running
1.1 job 63: .Ar time
64: after the first signal was sent.
1.2 ! jmc 65: .It Fl s Ar sig , Fl -signal Ns = Ns Ar sig
! 66: Specify the signal to send on timeout, instead of the default
! 67: .Dv SIGTERM .
! 68: .It Fl -foreground
! 69: Do not propagate the timeout signal to children processes.
! 70: .It Fl -preserve-status
! 71: Always exit with the same status as
! 72: .Ar command ,
! 73: even if the timeout was reached.
1.1 job 74: .El
75: .Sh DURATION FORMAT
76: .Ar duration
77: and
78: .Ar time
1.2 ! jmc 79: may contain a decimal fraction.
! 80: The value defaults to seconds unless a unit suffix is given.
! 81: .Pp
! 82: The supported unit suffixes are:
1.1 job 83: .Pp
1.2 ! jmc 84: .Bl -tag -width Ds -offset indent -compact
1.1 job 85: .It s
86: seconds
87: .It m
88: minutes
89: .It h
90: hours
91: .It d
92: days
93: .El
94: .Sh EXIT STATUS
95: If the timeout was not reached, the exit status of
96: .Ar command
97: is returned.
98: .Pp
99: If the timeout was reached and
1.2 ! jmc 100: .Fl -preserve-status
! 101: was set, the exit status of
1.1 job 102: .Ar command
103: is returned.
104: If
1.2 ! jmc 105: .Fl -preserve-status
! 106: was not set, an exit status of 124 is returned.
1.1 job 107: .Pp
108: If
109: .Ar command
1.2 ! jmc 110: exited after receiving a signal, the exit status returned is the signal number
! 111: plus 128.
1.1 job 112: .Sh SEE ALSO
113: .Xr kill 1 ,
114: .Xr signal 3
115: .Sh HISTORY
116: A
117: .Nm
118: utility appeared in a development branch of
119: .Fx 11
120: and was imported into
121: .Nx 7 .
122: The
123: .Fx
124: work is compatible with GNU
125: .Nm
126: by
127: .An Padraig Brady ,
128: from GNU Coreutils 8.21.
129: The
130: .Nm
131: utility first appeared in GNU Coreutils 7.0.