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, Chapter dtrace Provider, 2008, https://illumos.org/books/dtrace/chp-dtrace.html.

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.