... {anchor:top}
h1. {anchor:CHP-DTRACE} {{dtrace}} Provider
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.
[Top|#top]
h2. {anchor:CHP-DTRACE-ENTRY} {{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}}(2)|http://docs.sun.com/doc/819-2241/mmap-2?a=view] protection bits and a textual representation:
{noformat}
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]);
}
{noformat}
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.
[Top|#top]
h2. {anchor:CHP-DTRACE-END} The {{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:
{noformat}
BEGIN
{
start = timestamp;
}
/*
* ... other tracing actions...
*/
END
{
printf("total time: %d secs", (timestamp - start) / 1000000000);
}
{noformat}
See [Data Normalization|Aggregations#CHP-AGGS-NORMALIZATION] and [printa()|Output Formatting#CHP-FMT-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 [fill Policy and END Probes|#chp-buf-fillandend] for details.
{info:title=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 16, Options and Tunables|Options and Tunables].
{info}
[Top|#top]
h2. {anchor:CHP-DTRACE-ERROR} {{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 will fire, as shown in the following example.
h6. {anchor:CHP-DTRACE-ERROR.D} Example: {{error.d}}: Record Errors
{noformat}
BEGIN
{
*(char *)NULL;
}
ERROR
{
printf("Hit an error!");
}
{noformat}
When you run this program, you will see output like the following example:
{noformat}
# 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
{noformat}
The output shows that the {{ERROR}} probe fired, and also illustrates [{{dtrace}}(1M)|http://docs.sun.com/doc/819-2240/dtrace-1m?a=view] reporting 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 as follows:
|{{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 that action or {{-1}} if not applicable|
|{{arg4}}|The fault type|
|{{arg5}}|Value particular to the fault type|
The table below describes the various fault types and the value that {{arg5}} will have for each:
||{{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| |
... [Top|#top]
h2. {anchor:CHP-DTRACE-STABILITY} Stability
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 [Chapter 39, Stability|Stability].
||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|
{excerpt:hidden=true}Converted by tech dogg's sgml2wiki on Tue 20 Nov 2007 at 9:23:15 PM{excerpt} |