11.1.3 ERROR Probe

The ERROR probe fires when a runtime error occurs during the execution of a clause for a DTrace probe. As shown in the following example, if a clause attempts to dereference a NULL pointer, the ERROR probe fires. Save it in a file named error.d:

BEGIN
{
  *(char *)NULL;
}

ERROR
{
  printf("Hit an error!");
}

When you run this program, output similar to the following is displayed:

# dtrace -s error.d 
dtrace: script 'error.d' matched 2 probes
CPU     ID                    FUNCTION:NAME
  1      3                           :ERROR Hit an error!
dtrace: error on enabled probe ID 1 (ID 1: dtrace:::BEGIN):
invalid address (0x0) in action #1 at DIF offset 16
^C

The previous output indicates that the ERROR probe fired and that dtrace reported the error. dtrace has its own enabling of the ERROR probe so that it can report errors. Using the ERROR probe, you can create your own custom error handling.

The arguments to the ERROR probe are described in the following table.

Argument

Description

arg1

The enabled probe identifier (EPID) of the probe that caused the error.

arg2

The index of the action that caused the fault.

arg3

The DIF offset into the action or -1 if not applicable.

arg4

The fault type.

arg5

Value that is particular to the fault type.

The following table describes the various fault types that can be specified in arg4 and the values that arg5 can take for each fault type.

arg4 Value

Description

arg5 Meaning

DTRACEFLT_UNKNOWN

Unknown fault type

None

DTRACEFLT_BADADDR

Access to unmapped or invalid address

Address accessed

DTRACEFLT_BADALIGN

Unaligned memory access

Address accessed

DTRACEFLT_ILLOP

Illegal or invalid operation

None

DTRACEFLT_DIVZERO

Integer divide by zero

None

DTRACEFLT_NOSCRATCH

Insufficient scratch memory to satisfy scratch allocation

None

DTRACEFLT_KPRIV

Attempt to access a kernel address or property without sufficient privileges

Address accessed or 0 if not applicable

DTRACEFLT_UPRIV

Attempt to access a user address or property without sufficient privileges

Address accessed or 0 if not applicable

DTRACEFLT_TUPOFLOW

DTrace internal parameter stack overflow

None

DTRACEFLT_BADSTACK

Invalid user process stack

Address of invalid stack pointer

If the actions that are taken in the ERROR probe cause an error, that error is silently dropped. The ERROR probe is not recursively invoked.