git: 7bcd3a04c869 - main - dtrace_priv.4: Document the DTrace priv provider

The branch main has been updated by 0mp:

URL: https://cgit.FreeBSD.org/src/commit/?id=7bcd3a04c8695d797665289ed48ff2d84afb8ac4

commit 7bcd3a04c8695d797665289ed48ff2d84afb8ac4
Author:     Mateusz Piotrowski <0mp@FreeBSD.org>
AuthorDate: 2025-11-06 23:43:19 +0000
Commit:     Mateusz Piotrowski <0mp@FreeBSD.org>
CommitDate: 2025-11-12 14:51:37 +0000

    dtrace_priv.4: Document the DTrace priv provider
    
    Fixes:  6efcc2f26ab0 Add static tracing for privilege checking
    MFC after:      2 weeks
    Differential Revision:  https://reviews.freebsd.org/D53630
---
 cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 |  3 +-
 share/man/man4/Makefile                      |  1 +
 share/man/man4/dtrace_priv.4                 | 59 ++++++++++++++++++++++++++++
 share/man/man9/priv.9                        |  3 +-
 4 files changed, 64 insertions(+), 2 deletions(-)

diff --git a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
index 5115d16a1286..86887bbe8dd9 100644
--- a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
+++ b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
@@ -20,7 +20,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd November 8, 2025
+.Dd November 12, 2025
 .Dt DTRACE 1
 .Os
 .Sh NAME
@@ -1309,6 +1309,7 @@ in
 .Xr dtrace_lockstat 4 ,
 .Xr dtrace_pid 4 ,
 .Xr dtrace_proc 4 ,
+.Xr dtrace_priv 4 ,
 .Xr dtrace_profile 4 ,
 .Xr dtrace_sched 4 ,
 .Xr dtrace_sctp 4 ,
diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 752ae9f165ca..31e3d67e93eb 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -1014,6 +1014,7 @@ _dtrace_provs=	dtrace_audit.4 \
 		dtrace_kinst.4 \
 		dtrace_lockstat.4 \
 		dtrace_pid.4 \
+		dtrace_priv.4 \
 		dtrace_proc.4 \
 		dtrace_profile.4 \
 		dtrace_sched.4 \
diff --git a/share/man/man4/dtrace_priv.4 b/share/man/man4/dtrace_priv.4
new file mode 100644
index 000000000000..97bd4c20eb2c
--- /dev/null
+++ b/share/man/man4/dtrace_priv.4
@@ -0,0 +1,59 @@
+.\"
+.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org>
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.Dd November 12, 2025
+.Dt DTRACE_PRIV 4
+.Os
+.Sh NAME
+.Nm dtrace_priv
+.Nd a DTrace provider for the kernel privilege checking API
+.Sh SYNOPSIS
+.Nm priv Ns Cm :kernel:priv_check:priv-ok
+.Nm priv Ns Cm :kernel:priv_check:priv-err
+.Sh DESCRIPTION
+The
+.Nm priv
+provider allows for tracing the
+.Xr priv 9
+API.
+.Pp
+The
+.Nm priv Ns Cm :kernel:priv_check:priv-ok
+probe fires upon a successful kernel privilege check.
+.Pp
+The
+.Nm priv Ns Cm :kernel:priv_check:priv-err
+probe fires upon a failed kernel privilege check.
+.Pp
+The only argument to the
+.Nm priv
+probes,
+.Fa args[0] ,
+is the requested privilege number
+.Ft int priv .
+.Sh EXAMPLES
+.Ss Example 1: Tracing Kernel Privilege Check Failures
+The following script captures an array of counters,
+one for each stack trace leading to a failed kernel privilege check:
+.Bd -literal -offset 2n
+priv:::priv-err
+{
+	@traces[stack()] = count();
+}
+.Ed
+.Sh SEE ALSO
+.Xr dtrace 1 ,
+.Xr tracing 7 ,
+.Xr priv 9 ,
+.Xr SDT 9
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm priv
+provider was written by
+.An Robert N. M. Watson Aq Mt rwatson@FreeBSD.org .
+.Pp
+This manual page was written by
+.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org .
diff --git a/share/man/man9/priv.9 b/share/man/man9/priv.9
index 80d0542e9bdf..6343940c89fb 100644
--- a/share/man/man9/priv.9
+++ b/share/man/man9/priv.9
@@ -26,7 +26,7 @@
 .\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd December 19, 2018
+.Dd November 12, 2025
 .Dt PRIV 9
 .Os
 .Sh NAME
@@ -106,6 +106,7 @@ privilege checks, and the caller is unable to tell if an access control
 failure occurred.
 .Sh SEE ALSO
 .Xr jail 2 ,
+.Xr dtrace_priv 4 ,
 .Xr mac 9 ,
 .Xr ucred 9
 .Sh AUTHORS