5 files changed, 577 insertions, 7 deletions
diff --git a/share/man/man7/Makefile b/share/man/man7/Makefile
index 021bf9251bda..1e50242a1754 100644
--- a/share/man/man7/Makefile
+++ b/share/man/man7/Makefile
@@ -6,6 +6,7 @@ MAN=	arch.7 \
 	bsd.snmpmod.mk.7 \
 	build.7 \
 	c.7 \
+	d.7 \
 	clocks.7 \
 	crypto.7 \
 	development.7 \
@@ -17,6 +18,7 @@ MAN=	arch.7 \
 	intro.7 \
 	maclabel.7 \
 	mitigations.7 \
+	named_attribute.7 \
 	operator.7 \
 	orders.7 \
 	ports.7 \
diff --git a/share/man/man7/d.7 b/share/man/man7/d.7
new file mode 100644
index 000000000000..30efb0249a77
--- /dev/null
+++ b/share/man/man7/d.7
@@ -0,0 +1,287 @@
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org>
+.\"
+.Dd July 14, 2025
+.Dt D 7
+.Os
+.Sh NAME
+.Nm D
+.Nd DTrace scripting language overview
+.Sh SYNOPSIS
+.Sm off
+.Ar provider Cm \&:
+.Ar module Cm \&:
+.Ar function Cm \&:
+.Ar name
+.Sm on
+.Sm off
+.Oo
+.Cm /
+.Ar predicate
+.Cm /
+.Sm on
+.Oc
+.Op Cm \&{ Ns Ar action Ns Cm \&}
+.Sh DESCRIPTION
+.Nm D
+is the
+.Xr dtrace 1
+scripting language.
+This manual provides a brief reference of the
+.Nm
+language and scripting.
+.Pp
+This manual page serves as a short reference of the language.
+Refer to books listed in
+.Sx SEE ALSO
+for a complete reference.
+.Sh PROBE'S DESCRIPTION
+A probe's description consists of four elements:
+.Sm off
+.D1 Ar provider Ns Cm \&: Ns Ar module Cm \&: Ar function Cm \&: Ar name
+.Sm on
+.Pp
+The exact meaning of
+.Ar module ,
+.Ar function ,
+and
+.Ar name
+depends on
+.Ar provider .
+.Sh USER-DEFINED VARIABLE TYPES
+.Bl -column "thread-local" "Syntax"
+.It Sy Type Ta Sy Syntax
+.It global       Ta Va variable_name
+.It thread-local Ta Sy self-> Ns Va variable_name
+.It clause-local Ta Sy this-> Ns Va variable_name
+.It aggregate  Ta Sy @ Ns Va variable_name
+.El
+.Pp
+.Em Tips :
+.Bl -dash -compact
+.It
+Always use the variable type with the smallest scope
+to minimize processing overhead.
+.It
+Use aggregate variables instead of global variables when possible.
+Aggregate variables are multi-CPU safe in contrast to global variables.
+.El
+.Sh BUILT-IN VARIABLES
+.Ss Probe Arguments
+.Bl -tag -width "arg0, ..., arg9"
+.It Va args[]
+The array of typed probe arguments.
+.It Va arg0 , ... , arg9
+The untyped probe arguments represented as 64-bit unsigned integers.
+Only the first ten arguments are available this way.
+.El
+.Ss Probe Information
+.Bl -tag -width probeprov
+.It Va epid
+The enabled probe ID which uniquely identifies an enabled probe.
+An enabled probe is defined by its probe ID, its predicates, and its actions.
+.It Va id
+The probe ID which uniquely identifies a probe available to DTrace.
+.It Va probeprov
+The
+.Ar provider
+in the probe's description
+.Sm off
+.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name
+.Sm on .
+.It Va probemod
+The
+.Ar module
+in the probe's description
+.Sm off
+.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name
+.Sm on .
+.It Va probefunc
+The
+.Ar function
+in the probe's description
+.Sm off
+.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name
+.Sm on .
+.It Va probename
+The
+.Ar name
+in the probe's description
+.Sm off
+.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name
+.Sm on .
+.El
+.Ss Process Information
+.Bl -tag -width execname
+.It Va execargs
+The process arguments.
+Effectively,
+.Ql curthread->td_proc->p_args .
+.It Va execname
+The name of the current process.
+Effectively,
+.Ql curthread->td_proc->p_comm .
+.It Va gid
+The group ID of the current process.
+.It Va pid
+The process ID of the current process.
+.It Va ppid
+The parent process ID of the current process.
+.It Va uid
+The user ID of the current process.
+.El
+.Ss Thread Information
+.Bl -tag -width curlwpsinfo
+.It Va uregs[]
+The saved user-mode register values.
+.It Va cpu
+The ID of the current CPU.
+.It Va stackdepth
+The kernel stack frame depth.
+.It Va ustackdepth
+The userspace counterpart of
+.Va stackdepth .
+.It Va tid
+The thread ID.
+Depending on the context,
+this can be either the ID of a kernel thread or a thread in a user process.
+.It Va errno
+The
+.Xr errno 2
+value of the last system call performed by the current thread.
+.It Va curlwpsinfo
+A pointer to the
+.Vt lwpsinfo_t
+representation of the current thread.
+Refer to
+.Xr dtrace_proc 4
+for more details.
+.It Va curpsinfo
+A pointer to the
+.Vt psinfo_t
+representation of the current process.
+Refer to
+.Xr dtrace_proc 4
+for more details.
+.It Va curthread
+A pointer to the thread struct that is currently on-CPU.
+E.g.,
+.Ql curthread->td_name
+returns the thread name.
+The
+.In sys/proc.h
+header documents all members of
+.Vt struct thread .
+.It Va caller
+The address of the kernel thread instruction at the time of execution
+of the current probe.
+.It Va ucaller
+The userspace counterpart of
+.Va caller .
+.El
+.Ss Timestamps
+.Bl -tag -width walltimestamp
+.It Va timestamp
+The number of nanoseconds since boot.
+Suitable for calculating relative time differences of elapsed time and latency.
+.It Va vtimestamp
+The number of nanoseconds that the current thread spent on CPU.
+The counter is not increased during handling of a fired DTrace probe.
+Suitable for calculating relative time differences of on-CPU time.
+.It Va walltimestamp
+The number of nanoseconds since the Epoch
+.Pq 1970-01-01T00+00:00 .
+Suitable for timestamping logs.
+.El
+.Sh BUILT-IN FUNCTIONS
+.Ss Aggregation Functions
+.Bl -tag -compact -width "llquantize(value, factor, low, high, nsteps)"
+.It Fn avg value
+Average
+.It Fn count
+Count
+.It Fn llquantize value factor low high nsteps
+Log-linear quantization
+.It Fn lquantize value low high nsteps
+Linear quantization
+.It Fn max value
+Maximum
+.It Fn min value
+Minimum
+.It Fn quantize value
+Power-of-two frequency distribution
+.It Fn stddev value
+Standard deviation
+.It Fn sum value
+Sum
+.El
+.Ss Kernel Destructive Functions
+By default,
+.Xr dtrace 1
+does not permit the use of destructive actions.
+.Bl -tag -width "chill(nanoseconds)"
+.It Fn breakpoint
+Set a kernel breakpoint and transfer control to
+the
+.Xr ddb 4
+kernel debugger.
+.It Fn chill nanoseconds
+Spin on the CPU for the specified number of
+.Fa nanoseconds .
+.It Fn panic
+Panic the kernel.
+.El
+.Sh FILES
+.Bl -tag -width /usr/share/dtrace
+.It Pa /usr/share/dtrace
+DTrace scripts shipped with
+.Fx
+base.
+.El
+.Sh SEE ALSO
+.Xr awk 1 ,
+.Xr dtrace 1 ,
+.Xr tracing 7
+.Rs
+.%B The illumos Dynamic Tracing Guide
+.%D 2008
+.%U https://illumos.org/books/dtrace/
+.Re
+.Rs
+.%A Brendan Gregg
+.%A Jim Mauro
+.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD
+.%I Prentice Hall
+.%D 2011
+.%U https://www.brendangregg.com/dtracebook/
+.Re
+.Rs
+.%A George Neville-Neil
+.%A Jonathan Anderson
+.%A Graeme Jenkinson
+.%A Brian Kidney
+.%A Domagoj Stolfa
+.%A Arun Thomas
+.%A Robert N. M. Watson
+.%C Cambridge, United Kingdom
+.%D August 2018
+.%T Univeristy of Cambridge Computer Laboratory
+.%R OpenDTrace Specification version 1.0
+.%U https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-924.pdf
+.Re
+.Sh HISTORY
+This manual page first appeared in
+.Fx 15.0 .
+.Sh AUTHORS
+.An -nosplit
+This manual page was written by
+.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org .
+.Sh BUGS
+The
+.Va cwd
+variable which typically provides the current working directory is
+not supported on
+.Fx
+at the moment.
diff --git a/share/man/man7/intro.7 b/share/man/man7/intro.7
index d889c2dd299f..43e48de87bc5 100644
--- a/share/man/man7/intro.7
+++ b/share/man/man7/intro.7
@@ -25,7 +25,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd June 23, 2025
+.Dd July 14, 2025
 .Dt INTRO 7
 .Os
 .Sh NAME
@@ -49,6 +49,9 @@ system timekeeping clocks available in
 .It Xr crypto 7
 cryptographic algorithms provided by OpenCrypto in
 .Fx
+.It Xr d 7
+.Xr dtrace 1
+scripting language overview
 .It Xr development 7
 development introduction to
 .Fx
diff --git a/share/man/man7/named_attribute.7 b/share/man/man7/named_attribute.7
new file mode 100644
index 000000000000..7cd778620357
--- /dev/null
+++ b/share/man/man7/named_attribute.7
@@ -0,0 +1,275 @@
+.\"
+.\" Copyright (c) 2025 Rick Macklem
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.Dd July 3, 2025
+.Dt NAMED_ATTRIBUTE 7
+.Os
+.Sh NAME
+.Nm named_attribute
+.Nd Solaris-like extended attribute system interface
+.Sh DESCRIPTION
+Description of the system interface for named attributes
+(the NFS Version 4 terminology).
+.Ss Introduction
+This document describes an alternate system interface for extended
+attributes as compared to
+.Xr extattr 2 .
+It is based on the interface provided by Solaris and NFS Version 4.
+.Pp
+This interface associates a directory, known as a named attribute directory,
+to a file system object.
+This directory is read in the same manner as a normal directory via the
+.Xr getdents 2
+or
+.Xr getdirentries 2
+system calls.
+The
+.Pa .\&
+and
+.Pa ..\&
+entries refer to the directory itself and to the associated file object,
+respectively.
+The other entries in this directory
+are the names of the extended attributes for the associated file object
+and are referred to as named attributes.
+These named attributes are regular files used to store the attribute's
+value.
+.Pp
+A named attribute directory does not live in the file system's name space.
+It is accessed via an
+.Xr open 2
+or
+.Xr openat 2
+system call done on a file to query the named attributes for the file,
+with the
+.Dv O_NAMEDATTR
+flag specified and a
+.Fa path
+argument of
+.Pa .\& .
+This file descriptor can be used as the
+.Fa fd
+argument for a variety of system calls, such as:
+.Xr fchdir 2 ,
+.Xr unlinkat 2
+and
+.Xr renameat 2 .
+.Xr renameat 2
+is only permitted to rename a named attribute within the same named
+attribute directory.
+.Pp
+When a file descriptor for a file object in the file system's namespace
+is used as the
+.Fa fd
+argument of an
+.Xr openat 2
+along with the
+.Fa flag
+.Dv O_NAMEDATTR
+and a
+.Fa path
+argument that is the name of a named attribute (not
+.Pa .\&
+or
+.Pa ..\&
+), a file descriptor for the named attribute is returned.
+If the
+.Fa flag
+.Dv O_CREAT
+is specified, the named attribute will be created if it does not exist.
+The
+.Fa path
+argument must be a single component name, with no embedded
+.Dq /
+in it.
+I/O on these named attribute file descriptors may be performed by
+standard I/O system calls
+such as:
+.Xr read 2 ,
+.Xr write 2 ,
+.Xr lseek 2
+and
+.Xr ftruncate 2 .
+.Pp
+The
+.Dv _PC_NAMEDATTR_ENABLED
+.Fa name
+argument to
+.Xr pathconf 2
+will return 1 if the file system supports named attributes.
+The
+.Dv _PC_HAS_NAMEDATTR
+.Fa name
+argument to
+.Xr pathconf 2
+will return 1 if there are one or more named attributes for the file.
+If an application does a
+.Xr openat 2
+of
+.Dq .\&
+to open a named attribute directory when no named attribute directory exists,
+an empty named attribute directory will be created.
+Testing
+.Dv _PC_HAS_NAMEDATTR
+can be done to avoid creating these named attribute directories unnecessarily.
+.Pp
+The named attribute interface is a different mechanism/system call interface for
+manipulating extended attributes compared with
+.Xr extattr 2 .
+Although the named attribute machanism might require different internal
+implementation
+of extended attributes within a file system, both ZFS and NFSv4 provide
+both mechanisms, which can be used interchangeably to manipulate
+extended attributes, but with a couple of limitations.
+.Bl -bullet
+.It
+The
+.Xr extattr 2
+interface requires that an extended attribute's value be set or acquired
+via a single system call using a single buffer.
+This limits the size of the attribute's value.
+.It
+The named attribute interface does not support system namespace
+extended attributes and,
+as such, system namespace extended attributes must be manipulated via
+.Xr extattr 2 .
+.El
+.Pp
+The named attribute mechanism/system call interface provides certain
+advantages over
+.Xr extattr 2 .
+Since the attribute's value is updated via
+.Xr read 2
+and
+.Xr write 2
+system calls, the attribute's data may be as large as any regular file
+and may be partially updated.
+(Note that this interface does not provide the atomicity guarantee that
+.Xr extattr 2
+does.)
+The permission to access a named attribute directory is determined from
+the access control information for the associated file object.
+However, access control information can be set on each individual attribute
+in a manner similar to a regular file.
+This provides
+.Dq per attribute
+granular control over attribute permissions via
+.Xr fchown 2 .
+.Pp
+At this time, the only local file system which supports this interface
+is ZFS and only if the
+.Dv xattr
+property is set to
+.Dq dir .
+(Note that, even when
+.Dq zfs get xattr <file-system>
+shows
+.Dq on
+the command
+.Dq zfs set xattr=dir <file-system>
+must be done, followed by a remount to make the setting take effect.)
+A NFSv4 mount will also support this interface, but only if the NFSv4
+server file system supports named attributes (the openattr operation).
+The
+.Fx
+NFSv4 server supports named attributes only
+for ZFS exported file systems where the
+.Dq xattr
+property is set to
+.Dq dir
+for the file system.
+.Sh EXAMPLES
+.Bd -literal
+#include <stdio.h>
+#include <dirent.h>
+#include <fcntl.h>
+#include <unistd.h>
+
+\&...
+
+/* For a file called "myfile". Failure checks removed for brevity. */
+int file_fd, nameddir_fd, namedattr_fd;
+ssize_t siz;
+char buf[DIRBLKSIZ], *cp;
+struct dirent *dp;
+long named_enabled, has_named_attrs;
+
+\&...
+/* Check to see if named attributes are supported. */
+named_enabled = pathconf("myfile", _PC_NAMEDATTR_ENABLED);
+if (named_enabled <= 0)
+	err(1, "Named attributes not enabled");
+/* Test to see if named attribute(s) exist for the file. */
+has_named_attrs = pathconf("myfile", _PC_HAS_NAMEDATTR);
+if (has_named_attrs == 1)
+	printf("myfile has named attribute(s)\\n");
+else
+	printf("myfile does not have any named attributes\\n");
+/* Open a named attribute directory. */
+file_fd = open("myfile", O_RDONLY, 0);
+nameddir_fd = openat(file_fd, ".", O_NAMEDATTR, 0);
+\&...
+/* and read it, assuming it all fits in DIRBLKSIZ for simplicity. */
+siz = getdents(fd, buf, sizeof(buf));
+cp = buf;
+while (cp < &buf[siz]) {
+	dp = (struct dirent *)cp;
+	printf("name=%s\\n", dp->d_name);
+	cp += dp->d_reclen;
+}
+\&...
+/* Open/create a named attribute called "foo". */
+namedattr_fd = openat(file_fd, "foo", O_CREAT | O_RDWR |
+    O_TRUNC | O_NAMEDATTR, 0600);
+\&...
+/* Write foo's attribute value. */
+write(namedattr_fd, "xxxyyy", 6);
+\&...
+/* Read foo's attribute value. */
+lseek(namedattr_fd, 0, SEEK_SET);
+siz = read(namedattr_fd, buf, sizeof(buf));
+\&...
+/* And close "foo". */
+close(namedattr_fd);
+\&...
+/* Rename "foo" to "oldfoo". */
+renameat(nameddir_fd, "foo", nameddir_fd, "oldfoo");
+/* and delete "oldfoo". */
+unlinkat(nameddir_fd, "oldfoo", AT_RESOLVE_BENEATH);
+.Ed
+.Pp
+The
+.Xr runat 1
+command may be used to perform shell commands on named attributes.
+For example:
+.Bd -literal
+$ runat myfile cp /etc/hosts attrhosts	# creates attrhosts
+$ runat myfile cat attrhosts		# displays contents of attrhosts
+$ runat myfile ls -l			# lists the attributes for myfile
+.Ed
+.Pp
+If using the
+.Xr bash 1
+shell, the command
+.Dq cd -@ foo
+enters the named attribute directory for the file object
+.Dq foo .
+.Sh SEE ALSO
+.Xr bash 1 ,
+.Xr runat 1 ,
+.Xr chdir 2 ,
+.Xr extattr 2 ,
+.Xr lseek 2 ,
+.Xr open 2 ,
+.Xr pathconf 2 ,
+.Xr read 2 ,
+.Xr rename 2 ,
+.Xr truncate 2 ,
+.Xr unlinkat 2 ,
+.Xr write 2 ,
+.Xr zfsprops 7
+.Sh HISTORY
+This interface first appeared in
+.Fx 15.0 .
diff --git a/share/man/man7/tracing.7 b/share/man/man7/tracing.7
index 0bd64f197084..f3e3a5bf98c4 100644
--- a/share/man/man7/tracing.7
+++ b/share/man/man7/tracing.7
@@ -3,12 +3,12 @@
 .\"
 .\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org>
 .\"
-.Dd June 19, 2025
+.Dd July 12, 2025
 .Dt TRACING 7
 .Os
 .Sh NAME
 .Nm tracing
-.Nd introduction to tracing and performance monitoring facilities
+.Nd introduction to tracing and performance monitoring facilities on FreeBSD
 .Sh DESCRIPTION
 .Fx
 features a large variety of tracing and performance monitoring facilities.
@@ -34,7 +34,6 @@ for more details.
 is a user-friendly wrapper for DTrace.
 It simplifies common DTrace usage patterns and requires less expert knowledge
 to operate.
-.Pp
 .Ss Userland Tracing
 .Xr truss 1
 traces system calls.
@@ -55,7 +54,8 @@ it asynchronously logs entries to a trace file configured with
 .Xr ktrace 2
 (typically
 .Pa ktrace.out ) ,
-and it can log other types of kernel events, such as page faults and name lookups
+and it can log other types of kernel events, such as page faults
+and name lookups
 .Po refer to
 .Fl t
 in
@@ -73,11 +73,14 @@ It comes in handy for some niche purposes during kernel development.
 It lets kernel programmers log events to a global ring buffer,
 which can later be dumped using
 .Xr ktrdump 8 .
+.Ss Hardware-Accelerated Tracing
+.Xr hwt 4
+is a kernel trace framework providing infrastructure
+for hardware-assisted tracing.
 .Ss Hardware Counters
-.Pp
 .Xr pmcstat 8 ,
 and its kernel counterpart,
-.Xr hwmpc 4 ,
+.Xr hwpmc 4 ,
 is the
 .Fx
 facility for conducting performance measurements with hardware counters.