svn commit: r362994 - head/usr.bin/timeout

[Fernando Apesteguía]

Author: fernape (ports committer)
Date: Tue Jul  7 17:02:23 2020
New Revision: 362994
URL: https://svnweb.freebsd.org/changeset/base/362994

Log:
  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

Modified:
  head/usr.bin/timeout/timeout.1

Modified: head/usr.bin/timeout/timeout.1
==============================================================================
--- head/usr.bin/timeout/timeout.1	Tue Jul  7 16:35:52 2020	(r362993)
+++ head/usr.bin/timeout/timeout.1	Tue Jul  7 17:02:23 2020	(r362994)
@@ -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