D(7)

🌈 D(7) — DTrace Scripting Language Overview 🌈

Okay bestie, so you're reading D(7), the manual for the DTrace scripting language — the D language, not the vitamin, not the grade, the tracing one 💅 This page is your lil cheat-sheet, no cap.

---

✨ SYNOPSIS ✨

provider:module:function:name [[/predicate/] {action}]

That's the whole vibe of a probe clause, right there. Iconic.

---

💖 DESCRIPTION 💖

So D is the dtrace(1) scripting language. This manual gives you a brief reference of the D language and scripting — it's giving "quick-start card".

This page is literally just a short reference of the language, fr fr. If you want the full novel, go read the books listed in SEE ALSO — they're the main characters of complete references.

---

🦋 PROBE'S DESCRIPTION 🦋

A probe's description is made of four elements, and yes you have to say all four:

provider:module:function:name

The exact meaning of module, function, and name depends on the provider — so like, context matters, iykyk.

---

🎀 USER-DEFINED VARIABLE TYPES 🎀

Here's the whole fam, with their syntax:

• global — variable_name
• aggregate — @variable_name
• thread-local — self->variable_name
• clause-local — this->variable_name

Tips, bestie, listen up:

• Always use the variable type with the smallest scope to minimize processing overhead.
• Use aggregate variables instead of global variables when possible. Aggregate variables are multi-CPU safe in contrast to global variables — big slay.

---

👑 BUILT-IN VARIABLES 👑

🔥 Probe Arguments

• args[] — The array of typed probe arguments.
• arg0, ..., arg9 — The untyped probe arguments represented as 64-bit unsigned integers. Only the first ten arguments are available this way.

🔥 Probe Information

• 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.
• id — The probe ID which uniquely identifies a probe available to DTrace.
• probeprov — The provider in the probe's description (provider:module:function:name).
• probemod — The module in the probe's description (provider:module:function:name).
• probefunc — The function in the probe's description (provider:module:function:name).
• probename — The name in the probe's description (provider:module:function:name).

🔥 Process Information

• execargs — The process arguments. Effectively, curthread->td_proc->p_args.
• execname — The name of the current process. Effectively, curthread->td_proc->p_comm.
• gid — The group ID of the current process.
• pid — The process ID of the current process.
• ppid — The parent process ID of the current process.
• uid — The user ID of the current process.

🔥 Thread Information

• uregs[] — The saved user-mode register values.
• cpu — The ID of the current CPU.
• stackdepth — The kernel stack frame depth.
• ustackdepth — The userspace counterpart of stackdepth.
• 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.
• errno — The errno(2) value of the last system call performed by the current thread.
• curlwpsinfo — A pointer to the lwpsinfo_t representation of the current thread. Refer to dtrace_proc(4) for more details.
• curpsinfo — A pointer to the psinfo_t representation of the current process. Refer to dtrace_proc(4) for more details.
• curthread — A pointer to the thread struct that is currently on-CPU. E.g., curthread->td_name returns the thread name. The <sys/proc.h> header documents all members of struct thread.
• caller — The address of the kernel thread instruction at the time of execution of the current probe.
• ucaller — The userspace counterpart of caller.

🔥 Timestamps

• timestamp — The number of nanoseconds since boot. Suitable for calculating relative time differences of elapsed time and latency.
• 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.
• walltimestamp — The number of nanoseconds since the Epoch (1970-01-01T00+00:00). Suitable for timestamping logs.

---

🧚 BUILT-IN FUNCTIONS 🧚

String-ology 💬

string strchr(string s, char c) Return a substring of s starting at the first occurance of c in s. Return NULL if c does not occur in s.

For example,

strchr("abc", 'b');

returns bc and

strchr("abc", 'd');

returns NULL.

---

string strjoin(string s1, string s2) Return a string resulting from concatenating s1 and s2.

For example,

strjoin("abc", "def")

returns abcdef.

---

string strrchr(string s, char c) Return a substring of s starting at the last occurance of c in s. Similar to strchr().

---

string strstr(string haystack, string needle) Return a substring of haystack starting at the first occurrence of needle. Return NULL if needle is not a substring of haystack.

For example,

strstr("abc1bc2", "bc")

returns bc1bc2 and

strstr("abc", "xy")

returns NULL.

---

string strtok(string s, string separators) Tokenize s with separators.

For example,

strtok("abcdefg", "xyzd")

returns abc.

---

size_t strlen(string s) Return the length of string s.

---

string substr(string s, int position, [int length]) Return a substring of string s starting at position. The substring will be at most length-long. If length is not specified, use the rest of the string. If position is greater than the size of s, return an empty string.

For example,

substr("abcd", 2)

returns cd,

substr("abcd", 2, 1)

returns c, and

substr("abcd", 99)

returns an empty string.

---

Aggregation Functions 🧮

• avg(value) — Average
• count() — Count
• llquantize(value, factor, low, high, nsteps) — Log-linear quantization
• lquantize(value, low, high, nsteps) — Linear quantization
• max(value) — Maximum
• min(value) — Minimum
• quantize(value) — Power-of-two frequency distribution
• stddev(value) — Standard deviation
• sum(value) — Sum

Kernel Destructive Functions 💀 (handle with care, bestie)

By default, dtrace(1) does not permit the use of destructive actions. Read that again.

• breakpoint() — Set a kernel breakpoint and transfer control to the ddb(4) kernel debugger.
• chill(nanoseconds) — Spin on the CPU for the specified number of nanoseconds.
• panic() — Panic the kernel. 😭

---

🌸 FILES 🌸

• /usr/share/dtrace — DTrace scripts shipped with FreeBSD base.

---

⭐ SEE ALSO ⭐

awk(1), dtrace(1), tracing(7)

The illumos Dynamic Tracing Guide, https://illumos.org/books/dtrace/, 2008.

Brendan Gregg and Jim Mauro, DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD, Prentice Hall, https://www.brendangregg.com/dtracebook/, 2011.

George Neville-Neil, Jonathan Anderson, Graeme Jenkinson, Brian Kidney, Domagoj Stolfa, Arun Thomas, and Robert N. M. Watson, Univeristy of Cambridge Computer Laboratory, OpenDTrace Specification version 1.0, https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-924.pdf, Cambridge, United Kingdom, August 2018.

---

🕰️ HISTORY 🕰️

This manual page first appeared in FreeBSD 15.0 — a fresh arrival, periodt.

---

🫶 AUTHORS 🫶

This manual page was written by Mateusz Piotrowski <0mp@FreeBSD.org> — give them their flowers 💐

---

🙈 BUGS 🙈

The cwd variable which typically provides the current working directory is not supported on FreeBSD at the moment. So like... don't come for it, it's not there yet, ngl.

---

Okay that's the whole page, bestie — you ate that read 💅 This little number is Debian-flavored, dated October 28, 2025, and it's literally the FreeBSD D(7) tea served fresh 🌈✨