timeout(1): Add EXAMPLES section

Small EXAMPLES section showing the use of -s, -k and the different exit values

Approved by:	manpages (gbe)
Differential Revision:	https://reviews.freebsd.org/D25575

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