git: 55fdf7561cc4 - stable/15 - pdfork.2: document pddupfd()

The branch stable/15 has been updated by kib:

URL: https://cgit.FreeBSD.org/src/commit/?id=55fdf7561cc4d7048a46264b115987c4ac03baab

commit 55fdf7561cc4d7048a46264b115987c4ac03baab
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2026-05-22 10:09:01 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2026-08-16 02:41:27 +0000

    pdfork.2: document pddupfd()
    
    (cherry picked from commit c20558e5c9dadfdddc879ee50a65d14beb4992b9)
---
 lib/libsys/Makefile.sys |  3 ++-
 lib/libsys/pdfork.2     | 57 +++++++++++++++++++++++++++++++++++++++++++++----
 2 files changed, 55 insertions(+), 5 deletions(-)

diff --git a/lib/libsys/Makefile.sys b/lib/libsys/Makefile.sys
index 92d6b53d8fde..afe24345bc5d 100644
--- a/lib/libsys/Makefile.sys
+++ b/lib/libsys/Makefile.sys
@@ -499,7 +499,8 @@ MLINKS+=pdfork.2 pdgetpid.2 \
 	pdfork.2 pdopenpid.2 \
 	pdfork.2 pdkill.2 \
 	pdfork.2 pdrfork.2 \
-	pdfork.2 pdwait.2
+	pdfork.2 pdwait.2 \
+	pdfork.2 pddupfd.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 18dff970be1f..a6bf8534003d 100644
--- a/lib/libsys/pdfork.2
+++ b/lib/libsys/pdfork.2
@@ -39,7 +39,8 @@
 .Nm pdopenpid ,
 .Nm pdgetpid ,
 .Nm pdkill ,
-.Nm pdwait
+.Nm pdwait ,
+.Nm pddupfd
 .Nd System calls to manage process descriptors
 .Sh LIBRARY
 .Lb libc
@@ -63,6 +64,8 @@
 .Fa "struct __wrusage *wrusage"
 .Fa "struct __siginfo *info"
 .Fc
+.Ft int
+.Fn pddupfd "int fd" "int remotefd" "int flags"
 .Sh DESCRIPTION
 Process descriptors are special file descriptors that represent processes,
 and are created using
@@ -176,6 +179,23 @@ See the description of the
 .Xr wait6
 system call for the behavior specification.
 .Pp
+The
+.Fn pddupfd
+allows the caller to duplicate a file descriptor across the process
+boundaries.
+The function returns the new file descriptor that points to the same file
+as the file descriptor
+.Fa remotefd
+in the process specified by the
+.Fa fd
+process descriptor.
+The returned file descriptor has the
+.Va O_CLOEXEC
+flag set.
+The
+.Fa flags
+argument is reserved and must be zero.
+.Pp
 The following system calls also have effects specific to process descriptors:
 .Pp
 .Xr fstat 2
@@ -228,8 +248,9 @@ does.
 .Fn pdopenpid ,
 .Fn pdgetpid ,
 .Fn pdkill ,
+.Fn pdwait ,
 and
-.Fn pdwait
+.Fn pddupfd
 return 0 on success and -1 on failure.
 .Sh ERRORS
 These functions may return the same error numbers as their PID-based equivalents
@@ -306,6 +327,30 @@ which executes all actions performed by
 .Xr close 2
 on it.
 .El
+.Pp
+The
+.Fn pddupfd
+returns the following errors:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The
+.Fa flags
+argument is not zero.
+.It Bq Er ESRCH
+The process specified by the file descriptor
+.Fa fd
+exited.
+.It Bq Er EBADF
+The file descriptor
+.Fa fd
+is not a process file descriptor.
+.It Bq Er EBADF
+The file descriptor
+.Fa remotefd
+is not a valid file descriptor in the specified process.
+.It Bq Er ENOENT
+The specified process does not have a file descriptor table.
+.El
 .Sh SEE ALSO
 .Xr close 2 ,
 .Xr fork 2 ,
@@ -332,7 +377,9 @@ system calls first appeared in
 .Fx 15.1 .
 The
 .Fn pdopenpid
-system call first appeared in
+and
+.Fn pddupfd
+system calls first appeared in
 .Fx 16.0 .
 .Pp
 Support for process descriptors mode was developed as part of the
@@ -356,5 +403,7 @@ with input from
 .An Alan Somers Aq Mt asomers@FreeBSD.org .
 The
 .Fn pdopenpid
-function was developed by
+and
+.Fn pddupfd
+functions were developed by
 .An Konstantin Belousov Aq Mt kib@FreeBSD.org .