git: 8c17b933a869 - stable/15 - pdfork.2: document pdopenpid(2)

The branch stable/15 has been updated by kib:

URL: https://cgit.FreeBSD.org/src/commit/?id=8c17b933a8699037e4e080fe1b36ebbf9a9e32b2

commit 8c17b933a8699037e4e080fe1b36ebbf9a9e32b2
Author:     Konstantin Belousov <[email protected]>
AuthorDate: 2026-05-21 17:33:43 +0000
Commit:     Konstantin Belousov <[email protected]>
CommitDate: 2026-08-16 02:41:24 +0000

    pdfork.2: document pdopenpid(2)
    
    (cherry picked from commit 3e8b68c26e2b108dac96517ef8fd26fe7dce5bcd)
---
 lib/libsys/Makefile.sys |  1 +
 lib/libsys/pdfork.2     | 68 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 69 insertions(+)

diff --git a/lib/libsys/Makefile.sys b/lib/libsys/Makefile.sys
index b17336babfcb..92d6b53d8fde 100644
--- a/lib/libsys/Makefile.sys
+++ b/lib/libsys/Makefile.sys
@@ -496,6 +496,7 @@ MLINKS+=open.2 openat.2
 MLINKS+=pathconf.2 fpathconf.2
 MLINKS+=pathconf.2 lpathconf.2
 MLINKS+=pdfork.2 pdgetpid.2 \
+	pdfork.2 pdopenpid.2 \
 	pdfork.2 pdkill.2 \
 	pdfork.2 pdrfork.2 \
 	pdfork.2 pdwait.2
diff --git a/lib/libsys/pdfork.2 b/lib/libsys/pdfork.2
index 6ebab24ff180..9099edebaa2a 100644
--- a/lib/libsys/pdfork.2
+++ b/lib/libsys/pdfork.2
@@ -36,6 +36,7 @@
 .Sh NAME
 .Nm pdfork ,
 .Nm pdrfork ,
+.Nm pdopenpid ,
 .Nm pdgetpid ,
 .Nm pdkill ,
 .Nm pdwait
@@ -49,6 +50,8 @@
 .Ft pid_t
 .Fn pdrfork "int *fdp" "int pdflags" "int rfflags"
 .Ft int
+.Fn pdopenpid "pid_t pid" "int pdflags"
+.Ft int
 .Fn pdgetpid "int fd" "pid_t *pidp"
 .Ft int
 .Fn pdkill "int fd" "int signum"
@@ -128,6 +131,28 @@ flags, or
 .Va RFSPAWN
 flag are specified.
 .Pp
+.Fn pdopenpid
+opens the process descriptor for the process specified by the argument
+.Fa pid .
+It takes the same flags in the
+.Fa pdflags
+argument as
+.Fn pdfork .
+The caller must have permission to debug the target process in order for
+.Fn pdopenpid
+to succeed.
+Zombie processes cannot be opened.
+.Pp
+There might be more that one file descriptor referencing the process.
+But only one caller of
+.Fn pdwait
+gets the exit status.
+After the zombie is reaped, calls to
+.Fn pdwait
+specifying any file descriptors for the same process fail with the
+.Er ESRCH
+error.
+.Pp
 .Fn pdgetpid
 queries the process ID (PID) in the process descriptor
 .Fa fd .
@@ -198,6 +223,7 @@ return a PID, 0 or -1, as
 .Xr fork 2
 does.
 .Pp
+.Fn pdopenpid ,
 .Fn pdgetpid ,
 .Fn pdkill ,
 and
@@ -244,6 +270,40 @@ The
 function is called with reserved bits set in
 .Fa options .
 .El
+.Pp
+The
+.Fn pdopenpid
+might return the same errors as
+.Xr open 2 ,
+related to the file descriptor allocation problems, as well as the
+following specific errors:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The
+.Fa flags
+argument has reserved bits set.
+.It Bq Er ECAPMODE
+.Fn pdopenpid
+is called by the process in capability mode.
+.It Bq Er EBUSY
+The process specified by the
+.Fa pid
+argument already terminated.
+.It Bq Er ESRCH
+The process specified by the
+.Fa pid
+argument does not exist, or the caller does not have enough privileges
+to open the process.
+.It Bq Er EMFILE
+The calling process already reached its limit for open file descriptors.
+.Pp
+Current implementation installs the opened process descriptor into the
+calling process's file descriptors table.
+If the descriptor cannot be installed, the process descriptor is closed,
+which executes all actions performed by
+.Xr close 2
+on it.
+.El
 .Sh SEE ALSO
 .Xr close 2 ,
 .Xr fork 2 ,
@@ -268,6 +328,10 @@ and
 .Fn pdwait
 system calls first appeared in
 .Fx 15.1 .
+The
+.Fn pdopenpid
+system call first appeared in
+.Fx 16.0 .
 .Pp
 Support for process descriptors mode was developed as part of the
 .Tn TrustedBSD
@@ -288,3 +352,7 @@ functions were developed by
 .An Konstantin Belousov Aq Mt [email protected]
 with input from
 .An Alan Somers Aq Mt [email protected] .
+The
+.Fn pdopenpid
+function was developed by
+.An Konstantin Belousov Aq Mt [email protected] .