The branch main has been updated by kib: URL: https://cgit.FreeBSD.org/src/commit/?id=f7b56887cc0725fbe15730dbe062a092d0955058
commit f7b56887cc0725fbe15730dbe062a092d0955058 Author: Konstantin Belousov <[email protected]> AuthorDate: 2026-01-20 03:31:38 +0000 Commit: Konstantin Belousov <[email protected]> CommitDate: 2026-01-25 15:54:15 +0000 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 | 6 ++-- lib/libsys/pdfork.2 | 89 ++++++++++++++++++++++++++++++++++++++++++++----- lib/libsys/rfork.2 | 1 + lib/libsys/wait.2 | 1 + 4 files changed, 87 insertions(+), 10 deletions(-) diff --git a/lib/libsys/Makefile.sys b/lib/libsys/Makefile.sys index 4e70faec1167..eac28fbd2fe9 100644 --- a/lib/libsys/Makefile.sys +++ b/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 \ diff --git a/lib/libsys/pdfork.2 b/lib/libsys/pdfork.2 index c5319177f90f..ad7eecb00dae 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 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 [email protected] 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 [email protected] +with input from +.An Alan Somers Aq Mt [email protected] . diff --git a/lib/libsys/rfork.2 b/lib/libsys/rfork.2 index 649b2acae6ce..bf6db7531126 100644 --- a/lib/libsys/rfork.2 +++ b/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 diff --git a/lib/libsys/wait.2 b/lib/libsys/wait.2 index eeddf77aeac7..ca289c69f188 100644 --- a/lib/libsys/wait.2 +++ b/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 ,
