From nobody Sun Feb 1 21:41:02 2026 X-Original-To: dev-commits-src-branches@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 4f438b2NQSz6QjdB for ; Sun, 01 Feb 2026 21:41:03 +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 4f438b0jxdz3Fwr for ; Sun, 01 Feb 2026 21:41:03 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1769982063; 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=WEZzxG9jPKK0ip1ob/MFeDc4Xay9goV0Y5vXAofNJyY=; b=i6dZCpVwq+mkbHzpSuJGCsUIS4l6AN/cnmtvCvhUbWftxbg8kOMjmiqnpsAK+xSpKJI8qk JCBIv5+sjxilZoy9+yY0bLrTlsTbSfNTGEk+zIJacKpEFC1Eben6zTx+2lVi7yobjfX+IR UWS1C/E2Rtzfr4EBy9DmhRcDU95/AryeQkjh47UOv+jAAa6llVV75ol7gwuMlU4MwfH9+/ WDiWVReXZdnue42vIC4F+n3amTEs7w6ywww8KW3Rafi6o2Xiklxnqtn16/jFbbRyguhQ6P MvCUcBxmPoLCLAdi1Ec5lHEWCod1AKUWh9TCCT2YfXzM3B4uMxI+Na1Ql8JC4A== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1769982063; a=rsa-sha256; cv=none; b=nsYyNYj0C8ubGlmfuXvvGQtmlX1GjgqnE+oAgPKsEcsTnRBqPReR/wqpDYrM+lS70VQbUB Vlhm9RN/nWkDFaMOk69ydSINkDXDXcqHmUA72vcjbayCSY+5/4dsDb/LjPN9vxwJBeqxGJ IkNPzM6Ji8dNByp6ADMQZuL4P/XN/Ea992miSbXDnFuk6gw3w8c9s8Zw8rq4ep8MPWZuSh Hchdzfr16ShGWaBHpB60a4WVI0S4nVSNKFHXGLh+w/vXT3I6uVDiHHgJAKwJc9lxPMs4U6 ECpr3PD5SKLsJ3NAqUO6fC9GNgqXdwLkyiOMZ10uUILAAtLmTx5dD0u86zg6ew== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1769982063; 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=WEZzxG9jPKK0ip1ob/MFeDc4Xay9goV0Y5vXAofNJyY=; b=rHKA4HO2I+tPsIrimVZmtUh+3RjiIN2RASaGqwqQkqwGFdVhJA7Z2ZAnPAgCby2C4bMowZ JHsIBNAS4PRyP7QOXXmf9WwYOX2a0yluLU5IMz2K+eKBrLQ5HI8wVw1VNs9sPaLF+KdKY7 RgWzZz7z9WejEsqXDlyzDGsP6j387ff7Mv3HoZo2NWezyCDYAmogqSHDXCVkkROmeRWGee i4L2qTj7Rz1PO9jCxV9RKCQsfiWHa20Z1Nnm0JkOxHqXhq3RC8GbFYBySQxbc/MyYESZmI zVfFMgcmJKWUCWnfwdeJm3V3IAC9yO2tedh9UYeBMFT3fi9pL069+GrfAwl07w== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4f438Z70p9zxNH for ; Sun, 01 Feb 2026 21:41:02 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 3d388 by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Sun, 01 Feb 2026 21:41:02 +0000 To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Konstantin Belousov Subject: git: 780b7f9e0ece - stable/15 - Document pdrfork(2) and pdwait(2) List-Id: Commits to the stable branches of the FreeBSD src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-branches List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-branches@freebsd.org Sender: owner-dev-commits-src-branches@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/stable/15 X-Git-Reftype: branch X-Git-Commit: 780b7f9e0ece3be2b20daf57178a9d01d64db2da Auto-Submitted: auto-generated Date: Sun, 01 Feb 2026 21:41:02 +0000 Message-Id: <697fc86e.3d388.3777f1c6@gitrepo.freebsd.org> The branch stable/15 has been updated by kib: URL: https://cgit.FreeBSD.org/src/commit/?id=780b7f9e0ece3be2b20daf57178a9d01d64db2da commit 780b7f9e0ece3be2b20daf57178a9d01d64db2da Author: Konstantin Belousov AuthorDate: 2026-01-20 03:31:38 +0000 Commit: Konstantin Belousov CommitDate: 2026-02-01 21:38:49 +0000 Document pdrfork(2) and pdwait(2) (cherry picked from commit f7b56887cc0725fbe15730dbe062a092d0955058) --- 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 f2c5ba9593cb..4ad1ad4db7e9 100644 --- a/lib/libsys/Makefile.sys +++ b/lib/libsys/Makefile.sys @@ -493,8 +493,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 ,