git: 457fbd523d8d - stable/15 - d.7: Document macro variables

The branch stable/15 has been updated by 0mp:

URL: https://cgit.FreeBSD.org/src/commit/?id=457fbd523d8d0db5e0e5cccb8ba725c5b4014434

commit 457fbd523d8d0db5e0e5cccb8ba725c5b4014434
Author:     Mateusz Piotrowski <0mp@FreeBSD.org>
AuthorDate: 2026-05-07 14:20:46 +0000
Commit:     Mateusz Piotrowski <0mp@FreeBSD.org>
CommitDate: 2026-05-18 21:28:03 +0000

    d.7: Document macro variables
    
    MFC after:      1 week
    
    (cherry picked from commit 2b9301a22bc677239d3c0dc783d970f17e7ca294)
---
 share/man/man7/d.7 | 46 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 44 insertions(+), 2 deletions(-)

diff --git a/share/man/man7/d.7 b/share/man/man7/d.7
index 59b3389b121b..792f6d36ce73 100644
--- a/share/man/man7/d.7
+++ b/share/man/man7/d.7
@@ -1,9 +1,9 @@
 .\"
 .\" SPDX-License-Identifier: BSD-2-Clause
 .\"
-.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org>
+.\" Copyright (c) 2025-2026 Mateusz Piotrowski <0mp@FreeBSD.org>
 .\"
-.Dd October 28, 2025
+.Dd May 7, 2026
 .Dt D 7
 .Os
 .Sh NAME
@@ -39,6 +39,41 @@ This manual page serves as a short reference of the language.
 Refer to books listed in
 .Sx SEE ALSO
 for a complete reference.
+.Sh MACRO VARIABLES
+.Bl -column "$1, $2, $3, ..." "Syntax"
+.It Sy Name Ta Sy Description
+.It  Va  $1 , $2 , $3 , .\&.\&.  Ta  Macro arguments
+.It  Va  $egid                   Ta  Effective group ID Pq Xr getegid 2
+.It  Va  $euid                   Ta  Effective user ID Pq Xr geteuid 2
+.It  Va  $gid                    Ta  Real group ID Pq Xr getgid 2
+.It  Va  $pid                    Ta  Process ID Pq Xr getpid 2
+.It  Va  $pgid                   Ta  Process group ID Pq Xr getpgrp 2
+.It  Va  $ppid                   Ta  Parent process ID Pq Xr getppid 2
+.It  Va  $sid                    Ta  Session ID Pq Xr getsid 2
+.It  Va  $target                 Ta  Target process ID of the process
+specified via the
+.Fl p
+flag or created via the
+.Fl c
+flag.
+.It  Va  $uid                    Ta  Real user ID Pq Xr getuid 2
+.El
+.Pp
+The macro arguments correspond to the command-line operands.
+They expand to an integer, identifier, or string depending on the context.
+Prepending a macro argument with an extra dollar sign
+.Pq Ql $
+forces string expansion.
+.Pp
+For example,
+.Bd -literal -compact -offset indent
+dtrace -n 'syscall::fstatat: /execname == $$1/ {}' -- ls
+.Ed
+uses
+.Va $$1
+instead of
+.Va $1
+to expand to a string instead rather than to a global variable identifier.
 .Sh PROBE'S DESCRIPTION
 A probe's description consists of four elements:
 .Sm off
@@ -411,3 +446,10 @@ variable which typically provides the current working directory is
 not supported on
 .Fx
 at the moment.
+.Pp
+Macro variables
+.Va $projid
+and
+.Va $taskid
+are always 0 on
+.Fx .