>From 33870a01ef65145ccc0cc7f0bf0b76cafec9d95d Mon Sep 17 00:00:00 2001
From: Bernhard Voelker <mail@bernhard-voelker.de>
Date: Mon, 15 Jun 2020 22:47:15 +0200
Subject: [PATCH] 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
---
doc/coreutils.texi | 22 ++++++++++++++++++++++
1 file changed, 22 insertions(+)
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 3432fb294..4f6c6129b 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -18153,6 +18153,28 @@ 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 shorter-living 'sleep' command.
+# As that terminates with exit status 0 after 1s, 'timeout' returns the same.
+timeout 20 sleep 1
+
+# Send a 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 ignoring the signal 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 another KILL signal 3 seconds after the initial INT.
+# Here, '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
--
2.27.0