11.1 dtrace Provider

11.1.1 BEGIN Probe
11.1.2 END Probe
11.1.3 ERROR Probe
11.1.4 Stability

The dtrace provider provides several probes related to DTrace itself. You can use these probes to initialize state before tracing begins, process state after tracing has completed, and handle unexpected execution errors in other probes.

11.1.1 BEGIN Probe

The BEGIN probe fires before any other probe. No other probe will fire until all BEGIN clauses have completed. This probe can be used to initialize any state that is needed in other probes. The following example shows how to use the BEGIN probe to initialize an associative array to map between mmap() protection bits and a textual representation:

BEGIN
{
  prot[0] = "---";
  prot[1] = "r--";
  prot[2] = "-w-";
  prot[3] = "rw-";
  prot[4] = "--x";
  prot[5] = "r-x";
  prot[6] = "-wx";
  prot[7] = "rwx";
}

syscall::mmap:entry
{
  printf("mmap with prot = %s", prot[arg2 & 0x7]);
}

The BEGIN probe fires in an unspecified context. This means that the output of stack or ustack, and the value of context-specific variables (for example, execname), are all arbitrary. These values should not be relied upon or interpreted to infer any meaningful information. No arguments are defined for the BEGIN probe.

11.1.2 END Probe

The END probe fires after all other probes. This probe will not fire until all other probe clauses have completed. This probe can be used to process state that has been gathered or to format the output. The printa action is therefore often used in the END probe. The BEGIN and END probes can be used together to measure the total time spent tracing:

BEGIN
{
  start = timestamp;
}

/*
 * ... other tracing actions...
 */

END
{
  printf("total time: %d secs", (timestamp - start) / 1000000000);
}

See Section 3.4, “Data Normalization” and Section 6.2, “printa” for other common uses of the END probe.

As with the BEGIN probe, no arguments are defined for the END probe. The context in which the END probe fires is arbitrary and should not be depended upon.

When tracing with the bufpolicy option set to fill, adequate space is reserved to accommodate any records traced in the END probe. See Section 5.2.3, “fill Policy and END Probes” for details.

Note

The exit action causes tracing to stop and the END probe to fire. However, there is some delay between the invocation of the exit action and the END probe firing. During this delay, no probes will fire. After a probe invokes the exit action, the END probe is not fired until the DTrace consumer determines that exit has been called and stops tracing. The rate at which the exit status is checked can be set using statusrate option. For more information, see Chapter 10, Options and Tunables.

11.1.3 ERROR Probe

The ERROR probe fires when a run-time error occurs in executing a clause for a DTrace probe. For example, if a clause attempts to dereference a NULL pointer, the ERROR probe fires, as shown in the following example.

BEGIN
{
  *(char *)NULL;
}

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

When you run this program, you will see output like the following example:

# 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 output shows that the ERROR probe fired and that dtrace reported the error. dtrace has its own enabling of the ERROR probe to allow it to report errors. Using the ERROR probe, you can create your own custom error handling.

The arguments to the ERROR probe are shown 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 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 space 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 taken in the ERROR probe itself cause an error, that error is silently dropped. The ERROR probe is not recursively invoked.

11.1.4 Stability

The dtrace provider uses DTrace's stability mechanism to describe its stabilities as shown in the following table.

Element

Name Stability

Data Stability

Dependency Class

Provider

Stable

Stable

Common

Module

Private

Private

Unknown

Function

Private

Private

Unknown

Name

Stable

Stable

Common

Arguments

Stable

Stable

Common

For more information about the stability mechanism, see Chapter 15, Stability.