From: Bernhard Voelker <mail@bernhard-voelker.de>
Date: Fri, 3 Jul 2020 22:19:31 +0000 (+0200)
Subject: doc: add timeout examples
X-Git-Tag: v9.0~224
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b1c6ef230c129f9ec93b8c6148b94e3d52f31688;p=thirdparty%2Fcoreutils.git

doc: add timeout examples

* doc/coreutils.texi (timeout invocation): Add examples.

Suggested by Jonny Grant <jg@jguk.org> in
https://lists.gnu.org/r/bug-coreutils/2020-06/msg00018.html
---

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 4bbb960b73..c072b15758 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -18158,6 +18158,29 @@ or to @command{timeout} itself, i.e., these cases cannot be distinguished.
 In the latter case, the @var{command} process may still be alive after
 @command{timeout} has forcefully been terminated.
 
+Examples:
+
+@example
+# Send the default TERM signal after 20s to a short-living 'sleep 1'.
+# As that terminates long before the given duration, 'timeout' returns
+# with the same exit status as the command, 0 in this case.
+timeout 20 sleep 1
+
+# Send the INT signal after 5s to the 'sleep' command.  Returns after
+# 5 seconds with exit status 124 to indicate the sending of the signal.
+timeout -s INT 5 sleep 20
+
+# Likewise, but the command ignoring the INT signal due to being started
+# via 'env --ignore-signal'.  Thus, 'sleep' terminates regularly after
+# the full 20 seconds, still 'timeout' returns with exit status 124.
+timeout -s INT 5s env --ignore-signal=INT sleep 20
+
+# Likewise, but sending the KILL signal 3 seconds after the initial
+# INT signal.  Hence, 'sleep' is forcefully terminated after about
+# 8 seconds (5+3), and 'timeout' returns with an exit status of 137.
+timeout -s INT -k 3s 5s env --ignore-signal=INT sleep 20
+@end example
+
 @node Process control
 @chapter Process control