1 files changed, 101 insertions, 8 deletions
diff --git a/lib/libsys/pdfork.2 b/lib/libsys/pdfork.2
index c5319177f90f..3997570d2125 100644
--- a/lib/libsys/pdfork.2
+++ b/lib/libsys/pdfork.2
@@ -30,24 +30,36 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd October 14, 2018
+.Dd April 19, 2026
 .Dt PDFORK 2
 .Os
 .Sh NAME
 .Nm pdfork ,
+.Nm pdrfork ,
 .Nm pdgetpid ,
-.Nm pdkill
+.Nm pdkill ,
+.Nm pdwait
 .Nd System calls to manage process descriptors
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In sys/procdesc.h
 .Ft pid_t
-.Fn pdfork "int *fdp" "int flags"
+.Fn pdfork "int *fdp" "int pdflags"
+.Ft pid_t
+.Fn pdrfork "int *fdp" "int pdflags" "int rfflags"
 .Ft int
 .Fn pdgetpid "int fd" "pid_t *pidp"
 .Ft int
 .Fn pdkill "int fd" "int signum"
+.Ft int
+.Fo pdwait
+.Fa "int fd"
+.Fa "int *status"
+.Fa "int options"
+.Fa "struct __wrusage *wrusage"
+.Fa "struct __siginfo *info"
+.Fc
 .Sh DESCRIPTION
 Process descriptors are special file descriptors that represent processes,
 and are created using
@@ -63,8 +75,9 @@ will not cause
 .Dv SIGCHLD
 on termination.
 .Fn pdfork
-can accept the flags:
-.Bl -tag -width ".Dv PD_DAEMON"
+can accept the
+.Fa pdflags:
+.Bl -tag -width PD_CLOEXEC
 .It Dv PD_DAEMON
 Instead of the default terminate-on-close behaviour, allow the process to
 live until it is explicitly killed with
@@ -80,6 +93,35 @@ capability mode (see
 Set close-on-exec on process descriptor.
 .El
 .Pp
+The
+.Fn pdrfork
+system call is a variant of
+.Fn pdfork
+that also takes the
+.Fa rfflags
+argument to control sharing of process resources between the caller
+and the new process.
+Like
+.Fn pdfork ,
+the function writes the process descriptor referencing the created
+process into the location pointed to by the
+.Fa fdp
+argument.
+See
+.Xr rfork 2
+for a description of the possible
+.Fa rfflag
+flags.
+The
+.Fn pdrfork
+system call requires that both the
+.Va RFPROC
+and
+.Va RFPROCDESC
+flags, or
+.Va RFSPAWN
+flag are specified.
+.Pp
 .Fn pdgetpid
 queries the process ID (PID) in the process descriptor
 .Fa fd .
@@ -91,6 +133,16 @@ except that it accepts a process descriptor,
 .Fa fd ,
 rather than a PID.
 .Pp
+The
+.Fn pdwait
+system call allows the calling thread to wait and retrieve
+the status information on the process referenced by the
+.Fa fd
+process descriptor.
+See the description of the
+.Xr wait6
+system call for the behavior specification.
+.Pp
 The following system calls also have effects specific to process descriptors:
 .Pp
 .Xr fstat 2
@@ -126,15 +178,24 @@ is set; if the process is still alive and this is
 the last reference to the process descriptor, the process will be terminated
 with the signal
 .Dv SIGKILL .
+The PID of the referenced process is not reused until the process
+descriptor is closed,
+whether or not the zombie process is reaped by
+.Fn pdwait ,
+.Xr wait6 ,
+or similar system calls.
 .Sh RETURN VALUES
 .Fn pdfork
-returns a PID, 0 or -1, as
+and
+.Fn pdrfork
+return a PID, 0 or -1, as
 .Xr fork 2
 does.
 .Pp
-.Fn pdgetpid
+.Fn pdgetpid ,
+.Fn pdkill ,
 and
-.Fn pdkill
+.Fn pdwait
 return 0 on success and -1 on failure.
 .Sh ERRORS
 These functions may return the same error numbers as their PID-based equivalents
@@ -144,6 +205,24 @@ may return the same error numbers as
 .Xr fork 2 ) ,
 with the following additions:
 .Bl -tag -width Er
+.It Bq Er EFAULT
+The copyout of the resulting file descriptor value to the memory pointed
+to by
+.Fa fdp
+failed.
+.Pp
+Note that the child process was already created when this condition
+is detected,
+and the child continues execution, same as the parent.
+If this error must be handled, it is advisable to memoize the
+.Fn getpid
+result before the call to
+.Fn pdfork
+or
+.Fn pdrfork ,
+and compare it to the value returned by
+.Fn getpid
+after, to see if code is executing in parent or child.
 .It Bq Er EINVAL
 The signal number given to
 .Fn pdkill
@@ -172,6 +251,12 @@ and
 .Fn pdkill
 system calls first appeared in
 .Fx 9.0 .
+The
+.Fn pdrfork
+and
+.Fn pdwait
+system calls first appeared in
+.Fx 15.1 .
 .Pp
 Support for process descriptors mode was developed as part of the
 .Tn TrustedBSD
@@ -184,3 +269,11 @@ and
 .An Jonathan Anderson Aq Mt jonathan@FreeBSD.org
 at the University of Cambridge Computer Laboratory with support from a grant
 from Google, Inc.
+The
+.Fn pdrfork
+and
+.Fn pdwait
+functions were developed by
+.An Konstantin Belousov Aq Mt kib@FreeBSD.org
+with input from
+.An Alan Somers Aq Mt asomers@FreeBSD.org .