... h1. {anchor:CHP-PROG} D Program Structure
D programs consist of a set of clauses that describe probes to enable and predicates and actions to bind to these probes. D programs can also contain declarations of variables, as described in [Chapter 3, Variables|variables], and definitions of new types, described in [Chapter 8, Type and Constant Definitions|Type and Constant Definitions]. This chapter formally describes the overall structure of a D program and features for constructing probe descriptions that match more than one probe. We'll also discuss the use of the C preprocessor, {{cpp}}, with D programs.
[Top|#top]
h2. {anchor:CHP-PROG-1} Probe Clauses and Declarations
As shown in our examples so far, a D program source file consists of one or more probe clauses that describe the instrumentation to be enabled by DTrace. Each probe clause has the general form:
{noformat}
probe descriptions
/ predicate /
{
action statements
}
{noformat}
The predicate and list of action statements may be omitted. Any directives found outside probe clauses are referred to as _declarations_. Declarations may only be used outside of probe clauses. No declarations inside of the enclosing {{{ }}} are permitted and declarations may not be interspersed between the elements of the probe clause shown above. Whitespace can be used to separate any D program elements and to indent action statements.\\
\\Declarations can be used to declare D variables and external C symbols as discussed in [Chapter 3, Variables|Variables], or to define new types for use in D, as described in [Chapter 8, Type and Constant Definitions|Type and Constant Definitions]. Special D compiler directives called _pragmas_ may also appear anywhere in a D program, including outside of probe clauses. D pragmas are specified on lines beginning with a {{#}} character. D pragmas are used, for example, to set run-time DTrace options; see [Chapter 16, Options and Tunables|Options and Tunables] for details.
[Top|#top]
h2. {anchor:CHP-PROG-2} Probe Descriptions
Every D program clause begins with a list of one or more probe descriptions, each taking the usual form:\\
\\ _provider_:_module_:_function_:_name_\\
\\If one or more fields of the probe description are omitted, the specified fields are interpreted from right to left by the D compiler. For example, the probe description {{foo:bar}} would match a probe with function {{foo}} and name {{bar}} regardless of the value of the probe's provider and module fields. Therefore, a probe description is really more accurately viewed as a _pattern_ that can be used to match one or more probes based on their names.\\
\\You should write your D probe descriptions specifying all four field delimiters so that you can specify the desired _provider_ on the left-hand side. If you don't specify the provider, you might obtain unexpected results if multiple providers publish probes with the same name. Similarly, future versions of DTrace might include new providers whose probes unintentionally match your partially specified probe descriptions. You can specify a provider but match any of its probes by leaving any of the module, function, and name fields blank. For example, the description {{syscall:::}} can be used to match every probe published by the DTrace {{syscall}} provider.\\
\\Probe descriptions also support a pattern matching syntax similar to the shell _globbing_ pattern matching syntax described in [{{sh}}(1)|http://docs.sun.com/doc/819-2239/sh-1?a=view]. Before matching a probe to a description, DTrace scans each description field for the characters {{*}}, {{?}}, and {{[}}. If one of these characters appears in a probe description field and is not preceded by a {{\}}, the field is regarded as a pattern. The description pattern must match the entire corresponding field of a given probe. The complete probe description must match on every field in order to successfully match and enable a probe. A probe description field that is not a pattern must exactly match the corresponding field of the probe. A description field that is empty matches any probe.\\
\\The special characters in the following table are recognized in probe name patterns:
h6. {anchor:TBL-GLOB} Probe Name Pattern Matching Characters
||Symbol||Description||
|{{*}}|Matches any string, including the null string.|
|{{?}}|Matches any single character.|
|{{[ ... ]}}|Matches any one of the enclosed characters. A pair of characters separated by {{-}} matches any character between the pair, inclusive. If the first character after the {{[}} is {{!}}, any character not enclosed in the set is matched.|
|{{\}}|Interpret the next character as itself, without any special meaning.|
Pattern match characters can be used in any or all of the four fields of your probe descriptions. You can also use patterns to list matching probes by using the patterns on the command line with {{dtrace \-l}}. For example, the command {{dtrace -l -f kmem_*}} lists all DTrace probes in functions whose names begin with the prefix {{kmem_}}.\\
\\If you want to specify the same predicate and actions for more than one probe description or description pattern, you can place the descriptions in a comma-separated list. For example, the following D program would trace a timestamp each time probes associated with entry to system calls containing the words “{{lwp}}” or “{{sock}}” fire:
{noformat}
syscall::*lwp*:entry, syscall::*sock*:entry
{
trace(timestamp);
}
{noformat}
A probe description may also specify a probe using its integer probe ID. For example, the clause:
{noformat}
12345
{
trace(timestamp);
}
{noformat}
could be used to enable probe ID 12345, as reported by {{dtrace -l -i 12345}}. You should always write your D programs using human-readable probe descriptions. Integer probe IDs are not guaranteed to remain consistent as DTrace provider kernel modules are loaded and unloaded or following a reboot.
[Top|#top]
h2. {anchor:CHP-PROG-PRED} Predicates
Predicates are expressions enclosed in slashes {{/ /}} that are evaluated at probe firing time to determine whether the associated actions should be executed. Predicates are the primary conditional construct used for building more complex control flow in a D program. You can omit the predicate section of the probe clause entirely for any probe, in which case the actions are always executed when the probe fires.\\
\\Predicate expressions can use any of the previously described D operators and may refer to any D data objects such as variables and constants. The predicate expression must evaluate to a value of integer or pointer type so that it can be considered as true or false. As with all D expressions, a zero value is interpreted as false and any non-zero value is interpreted as true.
[Top|#top]
h2. {anchor:CHP-PROG-4} Actions
Probe actions are described by a list of statements separated by semicolons ({{;}}) and enclosed in braces {{{ }}}. If you only want to note that a particular probe fired on a particular CPU without tracing any data or performing any additional actions, you can specify an empty set of braces with no statements inside. |