From 270a486931f9987bfee6b3214e6897577d1bd96c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fernando=20Apestegu=C3=ADa?= <fernape@FreeBSD.org>
Date: Mon, 5 Oct 2020 13:35:34 +0000
Subject: [PATCH] pwait(1): Add EXAMPLES section to man page

* Add small EXAMPLES section to the man page showing the different
  flags and exit codes.

* Complete description for -v flag.

Approved by:	manpages (bcr@)
---
 bin/pwait/pwait.1 | 52 +++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 50 insertions(+), 2 deletions(-)

diff --git a/bin/pwait/pwait.1 b/bin/pwait/pwait.1
index 05f9392e4aa8..0452203eb4a1 100644
--- a/bin/pwait/pwait.1
+++ b/bin/pwait/pwait.1
@@ -32,7 +32,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd January 26, 2020
+.Dd October 5, 2020
 .Dt PWAIT 1
 .Os
 .Sh NAME
@@ -73,7 +73,9 @@ minutes
 hours
 .El
 .It Fl v
-Print the exit status when each process terminates.
+Print the exit status when each process terminates or
+.Ql timeout
+if the timer goes off earlier.
 .El
 .Sh EXIT STATUS
 The
@@ -85,6 +87,52 @@ If the
 flag is specified and a timeout occurs, the exit status will be 124.
 .Pp
 Invalid pids elicit a warning message but are otherwise ignored.
+.Sh EXAMPLES
+Start two
+.Xr sleep 1
+processes in the background.
+The first one will sleep for 30 seconds and the second one for one hour.
+Wait for any of them to finish but no more than 5 seconds.
+Since a timeout occurs the exit status is 124:
+.Bd -literal -offset indent
+$ sleep 30 & sleep 3600 &
+[1] 1646
+[2] 1647
+$ pwait -o -t5 1646 1647
+$?
+124
+.Ed
+.Pp
+Same as above but try to obtain the exit status of the processes.
+In this case
+.Ql timeout
+is shown and the exit status is 124:
+.Bd -literal -offset indent
+$ sleep 30 & sleep 3600 &
+[1] 1652
+[2] 1653
+$ pwait -v -t 5 1652 1653
+timeout
+$?
+124
+.Ed
+.Pp
+Start two
+.Xr sleep 1
+processes in the background sleeping for 30 and 40 seconds respectively.
+Wait 60 seconds for any of them to finish and get their exit codes:
+.Bd -literal -offset indent
+$ sleep 30 & sleep 40 &
+[1] 1674
+[2] 1675
+$ pwait -v -t 60 1674 1675
+1674: exited with status 0.
+1675: exited with status 0.
+[1]-  Done                    sleep 30
+[2]+  Done                    sleep 40
+$ echo $?
+0
+.Ed
 .Sh SEE ALSO
 .Xr kill 1 ,
 .Xr pkill 1 ,