DTRACE_DTRACE(4)       FreeBSD Kernel Interfaces Manual       DTRACE_DTRACE(4)

NAME

     dtrace_dtrace - a DTrace provider for BEGIN, END, and ERROR probes

SYNOPSIS

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

DESCRIPTION

     The dtrace provider implements three special probes related to the life
     cycle of the DTrace program itself.

dtrace:::BEGIN

     The dtrace:::BEGIN probe fires at the beginning of a dtrace(1), program
     before tracing has begun.  It provides a convenient place for
     initializing variables and printing column headers.

     Variables such as stack or execname cannot be relied upon in the
     execution context of the dtrace:::BEGIN probe.

dtrace:::END

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

dtrace:::ERROR

     The dtrace:::ERROR probe fires when an unexpected runtime error occurs in
     another probe.

     The following table describes the arguments to dtrace:::ERROR.

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

     The fault types are:
           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.

EXAMPLES

Example 1: Custom Column Headers

     The following script uses the dtrace:::BEGIN probe to print column
     headers.  Note the pragma line setting the `quiet' option to disable the
     default column headers.

       #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

     The following 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.

       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.

AUTHORS

     This manual page was written by Mateusz Piotrowski <0mp@FreeBSD.org>.

CAVEATS

     The dtrace:::ERROR probe arguments cannot be accessed through the typed
     args[] array.

     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.

FreeBSD 15.1-STABLE-HBSD         July 14, 2025                DTRACE_DTRACE(4)