pdwait(2), wait(2): document interaction between pdopenpid() and waitpid()

Reviewed by:	markj
Sponsored by:	The FreeBSD Foundation
MFC after:	1 week
Differential revision:	https://reviews.freebsd.org/D58264

2 files changed, 57 insertions, 13 deletions

diff --git a/lib/libsys/pdfork.2 b/lib/libsys/pdfork.2
index 1b99157203c1..6f577427a716 100644
--- a/lib/libsys/pdfork.2
+++ b/lib/libsys/pdfork.2
@@ -103,6 +103,9 @@ specifying the
 flag, closing that descriptor kills the process.
 .It Dv PD_CLOEXEC
 Set close-on-exec on process descriptor.
+.It Dv PD_NOWAITPID
+The parent cannot obtain the child's status with
+.Xr waitpid 2 .
 .El
 .Pp
 The
@@ -149,9 +152,6 @@ to succeed.
 Zombie processes cannot be opened.
 .Pp
 There might be more that one file descriptor referencing the process.
-But only one caller of
-.Fn pdwait
-gets the exit status.
 After the zombie is reaped, calls to
 .Fn pdwait
 specifying any file descriptors for the same process fail with the
@@ -176,7 +176,7 @@ the status information on the process referenced by the
 .Fa fd
 process descriptor.
 See the description of the
-.Xr wait6
+.Xr wait6 2
 system call for the behavior specification.
 .Pp
 The
@@ -197,6 +197,59 @@ The
 argument is reserved and must be zero.
 Certain file descriptor types cannot be copied this way, namely
 kqueues.
+.Sh INTERACTION OF PROCESS DESCRIPTORS AND Xr WAITPID 2
+.Pp
+The
+.Fn pdwait
+system call may be called on a process descriptor
+an unlimited number of times.
+In particular, it does not reap the target process,
+even if that process has exited.
+Each time, it returns the same status.
+.Bl -dash
+.It
+If the process was forked with
+.Fn pdfork ,
+and the
+.Dv PD_NOWAITPID
+flag was specified, then the process is automatically reaped after the
+last process descriptor referencing that process is closed.
+No
+.Xr waitpid 2
+call
+.Pq or a call from the same family of the wait functions which operate on PIDs
+are needed to reap the zombie process.
+.It
+If the process was created by
+.Fn pdfork ,
+and the
+.Dv PD_NOWAITPID
+flag was not specified, then after exiting,
+the process will not be reaped until the parent or reaper has called
+.Xr waitpid 2
+and all process descriptors referencing the process are closed.
+.It
+If the process was created by the
+.Xr fork 2
+system call
+.Pq which does not allocate a process descriptor for the child ,
+and later the process was opened by
+.Fn pdopenpid ,
+then a
+.Xr waitpid 2
+call from the parent is needed to reap the exited child.
+.El
+.Pp
+In any case, the PID of the process is not reused until its zombie
+is reaped, and all its process descriptors are closed.
+.Pp
+A debugger attached by
+.Xr ptrace 2
+can execute the
+.Fn waitpid
+calls against the alive target regardless of the way
+the target process was forked.
+.Sh INTERACTION OF PROCESS DESCRIPTORS WITH OTHER SYSTEM CALLS
 .Pp
 The following system calls also have effects specific to process descriptors:
 .Pp
diff --git a/lib/libsys/wait.2 b/lib/libsys/wait.2
index ca289c69f188..f018ab3d4d37 100644
--- a/lib/libsys/wait.2
+++ b/lib/libsys/wait.2
@@ -607,15 +607,6 @@ fields of
 .Fa infop
 must be checked against zero to determine if a process reported status.
 .Pp
-The
-.Fn wait
-family of functions will only return a child process created with
-.Xr pdfork 2
-if the calling process is not in
-.Xr capsicum 4
-capability mode, and
-.Nm
-has been explicitly given the child's process ID.
 .Sh ERRORS
 The
 .Fn wait