---
name: "dtrace_dtrace"
section: "4"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/dtrace_dtrace"
---

# dtrace\_dtrace(4)

a DTrace provider for BEGIN, END, and ERROR probes

## 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)](/dtrace/1.md), 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)](/dtrace/1.md) 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) |
| *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 |

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

- In 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)](/dtrace/1.md), [tracing(7)](/tracing/7.md) *The illumos Dynamic Tracing Guide*, 2008, Chapter dtrace Provider, 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)](/dtrace/1.md) 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)](/dtrace/1.md) will abort further processing of the **dtrace****:::ERROR** probe's actions.