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 4bbb960b7328311ccdf314a63990d5012f500a83..c072b15758fff580b40ffd719f79aad086b3ac43 100644 (file)
--- 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