git: 45633600acad - main - pdfork.2, rights.4: document pdptrace(2), CAP_PTRACE, and pdfork(PD_PTRACE_CAP)

The branch main has been updated by kib:

URL: https://cgit.FreeBSD.org/src/commit/?id=45633600acade39cccc3b8daace7b3aeeb1f5b07

commit 45633600acade39cccc3b8daace7b3aeeb1f5b07
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2026-07-19 22:56:32 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2026-08-28 11:52:32 +0000

    pdfork.2, rights.4: document pdptrace(2), CAP_PTRACE, and pdfork(PD_PTRACE_CAP)
    
    Reviewed by:    markj
    Sponsored by:   The FreeBSD Foundation
    MFC after:      1 week
    Differential revision:  https://reviews.freebsd.org/D58586
---
 lib/libsys/pdfork.2     | 51 ++++++++++++++++++++++++++++++++++++++++++++++---
 lib/libsys/ptrace.2     |  1 +
 share/man/man4/rights.4 |  3 +++
 3 files changed, 52 insertions(+), 3 deletions(-)

diff --git a/lib/libsys/pdfork.2 b/lib/libsys/pdfork.2
index 3c18a0f4130c..6ac85f717d01 100644
--- a/lib/libsys/pdfork.2
+++ b/lib/libsys/pdfork.2
@@ -66,6 +66,14 @@
 .Fc
 .Ft int
 .Fn pddupfd "int fd" "int remotefd" "int flags"
+.Ft int
+.Fo pdptrace
+.Fa "int req"
+.Fa "int fd"
+.Fa "int lwpid"
+.Fa "void *addr"
+.Fa "int data"
+.Fc
 .Sh DESCRIPTION
 Process descriptors are special file descriptors that represent processes,
 and are created using
@@ -83,7 +91,7 @@ on termination.
 .Fn pdfork
 can accept the
 .Fa pdflags:
-.Bl -tag -width PD_CLOEXEC
+.Bl -tag -width PD_PTRACE_CAP
 .It Dv PD_DAEMON
 Instead of the default terminate-on-close behaviour, allow the process to
 live until it is explicitly killed with
@@ -106,6 +114,16 @@ Set close-on-exec on process descriptor.
 .It Dv PD_NOWAITPID
 The parent cannot obtain the child's status with
 .Xr waitpid 2 .
+.It Dv PD_PTRACE_CAP
+Enable
+.Xr pdptrace 2
+requests on the resulting file descriptor.
+Otherwise the descriptor cannot be used to debug the child process.
+See
+.Xr rights 4
+for the description of the
+.Dv CAP_PTRACE
+capability.
 .El
 .Pp
 The
@@ -197,6 +215,32 @@ The
 argument is reserved and must be zero.
 Certain file descriptor types cannot be copied this way, namely
 kqueues.
+.Pp
+The
+.Fn pdptrace
+function enables execution of
+.Xr ptrace 2
+requests on the process specified by the process descriptor
+.Fa fd .
+.Pp
+In addition to the arguments taken by the
+.Xr ptrace 2 ,
+system call, the
+.Fa lwpid
+thread identifier can designate the thread on which the request
+must operate.
+The
+.Fa lwpid
+argument can be specified as \-1 if the call is not thread-specific,
+or kernel is allowed to select some thread on its own.
+.Pp
+Unlike the
+.Xr ptrace 2
+implementation,
+.Fn pdptrace
+does not clear the
+.Dv errno
+variable before executing the system call.
 .Sh INTERACTION OF PROCESS DESCRIPTORS AND Xr WAITPID 2
 .Pp
 The
@@ -461,8 +505,9 @@ functions were developed by
 with input from
 .An Alan Somers Aq Mt asomers@FreeBSD.org .
 The
-.Fn pdopenpid
+.Fn pdopenpid ,
+.Fn pddupfd ,
 and
-.Fn pddupfd
+.Fn pdptrace
 functions were developed by
 .An Konstantin Belousov Aq Mt kib@FreeBSD.org .
diff --git a/lib/libsys/ptrace.2 b/lib/libsys/ptrace.2
index cedcf92cbef1..c8513c7ba12d 100644
--- a/lib/libsys/ptrace.2
+++ b/lib/libsys/ptrace.2
@@ -1514,6 +1514,7 @@ holds the minimum buffer size required on return.
 .El
 .Sh SEE ALSO
 .Xr execve 2 ,
+.Xr pdptrace 2 ,
 .Xr sigaction 2 ,
 .Xr wait 2 ,
 .Xr execv 3 ,
diff --git a/share/man/man4/rights.4 b/share/man/man4/rights.4
index 396222a84579..93489300d161 100644
--- a/share/man/man4/rights.4
+++ b/share/man/man4/rights.4
@@ -484,6 +484,9 @@ Permit
 .It Dv CAP_PDKILL
 Permit
 .Xr pdkill 2 .
+.It Dv CAP_PTRACE
+Permit debugging using
+.Xr pdptrace 2 .
 .It Dv CAP_PDWAIT
 Permit
 .Xr pdwait 2 .