Document pdrfork(2) and pdwait(2)

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

lib/libsys/Makefile.sys

@@ -496,8 +496,10 @@ MLINKS+=ntp_adjtime.2 ntp_gettime.2
 MLINKS+=open.2 openat.2
 MLINKS+=pathconf.2 fpathconf.2
 MLINKS+=pathconf.2 lpathconf.2
-MLINKS+=pdfork.2 pdgetpid.2\
-	pdfork.2 pdkill.2
+MLINKS+=pdfork.2 pdgetpid.2 \
+	pdfork.2 pdkill.2 \
+	pdfork.2 pdrfork.2 \
+	pdfork.2 pdwait.2
 MLINKS+=pipe.2 pipe2.2
 MLINKS+=poll.2 ppoll.2
 MLINKS+=rctl_add_rule.2 rctl_get_limits.2 \

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 January 20, 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,33 @@ 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 the
+.Va RFPROC
+or
+.Va RFSPAWN
+flag is specified.
+.Pp
 .Fn pdgetpid
 queries the process ID (PID) in the process descriptor
 .Fa fd .
@@ -91,6 +131,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 +176,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
@@ -172,6 +231,12 @@ and
 .Fn pdkill
 system calls first appeared in
 .Fx 9.0 .
+The
+.Fn pdrfork
+and
+.Fn pdwait
+system calls first appeared in
+.Fx 16.0 .
 .Pp
 Support for process descriptors mode was developed as part of the
 .Tn TrustedBSD
@@ -184,3 +249,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 .

lib/libsys/rfork.2

@@ -194,6 +194,7 @@ There is insufficient swap space for the new process.
 .Xr fork 2 ,
 .Xr intro 2 ,
 .Xr minherit 2 ,
+.Xr pdrfork 2 ,
 .Xr vfork 2 ,
 .Xr pthread_create 3 ,
 .Xr rfork_thread 3

lib/libsys/wait.2

@@ -656,6 +656,7 @@ do not specify a valid set of processes.
 .El
 .Sh SEE ALSO
 .Xr _exit 2 ,
+.Xr pdwait 2 ,
 .Xr procctl 2 ,
 .Xr ptrace 2 ,
 .Xr sigaction 2 ,