DTRACE_DTRACE(4)

💫 dtrace_dtrace — the DTrace provider for BEGIN, END, and ERROR probes 💫

okay so this is the manual page for dtrace_dtrace in section 4 (kernel interfaces, iykyk), and it's literally all about the little provider that handles the life cycle of your DTrace program itself. main character energy fr. let's get into it 🎀

---

✨ SYNOPSIS ✨

dtrace:::BEGIN
dtrace:::END
dtrace:::ERROR

---

🌸 DESCRIPTION 🌸

The dtrace provider ships with three special probes that are all about the life cycle of the DTrace program itself — like, not your traced stuff, the DTrace program's own little journey from birth to death. obsessed. 🦋

🍼 dtrace:::BEGIN

The dtrace:::BEGIN probe fires right at the beginning of a dtrace(1) program, before tracing has even begun. it's giving "getting ready in the mirror before the party" — a super convenient place to initialize your variables and print column headers.

🚨 vibe check / important: variables like stack or execname cannot be relied upon in the execution context of the dtrace:::BEGIN probe. like, they're just not giving what you need there. don't come for them.

🎬 dtrace:::END

The dtrace:::END probe fires at the end of a dtrace(1) program, when all tracing has stopped. the closing credits. the farewell post. 😭

💀 dtrace:::ERROR

The dtrace:::ERROR probe fires when an unexpected runtime error happens in another probe. it's the friend who shows up when everything's on fire. 🔥

Here's what the arguments to dtrace:::ERROR actually mean, bestie:

• arg1 — the Enabled probe identifier (EPID) of the probe where the runtime error occurred.
• arg2 — the index of the action statement that caused the error.
• arg3 — the DIF offset into the action if available (otherwise -1).
• arg4 — the fault type.
• arg5 — the accessed address (or 0 if not applicable) when arg4 is of fault type DTRACEFLT_BADADDR, DTRACEFLT_BADALIGN, DTRACEFLT_KPRIV, or DTRACEFLT_UPRIV.

and here are the fault types, the whole squad 👑

• DTRACEFLT_UNKNOWN — unknown fault
• DTRACEFLT_BADADDR — bad address
• DTRACEFLT_BADALIGN — bad alignment
• DTRACEFLT_ILLOP — illegal operation
• DTRACEFLT_DIVZERO — divide-by-zero
• DTRACEFLT_NOSCRATCH — out of scratch space
• DTRACEFLT_KPRIV — illegal kernel access
• DTRACEFLT_UPRIV — illegal user access
• DTRACEFLT_TUPOFLOW — tuple stack overflow
• DTRACEFLT_BADSTACK — bad stack

---

📁 FILES 📁

• <sys/dtrace.h> — the header file containing the definitions of DTrace fault types. that's where all the DTRACEFLT_* lore lives 💅

---

🧪 EXAMPLES 🧪

🌈 Example 1: Custom Column Headers

This script uses the dtrace:::BEGIN probe to print column headers. note the pragma line setting the quiet option to disable the default column headers — because we are the default column headers now, periodt.

#pragma D option quiet

dtrace:::BEGIN
{
    printf("   %12s %-20s    %-20s %s\n",
        "DELTA(us)", "OLD", "NEW", "TIMESTAMP");
}

🔥 Example 2: Handling Runtime Errors with dtrace:::ERROR

This script causes a runtime error by dereferencing a pointer on address 19930908 in the BEGIN probe. as a result, the ERROR probe fires and prints out “Oops” along with the probe arguments. at that point, the program ends and fires the END probe. it's a whole arc fr 😭

ERROR
{
    printf("Oops\n");
    printf("EPID (arg1): %d\n", arg1);
    printf("Action index (arg2): %d\n", arg2);
    printf("DIF offset (arg3): %d\n", arg3);
    printf("Fault type (arg4): %d\n", arg4);
    printf("Accessed address (arg5): %X\n", arg5);
    exit(1);
}
BEGIN
{
    *(int *)0x19931101;
}
END {
    printf("Bye");
}

This script will result in the following output:

CPU     ID                    FUNCTION:NAME
  2      3                           :ERROR Oops
EPID (arg1): 2
Action index (arg2): 1
DIF offset (arg3): 16
Fault type: 1
arg5: 19931101

dtrace: error on enabled probe ID 2 (ID 1: dtrace:::BEGIN): invalid address (0x19931101) in action #1 at DIF offset 16
  2      2                             :END Bye

---

👀 SEE ALSO 👀

• dtrace(1)
• tracing(7)

The illumos Dynamic Tracing Guide, https://illumos.org/books/dtrace/chp-dtrace.html, 2008, Chapter dtrace Provider. go read it, it's iconic 📚

---

🫶 AUTHORS 🫶

This manual page was written by Mateusz Piotrowski <0mp@FreeBSD.org>. thank you for your service 🎀

---

⚠️ CAVEATS ⚠️

• The dtrace:::ERROR probe arguments cannot be accessed through the typed args[] array. nope. not happening. 🙈
• dtrace(1) will not fire the dtrace:::ERROR probe recursively. if an error occurs in one of the action statements of the dtrace:::ERROR, then dtrace(1) will abort further processing of the dtrace:::ERROR probe's actions. so like, don't try to error your way out of an error. it will simply stop. 💀

---

✿ that's the whole page, bestie ✿ this came out of the Debian side of things, dated July 14, 2025 — slay, happy reading, and remember: BEGIN is the getting-ready montage, END is the credits, and ERROR is the drama. 💖🦋🌸