1 files changed, 57 insertions, 1 deletions

diff --git a/usr.bin/timeout/timeout.1 b/usr.bin/timeout/timeout.1
index 3955177cf2171..b9613128755e1 100644
--- a/usr.bin/timeout/timeout.1
+++ b/usr.bin/timeout/timeout.1
@@ -26,7 +26,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd March 28, 2018
+.Dd July 7, 2020
 .Dt TIMEOUT 1
 .Os
 .Sh NAME
@@ -136,6 +136,62 @@ If an invalid parameter is passed to
 or
 .Fl k ,
 the exit status returned is 125.
+.Sh EXAMPLES
+Run
+.Xr sleep 1
+with a time limit of 4 seconds.
+Since the command completes in 2 seconds, the exit status is 0:
+.Bd -literal -offset indent
+$ timeout 4 sleep 2
+$ echo $?
+0
+.Ed
+.Pp
+Run
+.Xr sleep 1
+for 4 seconds and terminate process after 2 seconds.
+124 is returned since no
+.Fl -preserve-status
+is used:
+.Bd -literal -offset indent
+$ timeout 2 sleep 4
+$ echo $?
+124
+.Ed
+.Pp
+Same as above but preserving status.
+Exit status is 128 + signal number (15 for
+.Va SIGTERM )
+.Bd -literal -offset indent
+$ timeout --preserve-status 2 sleep 4
+$ echo $?
+143
+.Ed
+.Pp
+Same as above but sending
+.Va SIGALRM
+(signal number 14) instead of
+.Va SIGTERM
+.Bd -literal -offset indent
+$ timeout --preserve-status -s SIGALRM 2 sleep 4
+$ echo $?
+142
+.Ed
+.Pp
+Try to
+.Xr fetch 1
+the single page version of the
+.Fx
+Handbook.
+Send a
+.Va SIGTERM
+signal after 1 minute and send a
+.Va SIGKILL
+signal 5 seconds later if the process refuses to stop:
+.Bd -literal -offset indent
+timeout -k 5s 1m fetch \\
+https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/book.html
+.Ed
 .Sh SEE ALSO
 .Xr kill 1 ,
 .Xr signal 3