From nobody Sun Jan 25 15:57:00 2026 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4dzbrs36yrz6PjPd for ; Sun, 25 Jan 2026 15:57:01 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R13" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4dzbrr6JVQz481w for ; Sun, 25 Jan 2026 15:57:00 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1769356620; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=lj3djUqdNkhllRkh9JAz4m2GjohDEP/GM3D+WFenR4M=; b=CGy8Ff/JrlzlpyOXETBIu1YUpIILn7+9c4VidWByIXPQWfnsaT9skuyw7Mnp3a1GfsZ8e+ pyrB6n6QYW1+DonXN4uag5Bvzx5YBQGagW4C3XDMiCEwzJV5PYoyOE/USY84aIQIWBsUKP R1SfXEso5xKR/7bLLhiYGrBw0dtRMl0uge2hVs5KZ+16eWaQjFSEOz/cMoRoMNbnpHPMPR 4gXq1YonUJ2AcHnZBqUjBEjHUXz3OEWY1U5MAFcySxevdpCD2b43DgTACwv4hkHsDfJv7B Fb1mA6CUXsK4k/TDY3IfhF7m0Lg/QTJVKW7ENkdQBGwiNXT5BLD6DISddZoeuw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1769356620; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=lj3djUqdNkhllRkh9JAz4m2GjohDEP/GM3D+WFenR4M=; b=PdwEHLI9cbwy+apc923EinSd4Xo7elIrH7gZ3XZ5tX2vjHCJ6VnHEPL0mvZO2cbBMIBS9+ BmhEyNP3W6TPw7EtuhRaUbQtipwLe55HkeHON8fz4bn9694efTDPirJb5+FcrieHhBbo+F Mrs2AhFCNXTM/m4K4Aw121lq4Ut+SF7Ccvj/kGA0YBNj66HDPS8OafS9SYJ0HNeW+pbEcn yhYI8LUPMxs+JozxQ+acWwjBYUoyefsKvJJiCuWWF+D4sM6O0JB1dHXDFIv7cjuTkUvRiN eFDQLy9IEAmaUNKnNWPmCRA61WbbEypgbMpIsdnyqBaB3DKs1CeFRkryFLZ38A== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1769356620; a=rsa-sha256; cv=none; b=DbCzqCe4fvYxmyDmirDlf8+vuwjZOPe366qmVzCO3DiZSaOoqetyf2am7lSxbc0IqzIyJf rJP1y1RyqsavtoLf2VOGgSlhLc42ps9RChfLhalrUwjIHVXzdQMvqM3410tONoe3TN6q3W MF/Yw8B/5dyAQVRqd9auuY1RwAZU/ZkBxw7xCCrL4CrHDhuWeZHzC/zDtGI6KYCpgbk00e +l5c/bCgDLez+ZfbYEmmNK/rWMVzAd95TNj3pqstnwy8/xJO/pp+g84cQ/t4JlmteCeNkQ Mmw7O/emXXrr8mnn1BGrx+F32FZyC7UoTF0czonriBriIwTYbJcJGgL0XKHxhw== ARC-Authentication-Results: i=1; mx1.freebsd.org; none Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4dzbrr5t17zhts for ; Sun, 25 Jan 2026 15:57:00 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 33bed by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Sun, 25 Jan 2026 15:57:00 +0000 To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Konstantin Belousov Subject: git: f7b56887cc07 - main - Document pdrfork(2) and pdwait(2) List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: kib X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: f7b56887cc0725fbe15730dbe062a092d0955058 Auto-Submitted: auto-generated Date: Sun, 25 Jan 2026 15:57:00 +0000 Message-Id: <69763d4c.33bed.52415894@gitrepo.freebsd.org> The branch main has been updated by kib: URL: https://cgit.FreeBSD.org/src/commit/?id=f7b56887cc0725fbe15730dbe062a092d0955058 commit f7b56887cc0725fbe15730dbe062a092d0955058 Author: Konstantin Belousov AuthorDate: 2026-01-20 03:31:38 +0000 Commit: Konstantin Belousov 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 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 . 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 ,