[PATCH v2 08/20] doc: Fix anchor links for built-in variables

eugene.loh
2025-10-22T03:23:33Z

Anchor links (links pointing to specific locations within files) are
broken, at least for viewing the Markdown version of the DTrace User
Guide on github from common browsers, in at least two respects:

*) The arcane ID names are displayed at the anchor sites.

*) The links do not point to the specific locations within the files.

The problem is that the {#ID} syntax is not recognized.

Replace the {#ID} tags with more universal HTML tags.

This patch addresses the documentation on built-in variables.

Signed-off-by: Eugene Loh <eugene.loh@oracle.com>
---
.../dtrace_builtin_variable_reference.md | 60 +++++++++----------
1 file changed, 30 insertions(+), 30 deletions(-)

diff --git a/doc/userguide/reference/dtrace_builtin_variable_reference.md b/doc/userguide/reference/dtrace_builtin_variable_reference.md
index 28b3001ae..787137929 100644
--- a/doc/userguide/reference/dtrace_builtin_variable_reference.md
+++ b/doc/userguide/reference/dtrace_builtin_variable_reference.md
@@ -1,9 +1,9 @@

-# DTrace Built-in Variable Reference {#dt_ref_builtin_vars}
+# DTrace Built-in Variable Reference

DTrace includes a set of built-in scalar variables that can be used in D programs or scripts.

-## Macro Variables {#dt_macrov_scrpt}
+## Macro Variables

Macro variables are variables that are populated at runtime and identify information about the running `dtrace` process or the process running the compiler.

@@ -169,7 +169,7 @@ However, in probe descriptions, macro variables are expanded and concatenated wi

Macro variables are only expanded one time within each probe description field and they can't contain probe description delimiters \(`:`\).

-### Macro Arguments {#dt_macroa_scrpt}
+### Macro Arguments

The D compiler also provides a set of macro variables corresponding to any more argument operands that are specified as part of the `dtrace` command invocation. These *macro arguments* are accessed by using the built-in names `$0`, for the name of the D program file or `dtrace` command, `$1`, for the first extra operand, `$2` for the second operand, and so on. If you use the `-s` option, `$0` expands to the value of the name of the input file that's used with this option. For D programs that are specified on the command line, `$0` expands to the value of `argv[0]`, which is used to run the `dtrace` command itself.

@@ -243,7 +243,7 @@ To find the number of system calls made by the `date` command, save the script i
sudo dtrace -s syscall.d -c date
```

-## args\[\] {#dt_ref_vars_args}
+## args\[\]

The typed and mapped arguments, if any, to the current probe. The `args[]` array is accessed using an integer index. Use `dtrace -l -v` and check `Argument Types` for the type of each argument of each probe. For example, consider the system call `prlimit()`. The prototype on its `man` page \(`man -s 2 prlimit`\) is consistent with its DTrace probe listing \(`dtrace -lvn 'syscall:vmlinux:prlimit*:entry' | grep args`\). Specifically, argument 2, if non NULL, points to a `struct rlimit` with the requested resource limit, which can be traced with:

@@ -255,7 +255,7 @@ syscall:vmlinux:prlimit*:entry
}
```

-## arg0, …, arg9 {#dt_ref_var_arg0-9}
+## arg0, …, arg9

```
int64_t arg0, ..., arg9
@@ -271,7 +271,7 @@ rawfbt:vmlinux:ksys_write:entry
}
```

-## caller {#dt_ref_var_caller}
+## caller

```
uintptr_t caller
@@ -279,7 +279,7 @@ uintptr_t caller

The built-in variable `caller` references the program counter location of the current kernel thread at the time the probe fired.

-## curcpu {#dt_ref_var_curcpu}
+## curcpu

```
cpuinfo_t * curcpu
@@ -287,7 +287,7 @@ cpuinfo_t * curcpu

The built-in variable `curcpu` references the current physical CPU.

-## curthread {#dt_ref_var_curthread}
+## curthread

```
vmlinux`struct task_struct * curthread
@@ -295,7 +295,7 @@ vmlinux`struct task_struct * curthread

The built-in variable `curthread` references a `vmlinux` data type, for which members can be found by searching for "task\_struct" on the Internet.

-## epid {#dt_ref_var_epid}
+## epid

```
uint_t epid
@@ -306,12 +306,12 @@ The built-in variable `epid` references the enabled probe ID \(EPID\) for the cu
## errno

```
-int errno {#dt_ref_var_errno}
+int errno
```

The built-in variable `errno` references the error value returned by the last system call run by this thread.

-## execname {#dt_ref_var_execname}
+## execname

```
string execname
@@ -319,7 +319,7 @@ string execname

The built-in variable `execname` references the name that was passed to `execve()` to run the current process.

-## fds {#dt_ref_var_fds}
+## fds

```
fileinfo_t fds[]
@@ -327,7 +327,7 @@ fileinfo_t fds[]

The built-in `variable fds[]` is an array which has the files the current process has opened in a `fileinfo_t` array, indexed by file descriptor number. See [fileinfo\_t](dtrace_providers_io.md).

-## gid {#dt_ref_var_gid}
+## gid

```
gid_t gid
@@ -335,7 +335,7 @@ gid_t gid

The built-in variable `gid` references the real group ID of the current process.

-## id {#dt_ref_var_id}
+## id

```
uint_t id
@@ -343,7 +343,7 @@ uint_t id

The built-in variable `id` references the probe ID for the current probe. This ID is the system-wide unique identifier for the probe, as published by DTrace and listed in the output of `dtrace -l`.

-## ipl {#dt_ref_var_ipl}
+## ipl

```
uint_t ipl
@@ -355,7 +355,7 @@ The built-in variable `ipl` references the interrupt priority level \(IPL\) on t

This value is non-zero if interrupts are firing and zero otherwise. The non-zero value depends on whether preemption is active, and other factors, and can vary between kernel releases and kernel configurations.

-## pid {#dt_ref_var_pid}
+## pid

```
pid_t pid
@@ -363,7 +363,7 @@ pid_t pid

The built-in variable `pid` references the process ID of the current process.

-## ppid {#dt_ref_var_ppid}
+## ppid

```
pid_t ppid
@@ -371,7 +371,7 @@ pid_t ppid

The built-in variable `ppid` references the parent process ID of the current process.

-## probefunc {#dt_ref_var_probefunc}
+## probefunc

```
string probefunc
@@ -379,7 +379,7 @@ string probefunc

The built-in variable `probefunc` references the function name part of the current probe's description.

-## probemod {#dt_ref_var_probemod}
+## probemod

```
string probemod
@@ -387,7 +387,7 @@ string probemod

The built-in variable `probemod` references the module name part of the current probe's description.

-## probename {#dt_ref_var_probename}
+## probename

```
string probename
@@ -395,7 +395,7 @@ string probename

The built-in variable `probename` references the name part of the current probe's description.

-## probeprov {#dt_ref_var_probeprov}
+## probeprov

```
string probeprov
@@ -403,7 +403,7 @@ string probeprov

The built-in variable `probeprov` references the provider name part of the current probe's description.

-## stackdepth {#dt_ref_var_stackdepth}
+## stackdepth

```
uint32_t stackdepth
@@ -411,7 +411,7 @@ uint32_t stackdepth

The built-in variable `stackdepth` references the current thread's stack frame depth at probe firing time.

-## tid {#dt_ref_var_tid}
+## tid

```
id_t tid
@@ -419,7 +419,7 @@ id_t tid

The built-in variable `tid` references the thread ID of the current thread.

-## timestamp {#dt_ref_var_timestamp}
+## timestamp

```
uint64_t timestamp
@@ -427,7 +427,7 @@ uint64_t timestamp

The built-in variable `timestamp` references the current value of a nanosecond timestamp counter. This counter increments from an arbitrary point in the past. Therefore, only use the timestamp counter for relative computations.

-## ucaller {#dt_ref_var_ucaller}
+## ucaller

```
uint64_t ucaller
@@ -435,7 +435,7 @@ uint64_t ucaller

The built-in variable `ucaller` references the program counter location of the current user thread at the time the probe fired.

-## uid {#dt_ref_var_uid}
+## uid

```
uid_t uid
@@ -443,7 +443,7 @@ uid_t uid

The built-in variable `uid` references the real user ID of the current process.

-## uregs {#dt_ref_var_uregs}
+## uregs

```
uint64_t uregs[]
@@ -451,7 +451,7 @@ uint64_t uregs[]

The current thread's saved user-mode register values at probe firing time.

-## ustackdepth {#dt_ref_var_ustackdepth}
+## ustackdepth

```
uint32_t ustackdepth
@@ -459,7 +459,7 @@ uint32_t ustackdepth

The built-in variable `ustackdepth` references the user thread's stack frame depth at probe firing time.

-## vtimestamp {#dt_ref_var_vtimestamp}
+## vtimestamp

```
uint64_t vtimestamp
@@ -467,7 +467,7 @@ uint64_t vtimestamp

The built-in variable `vtimestamp` references the current value of a nanosecond timestamp counter that's virtualized to the amount of time that the current thread has been running on a CPU, minus the time spent in DTrace predicates and functions. This counter increments from an arbitrary point in the past. Therefore, only use the vtimestamp counter for relative time computations.

-## walltimestamp {#dt_ref_var_walltimestamp}
+## walltimestamp

```
int64_t walltimestamp
--
2.47.3