The dtrace provider provides several probes related to DTrace. 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.
The BEGIN probe fires before any other probe. No other probe fires until all BEGIN clauses are completed. You can use this probe to initialize any state that is required 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. For information about the mmap system call, see the mmap(2) man page.
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.
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. Therefore, the END probe often uses the printa action. You can use the BEGIN and END probes together to measure the total time spent in tracing.
BEGIN
{
start = timestamp;
}
/*
* ... other tracing actions...
*/
END
{
printf("total time: %d secs", (timestamp - start) / 1000000000);
}
For information about other uses of the END probe, see Data Normalization and printa Action.
No arguments are defined for the END probe. The context in which the END probe fires is arbitrary.
When tracing with the bufpolicy option set to fill, adequate space is reserved to accommodate any records traced in the END probe. For more information, see fill Policy and END Probes.
BEGIN
{
*(char *)NULL;
}
ERROR
{
printf("Hit an error!");
}
When you run this program, you will see the following output:
# dtrace -s ./error.d dtrace: script './error.d' matched 2 probes CPU ID FUNCTION:NAME 2 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 12 dtrace: 1 error on CPU 2
The output shows that the ERROR probe fired, and also illustrates dtrace reporting the error. dtrace has its own enabling of the ERROR probe to allow it to report errors. Use the ERROR probe to customize error handling.
The arguments to the ERROR probe are as follows:
arg1 – Enabled probe identifier (EPID) of the probe that caused the error
arg2 – Index of the action that caused the fault
arg3 – DIF offset into that action or -1 if not applicable
arg4 – Fault type
arg5 – Value particular to the fault type
The following table describes the arg4 fault types and the value and its meaning for the arg5.
|
If the error actions taken in the ERROR probe cause an error, the error is dropped and the ERROR probe is not recursively invoked.
The dtrace provider uses DTrace's stability mechanism to describe its stabilities as shown in the following table. For more information about the stability mechanism, see DTrace Stability Mechanisms.
|