As shown in the examples in this guide thus 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 uses the following general form:

probe descriptions 
/ predicate / 
{
  action statements
}

Note that the predicate and list of action statements may be omitted. Any directives that are found outside of probe clauses are referred to as declarations. Declarations may only be used outside of probe clauses. No declarations are permitted inside of the enclosing braces ({}). Also, declarations may not be interspersed between the elements of the probe clause in previous example. You can use white space to separate any D program elements and to indent action statements.

Declarations can be used to declare D variables and external C symbols or to define new types for use in D. For more details, see Variables and 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. For example, D pragmas are used to set DTrace runtime options. See Options and Tunables for more details.

Every program clause begins with a list of one or more probe descriptions, each taking the following 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 the 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, subsequent versions of DTrace might include new providers with probes that 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 that is published by the DTrace syscall provider.

Probe descriptions also support a pattern-matching syntax similar to the shell globbing pattern matching syntax that is described in the sh(1) manual page. 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. To successfully match and enable a probe, the complete probe description must match on every field. A probe description field that is not a pattern must exactly match the corresponding field of the probe. Note that a description field that is empty matches any probe.

The special characters in the following table are recognized in probe name patterns.

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 them on the command line by using the dtrace -l command. For example, the dtrace -l -f kmem_* command lists all of the DTrace probes in functions with names that 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 strings “read” or “write” fire:

syscall::*read*:entry, syscall::*write*:entry
{
  trace(timestamp);
}

A probe description can also specify a probe by using its integer probe ID, for example, the following clause could be used to enable probe ID 12345, as reported by dtrace -l -i 12345:

12345
{
  trace(timestamp);
}

Predicates are expressions that are enclosed in a pair of slashes (//) that are then evaluated at probe firing time to determine whether the associated actions should be executed. Predicates are the primary conditional construct that are 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 D operators and can 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.

Probe actions are described by a list of statements that are separated by semicolons (;) and enclosed in braces ({}). An empty set of braces with no statements included, leads to the default actions, which are to print the CPU and the probe.

The actions for a probe are executed in program order, regardless of whether those actions are in the same clause or in different clauses.

No other ordering constraints are imposed. It is not uncommon for the output from two distinct probes to appear interspersed or in an opposite order from which the probes fired. Also, output might appear misordered if it came from different CPUs.

The C programming language that is used for defining Linux system interfaces includes a preprocessor that performs a set of initial steps in C program compilation. The C preprocessor is commonly used to define macro substitutions, where one token in a C program is replaced with another predefined set of tokens, or to include copies of system header files. You can use the C preprocessor in conjunction with your D programs by specifying the dtrace command with the -c option. This option causes the dtrace command to execute the cpp preprocessor on your program source file and then pass the results to the D compiler. The C preprocessor is described in more detail in The C Programming Language by Kernighan and Ritchie, details of which are referenced in Preface.

The D compiler automatically loads the set of C type descriptions that is associated with the operating system implementation. However, you can use the preprocessor to include other type definitions such as the types that are used in your own C programs. You can also use the preprocessor to perform other tasks such as creating macros that expand to chunks of D code and other program elements. If you use the preprocessor with your D program, you may only include files that contain valid D declarations. The D compiler can correctly interpret C header files that include only external declarations of types and symbols. However, the D compiler cannot parse C header files that include additional program elements, such as C function source code, which produces an appropriate error message.

For example, the following D statements access an associative array, whose values must all be type int and whose tuples must all have signature string,int, setting an element to 456 and then incrementing it to 457:

a["hello", 123] = 456;
a["hello", 123]++;

Now let us use an associative array in a D program. Type the following program and save it in a file named rwtime.d:

syscall::read:entry,
syscall::write:entry
/pid == $1/
{
  ts[probefunc] = timestamp;
}
syscall::read:return,
syscall::write:return
/pid == $1 && ts[probefunc] != 0/
{
  printf("%d nsecs", timestamp - ts[probefunc]);
}

As with stracerw.d, specify the ID of the shell process when you execute rwtime.d. If you type a few shell commands, you will see the time elapsed during each system call. Type in the following command and then press return a few times in your other shell:

# dtrace -s rwtime.d `/usr/bin/pgrep -n bash`
dtrace: script 'rwtime.d' matched 4 probes
CPU     ID                    FUNCTION:NAME
  0      8                     write:return 51962 nsecs
  0      8                     write:return 45257 nsecs
  0      8                     write:return 40787 nsecs
  1      6                      read:return 925959305 nsecs
  1      8                     write:return 46934 nsecs
  1      8                     write:return 41626 nsecs
  1      8                     write:return 176839 nsecs
...
^C
#

To trace the elapsed time for each system call, you must instrument both the entry to and return from read() and write() and measure the time at each point. Then, on return from a given system call, you must compute the difference between our first and second timestamp. You could use separate variables for each system call, but this would make the program annoying to extend to additional system calls. Instead, it is easier to use an associative array indexed by the probe function name. The following is the first probe clause:

syscall::read:entry,
syscall::write:entry
/pid == $1/
{
  ts[probefunc] = timestamp;
}

This clause defines an array named ts and assigns the appropriate member the value of the DTrace variable timestamp. This variable returns the value of an always-incrementing nanosecond counter. When the entry timestamp is saved, the corresponding return probe samples timestamp again and reports the difference between the current time and the saved value:

syscall::read:return,
syscall::write:return
/pid == $1 && ts[probefunc] != 0/
{
  printf("%d nsecs", timestamp - ts[probefunc]);
}

The predicate on the return probe requires that DTrace is tracing the appropriate process and that the corresponding entry probe has already fired and assigned ts[probefunc] a non-zero value. This trick eliminates invalid output when DTrace first starts. If your shell is already waiting in a read() system call for input when you execute dtrace, the read:return probe fires without a preceding read:entry for this first read() and ts[probefunc] will evaluate to zero because it has not yet been assigned.

D identifier names are composed of uppercase and lowercase letters, digits, and underscores, where the first character must be a letter or underscore. All identifier names beginning with an underscore (_) are reserved for use by the D system libraries. You should avoid using these names in your D programs. By convention, D programmers typically use mixed-case names for variables and all uppercase names for constants.

D language keywords are special identifiers that are reserved for use in the programming language syntax itself. These names are always specified in lowercase and must not be used for the names of D variables. The following table lists the keywords that are reserved for use by the D language.

D reserves for use as keywords a superset of the ANSI C keywords. The keywords reserved for future use by the D language are marked with “*”. The D compiler produces a syntax error if you attempt to use a keyword that is reserved for future use. The keywords that are defined by D but not defined by ANSI C are marked with “+”. D provides the complete set of types and operators found in ANSI C. The major difference in D programming is the absence of control-flow constructs. Note that keywords associated with control-flow in ANSI C are reserved for future use in D.

D provides fundamental data types for integers and floating-point constants. Arithmetic may only be performed on integers in D programs. Floating-point constants may be used to initialize data structures, but floating-point arithmetic is not permitted in D. In Oracle Linux, D provides a 64-bit data model for use in writing programs. However, a 32-bit data model is not supported. The data model used when executing your program is the native data model that is associated with the active operating system kernel, which must also be 64-bit.

The names of the integer types and their sizes in the 64-bit data model are shown in the following table. Integers are always represented in twos-complement form in the native byte-encoding order of your system.

Integer types can be prefixed with the signed or unsigned qualifier. If no sign qualifier is present, it is assumed that the type is signed. The D compiler also provides the type aliases that are listed in the following table.

These type aliases are equivalent to using the name of the corresponding base type listed in the previous table and are appropriately defined for each data model. For example, the uint8_t type name is an alias for the type unsigned char. See Type and Constant Definitions for information about how to define your own type aliases for use in D programs.

D provides floating-point types for compatibility with ANSI C declarations and types. Floating-point operators are not supported in D, but floating-point data objects can be traced and formatted with the printf function. You can use the floating-point types that are listed in the following table.

D also provides the special type string to represent ASCII strings. Strings are discussed in more detail in DTrace Support for Strings.

Integer constants can be written in decimal (12345), octal (012345), or hexadecimal (0x12345) format. Octal (base 8) constants must be prefixed with a leading zero. Hexadecimal (base 16) constants must be prefixed with either 0x or 0X. Integer constants are assigned the smallest type among int, long, and long long that can represent their value. If the value is negative, the signed version of the type is used. If the value is positive and too large to fit in the signed type representation, the unsigned type representation is used. You can apply one of the suffixes listed in the following table to any integer constant to explicitly specify its D type.

Floating-point constants are always written in decimal format and must contain either a decimal point (12.345), an exponent (123e45), or both ( 123.34e-5). Floating-point constants are assigned the type double by default. You can apply one of the suffixes listed in the following table to any floating-point constant to explicitly specify its D type.

Character constants are written as a single character or escape sequence that is enclosed in a pair of single quotes ('a'). Character constants are assigned the int type rather than char and are equivalent to an integer constant with a value that is determined by that character's value in the ASCII character set. See the ascii(7) manual page for a list of characters and their values. You can also use any of the special escape sequences that are listed in the following table in your character constants. D supports the same escape sequences as those found in ANSI C.

You can include more than one character specifier inside single quotes to create integers with individual bytes that are initialized according to the corresponding character specifiers. The bytes are read left-to-right from your character constant and assigned to the resulting integer in the order corresponding to the native endianness of your operating environment. Up to eight character specifiers can be included in a single character constant.

Strings constants of any length can be composed by enclosing them in a pair of double quotes ("hello"). A string constant may not contain a literal newline character. To create strings containing newlines, use the \n escape sequence instead of a literal newline. String constants can contain any of the special character escape sequences that are shown for character constants previously. Similar to ANSI C, strings are represented as arrays of characters terminated by a null character (\0) that is implicitly added to each string constant you declare. String constants are assigned the special D type string. The D compiler provides a set of special features for comparing and tracing character arrays that are declared as strings. See DTrace Support for Strings for more information.

D provides the binary arithmetic operators that are described in the following table for use in your programs. These operators all have the same meaning for integers that they do in ANSI C.

Arithmetic in D may only be performed on integer operands or on pointers. See Pointers and Scalar Arrays. Arithmetic may not be performed on floating-point operands in D programs. The DTrace execution environment does not take any action on integer overflow or underflow. You must specifically check for these conditions in situations where overflow and underflow can occur.

However, the DTrace execution environment does automatically check for and report division by zero errors resulting from improper use of the / and % operators. If a D program executes an invalid division operation, DTrace automatically disables the affected instrumentation and reports the error. Errors that are detected by DTrace have no effect on other DTrace users or on the operating system kernel. You therefore do not need to be concerned about causing any damage if your D program inadvertently contains one of these errors.

In addition to these binary operators, the + and - operators can also be used as unary operators as well, and these operators have higher precedence than any of the binary arithmetic operators. The order of precedence and associativity properties for all of the D operators is presented in Table 2-12. You can control precedence by grouping expressions in parentheses (()).

D provides the binary relational operators that are described in the following table for use in your programs. These operators all have the same meaning that they do in ANSI C.

Relational operators are most frequently used to write D predicates. Each operator evaluates to a value of type int, which is equal to one if the condition is true, or zero if it is false.

Relational operators can be applied to pairs of integers, pointers, or strings. If pointers are compared, the result is equivalent to an integer comparison of the two pointers interpreted as unsigned integers. If strings are compared, the result is determined as if by performing a strcmp() on the two operands. The following table shows some example D string comparisons and their results.

Relational operators can also be used to compare a data object associated with an enumeration type with any of the enumerator tags defined by the enumeration. Enumerations are a facility for creating named integer constants and are described in more detail in Type and Constant Definitions.

D provides the binary logical operators that are listed in the following table for use in your programs. The first two operators are equivalent to the corresponding ANSI C operators.

Logical operators are most frequently used in writing D predicates. The logical AND operator performs the following short-circuit evaluation: if the left-hand operand is false, the right-hand expression is not evaluated. The logical OR operator also performs the following short-circuit evaluation: if the left-hand operand is true, the right-hand expression is not evaluated. The logical XOR operator does not short-circuit. Both expression operands are always evaluated.

In addition to the binary logical operators, the unary ! operator can be used to perform a logical negation of a single operand: it converts a zero operand into a one and a non-zero operand into a zero. By convention, D programmers use ! when working with integers that are meant to represent boolean values and == 0 when working with non-boolean integers, although the expressions are equivalent.

The logical operators may be applied to operands of integer or pointer types. The logical operators interpret pointer operands as unsigned integer values. As with all logical and relational operators in D, operands are true if they have a non-zero integer value and false if they have a zero integer value.

D provides the binary operators that are listed in the following table for manipulating individual bits inside of integer operands. These operators all have the same meaning as in ANSI C.

The binary & operator is used to clear bits from an integer operand. The binary | operator is used to set bits in an integer operand. The binary ^ operator returns one in each bit position, exactly where one of the corresponding operand bits is set.

The shift operators are used to move bits left or right in a given integer operand. Shifting left fills empty bit positions on the right-hand side of the result with zeroes. Shifting right using an unsigned integer operand fills empty bit positions on the left-hand side of the result with zeroes. Shifting right using a signed integer operand fills empty bit positions on the left-hand side with the value of the sign bit, also known as an arithmetic shift operation.

Shifting an integer value by a negative number of bits or by a number of bits larger than the number of bits in the left-hand operand itself produces an undefined result. The D compiler produces an error message if the compiler can detect this condition when you compile your D program.

In addition to the binary logical operators, the unary ~ operator may be used to perform a bitwise negation of a single operand: it converts each zero bit in the operand into a one bit, and each one bit in the operand into a zero bit.

D provides the binary assignment operators that are listed in the folloiwng table for modifying D variables. You can only modify D variables and arrays. Kernel data objects and constants may not be modified using the D assignment operators. The assignment operators have the same meaning as they do in ANSI C.

Aside from the assignment operator =, the other assignment operators are provided as shorthand for using the = operator with one of the other operators that were described earlier. For example, the expression x = x + 1 is equivalent to the expression x += 1, except that the expression x is evaluated one time. These assignment operators adhere to the same rules for operand types as the binary forms described earlier.

The result of any assignment operator is an expression equal to the new value of the left-hand expression. You can use the assignment operators or any of the operators described thus far in combination to form expressions of arbitrary complexity. You can use parentheses () to group terms in complex expressions.

x += 1; y = x;

y = ++x;

y = x; x -= 1;

y = x--;

You can use the increment and decrement operators to create new variables without declaring them. If a variable declaration is omitted and the increment or decrement operator is applied to a variable, the variable is implicitly declared to be of type int64_t.

The increment and decrement operators can be applied to integer or pointer variables. When applied to integer variables, the operators increment or decrement the corresponding value by one. When applied to pointer variables, the operators increment or decrement the pointer address by the size of the data type that is referenced by the pointer. Pointers and pointer arithmetic in D are discussed in Pointers and Scalar Arrays.

Although D does not provide support for if-then-else constructs, it does provide support for simple conditional expressions by using the ? and : operators. These operators enable a triplet of expressions to be associated, where the first expression is used to conditionally evaluate one of the other two.

For example, the following D statement could be used to set a variable x to one of two strings, depending on the value of i:

x = i == 0 ? "zero" : "non-zero";

In the previous example, the expression i == 0 is first evaluated to determine whether it is true or false. If the expression is true, the second expression is evaluated and its value is returned. If the expression is false, the third expression is evaluated and its value is returned.

As with any D operator, you can use multiple ?: operators in a single expression to create more complex expressions. For example, the following expression would take a char variable c containing one of the characters 0-9, a-f, or A-F, and return the value of this character when interpreted as a digit in a hexadecimal (base 16) integer:

hexval = (c >= '0' && c <= '9') ? c - '0' : (c >= 'a' && c <= 'f') ? c + 10 - 'a' : c + 10 - 'A';

To be evaluated for its truth value, the first expression that is used with ?: must be a pointer or integer. The second and third expressions can be of any compatible types. You may not construct a conditional expression where, for example, one path returns a string and another path returns an integer. The second and third expressions also may not invoke a tracing function such as trace or printf. If you want to conditionally trace data, use a predicate instead. See Predicate Examples for more information.

When expressions are constructed by using operands of different but compatible types, type conversions are performed to determine the type of the resulting expression. The D rules for type conversions are the same as the arithmetic conversion rules for integers in ANSI C. These rules are sometimes referred to as the usual arithmetic conversions.

A simple way to describe the conversion rules is as follows: each integer type is ranked in the order char, short, int, long, long long, with the corresponding unsigned types assigned a rank higher than its signed equivalent, but below the next integer type. When you construct an expression using two integer operands such as x + y and the operands are of different integer types, the operand type with the highest rank is used as the result type.

If a conversion is required, the operand with the lower rank is first promoted to the type of the higher rank. Promotion does not actually change the value of the operand: it simply extends the value to a larger container according to its sign. If an unsigned operand is promoted, the unused high-order bits of the resulting integer are filled with zeroes. If a signed operand is promoted, the unused high-order bits are filled by performing sign extension. If a signed type is converted to an unsigned type, the signed type is first sign-extended and then assigned the new, unsigned type that is determined by the conversion.

Integers and other types can also be explicitly cast from one type to another. In D, pointers and integers can be cast to any integer or pointer types, but not to other types. Rules for casting and promoting strings and character arrays are discussed in DTrace Support for Strings.

An integer or pointer cast is formed using an expression such as the following:

y = (int)x;

In this example, the destination type is enclosed in parentheses and used to prefix the source expression. Integers are cast to types of higher rank by performing promotion. Integers are cast to types of lower rank by zeroing the excess high-order bits of the integer.

Because D does not permit floating-point arithmetic, no floating-point operand conversion or casting is permitted and no rules for implicit floating-point conversion are defined.

Table 2-12 lists the D rules for operator precedence and associativity. These rules are somewhat complex, but they are necessary to provide precise compatibility with the ANSI C operator precedence rules. The following entries in the following table are in order from highest precedence to lowest precedence.

Several operators listed in the previous table that have not been discussed yet. These operators are described in subsequent chapters. The following table lists several miscellaneous operators that are provided by the D language.

The comma (,) operator that is listed in the table is for compatibility with the ANSI C comma operator. It can be used to evaluate a set of expressions in left-to-right order and return the value of the right most expression. This operator is provided strictly for compatibility with C and should generally not be used.

The () entry listed in the table of operator precedence represents a function call. For examples of calls to functions, such as printf and trace, see Output Formatting. A comma is also used in D to list arguments to functions and to form lists of associative array keys. Note that this comma is not the same as the comma operator and does not guarantee left-to-right evaluation. The D compiler provides no guarantee regarding the order of evaluation of arguments to a function or keys to an associative array. Note that you should be careful of using expressions with interacting side-effects, such as the pair of expressions i and i++, in these contexts.

The [] entry listed in the table of operator precedence represents an array or associative array reference. Examples of associative arrays are presented in Associative Arrays. A special kind of associative array, called an aggregation, is described in Aggregations. The [] operator can also be used to index into fixed-size C arrays as well. See Pointers and Scalar Arrays.

Scalar variables are used to represent individual, fixed-size data objects, such as integers and pointers. Scalar variables can also be used for fixed-size objects that are composed of one or more primitive or composite types. D provides the ability to create arrays of objects, as well as composite structures. DTrace also represents strings as fixed-size scalars by permitting them to grow to a predefined maximum length. Control over string length in your D program is discussed further in DTrace Support for Strings.

Scalar variables are created automatically the first time you assign a value to a previously undefined identifier in your D program. For example, to create a scalar variable named x of type int, you can simply assign it a value of type int in any probe clause, for example:

BEGIN
{
  x = 123;
}

Scalar variables that are created in this manner are global variables: each one is defined once and is visible in every clause of your D program. Any time that you reference the x identifier, you are referring to a single storage location associated with this variable.

Unlike ANSI C, D does not require explicit variable declarations. If you do want to declare a global variable and assign its name and type explicitly before using it, you can place a declaration outside of the probe clauses in your program, as shown in the following example:

int x; /* declare an integer x for later use */
BEGIN
{
  x = 123;
  ...
}

Explicit variable declarations are not necessary in most D programs, but sometimes are useful when you want to carefully control your variable types or when you want to begin your program with a set of declarations and comments documenting your program's variables and their meanings.

Unlike ANSI C declarations, D variable declarations may not assign initial values. You must use a BEGIN probe clause to assign any initial values. All global variable storage is filled with zeroes by DTrace before you first reference the variable.

The D language definition places no limit on the size and number of D variables. Limits are defined by the DTrace implementation and by the memory that is available on your system. The D compiler enforces any of the limitations that can be applied at the time you compile your program. See Options and Tunables for more about how to tune options related to program limits.

Associative arrays are used to represent collections of data elements that can be retrieved by specifying a name, which is called a key. D associative array keys are formed by a list of scalar expression values, called a tuple. You can think of the array tuple as an imaginary parameter list to a function that is called to retrieve the corresponding array value when you reference the array. Each D associative array has a fixed key signature consisting of a fixed number of tuple elements, where each element has a given, fixed type. You can define different key signatures for each array in your D program.

Associative arrays differ from normal, fixed-size arrays in that they have no predefined limit on the number of elements: the elements can be indexed by any tuple, as opposed to just using integers as keys, and the elements are not stored in preallocated, consecutive storage locations. Associative arrays are useful in situations where you would use a hash table or other simple dictionary data structure in a C, C++, or Java language program. Associative arrays provide the ability to create a dynamic history of events and state captured in your D program, which you can use to create more complex control flows.

To define an associative array, you write an assignment expression of the following form:

name [ key ] = expression ;

where name is any valid D identifier and key is a comma-separated list of one or more expressions.

For example, the following statement defines an associative array a with key signature [ int, string ] and stores the integer value 456 in a location named by the tuple [123, "hello"]:

a[123, "hello"] = 456;

The type of each object that is contained in the array is also fixed for all elements in a given array. Because it was first assigned by using the integer 456, every subsequent value that is stored in the array will also be of type int. You can use any of the assignment operators that are defined in Types, Operators, and Expressions to modify associative array elements, subject to the operand rules defined for each operator. The D compiler produces an appropriate error message if you attempt an incompatible assignment. You can use any type with an associative array key or value that can be used with a scalar variable.

You can reference an associative array by using any tuple that is compatible with the array key signature. The rules for tuple compatibility are similar to those for function calls and variable assignments. That is, the tuple must be of the same length and each type in the list of actual parameters and must be compatible with the corresponding type in the formal key signature. For example, for an associative array x that is defined as follows:

x[123ull] = 0;

The key signature is of type unsigned long long and the values are of type int. This array can also be referenced by using the expression x['a'] because the tuple consisting of the character constant 'a', of type int and length one, is compatible with the key signature unsigned long long, according to the arithmetic conversion rules. These rules are described in Type Conversions.

If you need to explicitly declare a D associative array before using it, you can create a declaration of the array name and key signature outside of the probe clauses in your program source code, for example:

int x[unsigned long long, char];
BEGIN
{
  x[123ull, 'a'] = 456;
}

Storage is allocated only for array elements with a nonzero value.

DTrace provides the ability to declare variable storage that is local to each operating system thread, as opposed to the global variables demonstrated earlier in this chapter. Thread-local variables are useful in situations where you want to enable a probe and mark every thread that fires the probe with some tag or other data. Creating a program to solve this problem is easy in D because thread-local variables share a common name in your D code, but refer to separate data storage that is associated with each thread.

Thread-local variables are referenced by applying the -> operator to the special identifier self, for example:

syscall::read:entry
{
  self->read = 1;
}

This D fragment example enables the probe on the read() system call and associates a thread-local variable named read with each thread that fires the probe. Similar to global variables, thread-local variables are created automatically on their first assignment and assume the type that is used on the right-hand side of the first assignment statement, which is int in this example.

Each time the self->read variable is referenced in your D program, the data object that is referenced is the one associated with the operating system thread that was executing when the corresponding DTrace probe fired. You can think of a thread-local variable as an associative array that is implicitly indexed by a tuple that describes the thread's identity in the system. A thread's identity is unique over the lifetime of the system: if the thread exits and the same operating system data structure is used to create a new thread, this thread does not reuse the same DTrace thread-local storage identity.

When you have defined a thread-local variable, you can reference it for any thread in the system, even if the variable in question has not been previously assigned for that particular thread. If a thread's copy of the thread-local variable has not yet been assigned, the data storage for the copy is defined to be filled with zeroes. As with associative array elements, underlying storage is not allocated for a thread-local variable until a non-zero value is assigned to it. Also, as with associative array elements, assigning zero to a thread-local variable causes DTrace to deallocate the underlying storage. Always assign zero to thread-local variables that are no longer in use. For other techniques to fine-tune the dynamic variable space from which thread-local variables are allocated, see Options and Tunables.

Thread-local variables of any type can be defined in your D program, including associative arrays. The following are some example thread-local variable definitions:

self->x = 123; /* integer value */

self->s = "hello"; /* string value */

self->a[123, 'a'] = 456; /* associative array */

Like any D variable, you do not need to explicitly declare thread-local variables prior to using them. If you want to create a declaration anyway, you can place one outside of your program clauses by pre-pending the keyword self, for example:

self int x; /* declare int x as a thread-local variable */ 
syscall::read:entry
{
  self->x = 123;
}

Thread-local variables are kept in a separate namespace from global variables so that you can reuse names. Remember that x and self->x are not the same variable if you overload names in your program.

The following example shows how to use thread-local variables. In an editor, type the following program and save it in a file named rtime.d:

syscall::read:entry
{
  self->t = timestamp;
}

syscall::read:return
/self->t != 0/
{
  printf("%d/%d spent %d nsecs in read()\n", pid, tid, timestamp - self->t);
  /* 
   * We are done with this thread-local variable; assign zero to it
   * to allow the DTrace runtime to reclaim the underlying storage.
   */ 
  self->t = 0;
}

Next, in your shell, start the program running. Wait a few seconds and you should begin to see some output. If no output appears, try running a few commands:

# dtrace -q -s rtime.d
3987/3987 spent 12786263 nsecs in read()
2183/2183 spent 13410 nsecs in read()
2183/2183 spent 12850 nsecs in read()
2183/2183 spent 10057 nsecs in read()
3583/3583 spent 14527 nsecs in read()
3583/3583 spent 12571 nsecs in read()
3583/3583 spent 9778 nsecs in read()
3583/3583 spent 9498 nsecs in read()
3583/3583 spent 9778 nsecs in read()
2183/2183 spent 13968 nsecs in read()
2183/2183 spent 72076 nsecs in read()
...
^C
#

The rtime.d program uses a thread-local variable that is named to capture a timestamp on entry to read() by any thread. Then, in the return clause, the program prints the amount of time spent in read() by subtracting self->t from the current timestamp. The built-in D variables pid and tid report the process ID and thread ID of the thread that is performing the read(). Because self->t is no longer needed after this information is reported, it is then assigned 0 to enable DTrace to reuse the underlying storage that is associated with t for the current thread.

Typically, you see many lines of output without doing anything because server processes and daemons are executing read() all the time behind the scenes. Try changing the second clause of rtime.d to use the execname variable to print out the name of the process performing a read(), for example:

printf("%s/%d spent %d nsecs in read()\n", execname, tid, timestamp - self->t);

If you find a process that is of particular interest, add a predicate to learn more about its read() behavior, as shown in the following example:

syscall::read:entry
/execname == "Xorg"/
{
  self->t = timestamp;
}

The value of a D variable can be accessed whenever a probe fires. Variables describes how variables could have a different scope. For a global variable, the same instance of the variable is accessed from every thread. For thread-local, the instance of the variable is thread-specific.

Meanwhile, for a clause-local variable, the instance of the variable is specific to that particular firing of the probe. Clause-local is the narrowest scope. When a probe fires on a CPU, the D script is executed in program order. Each clause-local variable is instantiated with an undefined value the first time it is used in the script. The same instance of the variable is used in all clauses until the D script has completed execution for that particular firing of the probe.

Clause-local variables can be referenced and assigned by prefixing with this->:

BEGIN
{
  this->secs = timestamp / 1000000000;
  ...
}

If you want to declare a clause-local variable explicitly before using it, you can do so by using the this keyword:

this int x;  /* an integer clause-local variable */
this char c; /* a character clause-local variable */

BEGIN
{
  this->x = 123;
  this->c = 'D';
}

Note that if your program contains multiple clauses for a single probe, any clause-local variables remain intact as the clauses are executed, as shown in the following example. Type the following source code and save it in a file named clause.d:

int me;       /* an integer global variable */
this int foo; /* an integer clause-local variable */

tick-1sec
{ 
  /*
   * Set foo to be 10 if and only if this is the first clause executed.
   */
  this->foo = (me % 3 == 0) ? 10 : this->foo;
  printf("Clause 1 is number %d; foo is %d\n", me++ % 3, this->foo++);
}

tick-1sec
{
  /*
   * Set foo to be 20 if and only if this is the first clause executed.
   */
  this->foo = (me % 3 == 0) ? 20 : this->foo;
  printf("Clause 2 is number %d; foo is %d\n", me++ % 3, this->foo++);
}

tick-1sec
{
  /*
   * Set foo to be 30 if and only if this is the first clause executed.
   */
  this->foo = (me % 3 == 0) ? 30 : this->foo;
  printf("Clause 3 is number %d; foo is %d\n", me++ % 3, this->foo++);
}

Because the clauses are always executed in program order, and because clause-local variables are persistent across different clauses that are enabling the same probe, running the preceding program always produces the same output:

# dtrace -q -s clause.d
Clause 1 is number 0; foo is 10
Clause 2 is number 1; foo is 11
Clause 3 is number 2; foo is 12
Clause 1 is number 0; foo is 10
Clause 2 is number 1; foo is 11
Clause 3 is number 2; foo is 12
Clause 1 is number 0; foo is 10
Clause 2 is number 1; foo is 11
Clause 3 is number 2; foo is 12
Clause 1 is number 0; foo is 10
Clause 2 is number 1; foo is 11
Clause 3 is number 2; foo is 12
^C

While clause-local variables are persistent across clauses that are enabling the same probe, their values are undefined in the first clause executed for a given probe. Be sure to assign each clause-local variable an appropriate value before using it or your program might have unexpected results.

Clause-local variables can be defined using any scalar variable type, but associative arrays may not be defined using clause-local scope. The scope of clause-local variables only applies to the corresponding variable data, not to the name and type identity defined for the variable. When a clause-local variable is defined, this name and type signature can be used in any subsequent D program clause.

You can use clause-local variables to accumulate intermediate results of calculations or as temporary copies of other variables. Access to a clause-local variable is much faster than access to an associative array. Therefore, if you need to reference an associative array value multiple times in the same D program clause, it is more efficient to copy it into a clause-local variable first and then reference the local variable repeatedly.

The following table provides a complete list of built-in D variables. All of these variables are scalar global variables.

Functions that are built into the D language such as trace are discussed in Actions and Subroutines.

The D language uses the back quote character (`) as a special scoping operator for accessing variables that are defined in the operating system and not in your D program. For more information, see External Symbols and Types.

The Linux operating system uses a technique called virtual memory to provide each user process with its own virtual view of the memory resources on your system. A virtual view of memory resources is referred to as an address space. An address space associates a range of address values, either [0 ... 0xffffffff] for a 32-bit address space or [0 ... 0xffffffffffffffff] for a 64-bit address space, with a set of translations that the operating system and hardware use to convert each virtual address to a corresponding physical memory location. Pointers in D are data objects that store an integer virtual address value and associate it with a D type that describes the format of the data stored at the corresponding memory location.

You can explicitly declare a D variable to be of pointer type by first specifying the type of the referenced data and then appending an asterisk (*) to the type name. Doing so indicates you want to declare a pointer type, as shown in the following statement:

int *p;

This statement declares a D global variable named p that is a pointer to an integer. The declaration means that p is a 64-bit integer with a value that is the address of another integer located somewhere in memory. Because the compiled form of your D code is executed at probe firing time inside the operating system kernel itself, D pointers are typically pointers associated with the kernel's address space. You can use the arch command to determine the number of bits that are used for pointers by the active operating system kernel.

If you want to create a pointer to a data object inside of the kernel, you can compute its address by using the & operator. For example, the operating system kernel source code declares an unsigned long max_pfn variable. You could trace the address of this variable by tracing the result of applying the & operator to the name of that object in D:

trace(&`max_pfn);

The * operator can be used to refer to the object addressed by the pointer, and acts as the inverse of the & operator. For example, the following two D code fragments are equivalent in meaning:

q = &`max_pfn; trace(*q);

trace(`max_pfn); 

In this example, the first fragment creates a D global variable pointer q. Because the max_pfn object is of type unsigned long, the type of &`max_pfn is unsigned long * (that is, pointer to unsigned long), implicitly setting the type of q. Tracing the value of *qfollows the pointer back to the data object max_pfn. This fragment is therefore the same as the second fragment, which directly traces the value of the data object by using its name.

If you are a C or C++ programmer, you might be a bit apprehensive after reading the previous section because you know that misuse of pointers in your programs can cause your programs to crash. DTrace, however, is a robust, safe environment for executing your D programs. Take note that these types of mistakes cannot cause program crashes. You might write a buggy D program, but invalid D pointer accesses do not cause DTrace or the operating system kernel to fail or crash in any way. Instead, the DTrace software detects any invalid pointer accesses, disables your instrumentation, and reports the problem back to you for debugging.

If you have previously programmed in the Java programming language, you are probably aware that the Java language does not support pointers for precisely the same reasons of safety. Pointers are needed in D because they are an intrinsic part of the operating system's implementation in C, but DTrace implements the same kind of safety mechanisms that are found in the Java programming language to prevent buggy programs from damaging themselves or each other. DTrace's error reporting is similar to the runtime environment for the Java programming language that detects a programming error and reports an exception.

To observe DTrace's error handling and reporting, you could write a deliberately bad D program using pointers. For example, in an editor, type the following D program and save it in a file named badptr.d:

BEGIN
{
  x = (int *)NULL;
  y = *x;
  trace(y);
}

The badptr.d program creates a D pointer named x that is a pointer to int. The program assigns this pointer the special invalid pointer value NULL, which is a built-in alias for address 0. By convention, address 0 is always defined as invalid so that NULL can be used as a sentinel value in C and D programs. The program uses a cast expression to convert NULL to be a pointer to an integer. The program then dereferences the pointer by using the expression *x, assigns the result to another variable y, and then attempts to trace y. When the D program is executed, DTrace detects an invalid pointer access when the statement y = *x is executed and reports the following error:

# dtrace -s badptr.d
dtrace: script 'badptr.d' matched 1 probe
dtrace: error on enabled probe ID 1 (ID 1: dtrace:::BEGIN):
invalid address (0x0) in action #2 at DIF offset 4
^C
#

Notice that the D program moves past the error and continues to execute; the system and all observed processes remain unperturbed. You can also add an ERROR probe to your script to handle D errors. For details about the DTrace error mechanism, see ERROR Probe.

In addition to the dynamic associative arrays that are described in Variables, D supports scalar arrays. Scalar arrays are a fixed-length group of consecutive memory locations that each store a value of the same type. Scalar arrays are accessed by referring to each location with an integer, starting from zero. Scalar arrays correspond directly in concept and syntax with arrays in C and C++. Scalar arrays are not used as frequently in D as associative arrays and their more advanced counterparts aggregations. You might, however, need to use scalar arrays to access existing operating system array data structures that are declared in C. Aggregations are described in Aggregations.

A D scalar array of 5 integers is declared by using the type int and suffixing the declaration with the number of elements in square brackets, for example:

int a[5];

Figure 2-* shows a visual representation of the array storage:

Scalar Array Representation

The D expression a[0] refers to the first array element, a[1] refers to the second, and so on. From a syntactic perspective, scalar arrays and associative arrays are very similar. You can declare an associative array of integers referenced by an integer key as follows:

int a[int];

You can also reference this array using the expression a[0]. But, from a storage and implementation perspective, the two arrays are very different. The static array a consists of five consecutive memory locations numbered from zero, and the index refers to an offset in the storage that is allocated for the array. On the other hand, an associative array has no predefined size and does not store elements in consecutive memory locations. In addition, associative array keys have no relationship to the corresponding value storage location. You can access associative array elements a[0] and a[-5] and only two words of storage are allocated by DTrace, and these might or might not be consecutive. Associative array keys are abstract names for the corresponding values and have no relationship to the value storage locations.

If you create an array using an initial assignment and use a single integer expression as the array index , for example, a[0] = 2, the D compiler always creates a new associative array, even though in this expression a could also be interpreted as an assignment to a scalar array. Scalar arrays must be predeclared in this situation so that the D compiler can recognize the definition of the array size and infer that the array is a scalar array.

Pointers and scalar arrays have a special relationship in D, just as they do in ANSI C. A scalar array is represented by a variable that is associated with the address of its first storage location. A pointer is also the address of a storage location with a defined type. Thus, D permits the use of the array [] index notation with both pointer variables and array variables. For example, the following two D fragments are equivalent in meaning:

p = &a[0]; trace(p[2]);

trace(a[2]); 

In the first fragment, the pointer p is assigned to the address of the first element in scalar array a by applying the & operator to the expression a[0]. The expression p[2] traces the value of the third array element (index 2). Because p now contains the same address associated with a, this expression yields the same value as a[2], shown in the second fragment. One consequence of this equivalence is that C and D permit you to access any index of any pointer or array. Array bounds checking is not performed for you by the compiler or the DTrace runtime environment. If you access memory beyond the end of a scalar array's predefined size, you either get an unexpected result or DTrace reports an invalid address error, as shown in the previous example. As always, you cannot damage DTrace itself or your operating system, but you do need to debug your D program.

The difference between pointers and arrays is that a pointer variable refers to a separate piece of storage that contains the integer address of some other storage. Whereas, an array variable names the array storage itself, not the location of an integer that in turn contains the location of the array. Figure 2-* illustrates this difference.

Pointer and Array Storage

This difference is manifested in the D syntax if you attempt to assign pointers and scalar arrays. If x and y are pointer variables, the expression x = y is legal; it copies the pointer address in y to the storage location that is named by x. If x and y are scalar array variables, the expression x = y is not legal. Arrays may not be assigned as a whole in D. However, an array variable or symbol name can be used in any context where a pointer is permitted. If p is a pointer and a is a scalar array, the statement p = a is permitted. This statement is equivalent to the statement p = &a[0].

Because pointers are just integers that are used as addresses of other objects in memory, D provides a set of features for performing arithmetic on pointers. However, pointer arithmetic is not identical to integer arithmetic. Pointer arithmetic implicitly adjusts the underlying address by multiplying or dividing the operands by the size of the type referenced by the pointer.

The following D fragment illustrates this property:

int *x;

BEGIN
{
  trace(x);
  trace(x + 1);
  trace(x + 2);
}

This fragment creates an integer pointer x and then traces its value, its value incremented by one, and its value incremented by two. If you create and execute this program, DTrace reports the integer values 0, 4, and 8.

Since x is a pointer to an int (size 4 bytes), incrementing x adds 4 to the underlying pointer value. This property is useful when using pointers to refer to consecutive storage locations such as arrays. For example, if x was assigned to the address of an array a, similar to what is shown in Figure 2-*, the expression x + 1 would be equivalent to the expression &a[1]. Similarly, the expression *(x + 1) would refer to the value a[1]. Pointer arithmetic is implemented by the D compiler whenever a pointer value is incremented by using the +, ++, or =+ operators. Pointer arithmetic is also applied as follows; when an integer is subtracted from a pointer on the left-hand side, when a pointer is subtracted from another pointer, or when the -- operator is applied to a pointer.

For example, the following D program would trace the result 2:

int *x, *y;
int a[5];

BEGIN
{
  x = &a[0];
  y = &a[2];
  trace(y - x);
}

Sometimes it is useful to represent or manipulate a generic pointer address in a D program without specifying the type of data referred to by the pointer. Generic pointers can be specified by using the type void *, where the keyword void represents the absence of specific type information, or by using the built-in type alias uintptr_t, which is aliased to an unsigned integer type of size that is appropriate for a pointer in the current data model. You may not apply pointer arithmetic to an object of type void *, and these pointers cannot be dereferenced without casting them to another type first. You can cast a pointer to the uintptr_t type when you need to perform integer arithmetic on the pointer value.

Pointers to void can be used in any context where a pointer to another data type is required, such as an associative array tuple expression or the right-hand side of an assignment statement. Similarly, a pointer to any data type can be used in a context where a pointer to void is required. To use a pointer to a non-void type in place of another non-void pointer type, an explicit cast is required. You must always use explicit casts to convert pointers to integer types, such as uintptr_t, or to convert these integers back to the appropriate pointer type.

Multi-dimensional scalar arrays are used infrequently in D, but are provided for compatibility with ANSI C and are for observing and accessing operating system data structures that are created by using this capability in C. A multi-dimensional array is declared as a consecutive series of scalar array sizes enclosed in square brackets [] following the base type. For example, to declare a fixed-size, two-dimensional rectangular array of integers of dimensions that is 12 rows by 34 columns, you would write the following declaration:

int a[12][34];

A multi-dimensional scalar array is accessed by using similar notation. For example, to access the value stored at row 0 and column 1, you would write the D expression as follows:

a[0][1]

Storage locations for multi-dimensional scalar array values are computed by multiplying the row number by the total number of columns declared and then adding the column number.

Be careful not to confuse the multi-dimensional array syntax with the D syntax for associative array accesses, that is, a[0][1], is not the same as a[0,1]). If you use an incompatible tuple with an associative array or attempt an associative array access of a scalar array, the D compiler reports an appropriate error message and refuses to compile your program.

The D compiler prohibits you from using the & operator to obtain pointers to DTrace objects such as associative arrays, built-in functions, and variables. You are prohibited from obtaining the address of these variables so that the DTrace runtime environment is free to relocate them as needed between probe firings . In this way, DTrace can more efficiently manage the memory required for your programs. If you create composite structures, it is possible to construct expressions that do retrieve the kernel address of your DTrace object storage. You should avoid creating such expressions in your D programs. If you need to use such an expression, do not rely on the address being the same across probe firings.

In ANSI C, pointers can also be used to perform indirect function calls or to perform assignments, such as placing an expression using the unary * dereference operator on the left-hand side of an assignment operator. In D, these types of expressions using pointers are not permitted. You may only assign values directly to D variables by specifying their name or by applying the array index operator [] to a D scalar or associative array. You may only call functions that are defined by the DTrace environment by name, as specified in Actions and Subroutines. Indirect function calls using pointers are not permitted in D.

A pointer is an address that provides a translation within some virtual address space to a piece of physical memory. DTrace executes your D programs within the address space of the operating system kernel itself. The Linux system manages many address spaces: one for the operating system kernel and one for each user process. Because each address space provides the illusion that it can access all of the memory on the system, the same virtual address pointer value can be reused across address spaces, but translate to different physical memory. Therefore, when writing D programs that use pointers, you must be aware of the address space corresponding to the pointers you intend to use.

For example, if you use the syscall provider to instrument entry to a system call that takes a pointer to an integer or array of integers as an argument, for example, pipe(), it would not be valid to dereference that pointer or array using the * or [] operators because the address in question is an address in the address space of the user process that performed the system call. Applying the * or [] operators to this address in D would result in kernel address space access, which would result in an invalid address error or in returning unexpected data to your D program, depending on whether the address happened to match a valid kernel address.

To access user-process memory from a DTrace probe, you must apply one of the copyin, copyinstr, or copyinto functions that are described in Actions and Subroutines to the user address space pointer. To avoid confusion, take care when writing your D programs to name and comment variables storing user addresses appropriately. You can also store user addresses as uintptr_t so that you do not accidentally compile D code that dereferences them. Techniques for using DTrace on user processes are described in User Process Tracing.

In DTrace, strings are represented as an array of characters terminated by a null byte (that is, a byte whose value is zero, usually written as '\0'). The visible part of the string is of variable length, depending on the location of the null byte, but DTrace stores each string in a fixed-size array so that each probe traces a consistent amount of data. Strings cannot exceed the length of the predefined string limit. However, the limit can be modified in your D program or on the dtrace command line by tuning the strsize option. See Options and Tunables for more information about tunable DTrace options. The default string limit is 256 bytes.

The D language provides an explicit string type rather than using the type char * to refer to strings. The string type is equivalent to char *, in that it is the address of a sequence of characters, but the D compiler and D functions such as trace provide enhanced capabilities when applied to expressions of type string. For example, the string type removes the ambiguity of type char * when you need to trace the actual bytes of a string.

In the following D statement, if s is of type char *, DTrace traces the value of the pointer s, which means it traces an integer address value:

trace(s);

In the following D statement, by the definition of the * operator, the D compiler dereferences the pointer s and traces the single character at that location:

trace(*s);

These behaviors enable you to manipulate character pointers that refer to either single characters, or to arrays of byte-sized integers that are not strings and do not end with a null byte.

In the next D statement, if s is of type string, the string type indicates to the D compiler that you want DTrace to trace a null terminated string of characters whose address is stored in the variable s:

trace(s);

You can also perform lexical comparison of expressions of type string. See String Comparison.

String constants are enclosed in pairs of double quotes ("") and are automatically assigned the type string by the D compiler. You can define string constants of any length, limited only by the amount of memory DTrace is permitted to consume on your system. The terminating null byte (\0) is added automatically by the D compiler to any string constants that you declare. The size of a string constant object is the number of bytes associated with the string, plus one additional byte for the terminating null byte.

A string constant may not contain a literal newline character. To create strings containing newlines, use the \n escape sequence instead of a literal newline. String constants can also contain any of the special character escape sequences that are defined for character constants. See Table 2-6.

Unlike the assignment of char * variables, strings are copied by value and not by reference. The string assignment operator = copies the actual bytes of the string from the source operand up to and including the null byte to the variable on the left-hand side, which must be of type string. You can create a new string variable by assigning it an expression of type string.

For example, the D statement:

s = "hello";

would create a new variable s of type string and copy the six bytes of the string "hello" into it (five printable characters, plus the null byte). String assignment is analogous to the C library function strcpy(), with the exception that if the source string exceeds the limit of the storage of the destination string, the resulting string is automatically truncated by a null byte at this limit.

You can also assign to a string variable an expression of a type that is compatible with strings. In this case, the D compiler automatically promotes the source expression to the string type and performs a string assignment. The D compiler permits any expression of type char * or of type char[n], that is, a scalar array of char of any size, to be promoted to a string.

Expressions of other types can be explicitly converted to type string by using a cast expression or by applying the special stringof operator, which are equivalent in the following meaning:

s = (string) expression;

s = stringof (expression);

The expression is interpreted as an address to the string.

The stringof operator binds very tightly to the operand on its right-hand side. Typically, parentheses are used to surround the expression for clarity. Although, they are not strictly necessary.

Any expression that is a scalar type, such as a pointer or integer, or a scalar array address may be converted to string. Expressions of other types such as void may not be converted to string. If you erroneously convert an invalid address to a string, the DTrace safety features prevents you from damaging the system or DTrace, but you might end up tracing a sequence of undecipherable characters.

D overloads the binary relational operators and permits them to be used for string comparisons, as well as integer comparisons. The relational operators perform string comparison whenever both operands are of type string or when one operand is of type string and the other operand can be promoted to type string. See String Assignment for a detailed description. See also Table 2-14, which lists the relational operators that can be used to compare strings.

As with integers, each operator evaluates to a value of type int, which is equal to one if the condition is true or zero if it is false.

The relational operators compare the two input strings byte-by-byte, similarly to the C library routine strcmp(). Each byte is compared by using its corresponding integer value in the ASCII character set until a null byte is read or the maximum string length is reached. See the ascii(7) manual page for more information. Some example D string comparisons and their results are shown in the following table.

The D keyword struct, short for structure, is used to introduce a new type that is composed of a group of other types. The new struct type can be used as the type for D variables and arrays, enabling you to define groups of related variables under a single name. D structs are the same as the corresponding construct in C and C++. If you have programmed in the Java programming language previously, think of a D struct as a class that contains only data members and no methods.

Suppose you want to create a more sophisticated system call tracing program in D that records a number of things about each read() and write() system call that is executed by your shell, for example, the elapsed time, number of calls, and the largest byte count passed as an argument.

You could write a D clause to record these properties in three separate associative arrays, as shown in the following example:

int maxbytes[string]; /* declare maxbytes */ 
syscall::read:entry, syscall::write:entry
/pid == 12345/
{
  ts[probefunc] = timestamp;
  calls[probefunc]++;
  maxbytes[probefunc] = arg2 > maxbytes[probefunc] ?
        arg2 : maxbytes[probefunc];
}

This clause, however, is inefficient because DTrace must create three separate associative arrays and store separate copies of the identical tuple values corresponding to probefunc for each one. Instead, you can conserve space and make your program easier to read and maintain by using a struct.

First, declare a new struct type at the top of the D program source file:

struct callinfo {
  uint64_t ts;       /* timestamp of last syscall entry */
  uint64_t elapsed;  /* total elapsed time in nanoseconds */
  uint64_t calls;    /* number of calls made */
  size_t maxbytes;   /* maximum byte count argument */
};

The struct keyword is followed by an optional identifier that is used to refer back to the new type, which is now known as struct callinfo. The struct members are then enclosed in a set of braces {} and the entire declaration is terminated by a semicolon (;). Each struct member is defined by using the same syntax as a D variable declaration, with the type of the member listed first followed by an identifier naming the member and another semicolon (;).

The struct declaration simply defines the new type. It does not create any variables or allocate any storage in DTrace. When declared, you can use struct callinfo as a type throughout the remainder of your D program. Each variable of type struct callinfo stores a copy of the four variables that are described by our structure template. The members are arranged in memory in order, according to the member list, with padding space introduced between members, as required for data object alignment purposes.

You can use the member identifier names to access the individual member values using the “.” operator by writing an expression of the following form:

      variable-name.member-name
    

The following example is an improved program that uses the new structure type. In a text editor, type the following D program and save it in a file named rwinfo.d:

struct callinfo {
  uint64_t ts; /* timestamp of last syscall entry */
  uint64_t elapsed; /* total elapsed time in nanoseconds */
  uint64_t calls; /* number of calls made */
  size_t maxbytes; /* maximum byte count argument */
};

struct callinfo i[string]; /* declare i as an associative array */

syscall::read:entry, syscall::write:entry
/pid == $1/
{
  i[probefunc].ts = timestamp;
  i[probefunc].calls++;
  i[probefunc].maxbytes = arg2 > i[probefunc].maxbytes ?
        arg2 : i[probefunc].maxbytes;
}

syscall::read:return, syscall::write:return
/i[probefunc].ts != 0 && pid == $1/
{
  i[probefunc].elapsed += timestamp - i[probefunc].ts;
}

END
{
  printf("       calls max bytes elapsed nsecs\n");
  printf("------ ----- --------- -------------\n");
  printf("  read %5d %9d %d\n",
  i["read"].calls, i["read"].maxbytes, i["read"].elapsed);
  printf(" write %5d %9d %d\n",
  i["write"].calls, i["write"].maxbytes, i["write"].elapsed);
}

When you have typed the program, run the dtrace -q -s rwinfo.d command, specifying one of your shell processes. Then, type a few commands in your shell. When you have finished typing the shell commands, type Ctrl-C to fire the END probe and print the results:

# dtrace -q -s rwinfo.d `pgrep -n bash`
 ^C
       calls max bytes elapsed nsecs
------ ----- --------- -------------
  read    25      1024 8775036488
 write    33        22 1859173

Referring to structs by using pointers is very common in C and D. You can use the operator -> to access struct members through a pointer. If struct s has a member m, and you have a pointer to this struct named sp, where sp is a variable of type struct s *, you can either use the * operator to first dereference the sp pointer to access the member:

struct s *sp;
(*sp).m

Or, you can use the -> operator as shorthand for this notation. The following two D fragments are equivalent if sp is a pointer to a struct:

(*sp).m 
sp->m

DTrace provides several built-in variables that are pointers to structs. For example, the pointer curpsinfo refers to struct psinfo and its content provides a snapshot of information about the state of the process associated with the thread that fired the current probe. The following table lists a few example expressions that use curpsinfo, including their types and their meanings.

For more information, see psinfo_t.

The next example uses the pr_fname member to identify a process of interest. In an editor, type the following script and save it in a file named procfs.d:

syscall::write:entry
/ curpsinfo->pr_fname == "date" /
{
  printf("%s run by UID %d\n", curpsinfo->pr_psargs, curpsinfo->pr_uid);
}

This clause uses the expression curpsinfo->pr_fname to access and match the command name so that the script selects the correct write() requests before tracing the arguments. Notice that by using operator == with a left-hand argument that is an array of char and a right-hand argument that is a string, the D compiler infers that the left-hand argument should be promoted to a string and a string comparison should be performed. Type the command dtrace -q -s procs.d in one shell and then type the date command several times in another shell. The output that is displayed by DTrace is similar to the following:

# dtrace -q -s procfs.d 
date  run by UID 500
/bin/date  run by UID 500
date -R  run by UID 500
...
^C
#

Complex data structures are used frequently in C programs, so the ability to describe and reference structs from D also provides a powerful capability for observing the inner workings of the Oracle Linux operating system kernel and its system interfaces.

Unions are another kind of composite type that is supported by ANSI C and D and are closely related to structs. A union is a composite type where a set of members of different types are defined and the member objects all occupy the same region of storage. A union is therefore an object of variant type, where only one member is valid at any given time, depending on how the union has been assigned. Typically, some other variable or piece of state is used to indicate which union member is currently valid. The size of a union is the size of its largest member. The memory alignment that is used for the union is the maximum alignment required by the union members.

You can determine the size in bytes of any D type or expression, including a struct or union, by using the sizeof operator. The sizeof operator can be applied either to an expression or to the name of a type surrounded by parentheses, as illustrated in the following two examples:

sizeof expression 
sizeof (type-name)

For example, the expression sizeof (uint64_t) would return the value 8, and the expression sizeof (callinfo.ts) would also return 8, if inserted into the source code of the previous example program. The formal return type of the sizeof operator is the type alias size_t, which is defined as an unsigned integer that is the same size as a pointer in the current data model and is used to represent byte counts. When the sizeof operator is applied to an expression, the expression is validated by the D compiler, but the resulting object size is computed at compile time and no code for the expression is generated. You can use sizeof anywhere an integer constant is required.

You can use the companion operator offsetof to determine the offset in bytes of a struct or union member from the start of the storage that is associated with any object of the struct or union type. The offsetof operator is used in an expression of the following form:

offsetof (type-name, member-name)

Here, type-name is the name of any struct or union type or type alias, and member-name is the identifier naming a member of that struct or union. Similar to sizeof, offsetof returns a size_t and you can use it anywhere in a D program that an integer constant can be used.

D also permits the definition of integer struct and union members of arbitrary numbers of bits, known as bit-fields. A bit-field is declared by specifying a signed or unsigned integer base type, a member name, and a suffix indicating the number of bits to be assigned for the field, as shown in the following example:

struct s 
{
  int a : 1;
  int b : 3;
  int c : 12;
};

The bit-field width is an integer constant that is separated from the member name by a trailing colon. The bit-field width must be positive and must be of a number of bits not larger than the width of the corresponding integer base type. Bit-fields that are larger than 64 bits may not be declared in D. D bit-fields provide compatibility with and access to the corresponding ANSI C capability. Bit-fields are typically used in situations when memory storage is at a premium or when a struct layout must match a hardware register layout.

A bit-field is a compiler construct that automates the layout of an integer and a set of masks to extract the member values. The same result can be achieved by simply defining the masks yourself and using the & operator. The C and D compilers attempt to pack bits as efficiently as possible, but they are free to do so in any order or fashion they desire. Therefore, bit-fields are not guaranteed to produce identical bit layouts across differing compilers or architectures. If you require stable bit layout, you should construct the bit masks yourself and extract the values by using the & operator.

A bit-field member is accessed by simply specifying its name in combination with the “.” or -> operators, like any other struct or union member. The bit-field is automatically promoted to the next largest integer type for use in any expressions. Because bit-field storage cannot be aligned on a byte boundary or be a round number of bytes in size, you may not apply the sizeof or offsetof operators to a bit-field member. The D compiler also prohibits you from taking the address of a bit-field member by using the & operator.

The typedef keyword is used to declare an identifier as an alias for an existing type. Like all D type declarations, typedef is used outside of probe clauses in a declaration of the following form:

typedef existing-type new-type ;

where existing-type is any type declaration and new-type is an identifier to be used as the alias for this type. For example, the D compiler uses the following declaration internally to create the uint8_t type alias:

typedef unsigned char uint8_t;

You can use type aliases anywhere that a normal type can be used, such as the type of a variable or associative array value or tuple member. You can also combine typedef with more elaborate declarations such as the definition of a new struct, as shown in the following example:

typedef struct foo {
  int x;
  int y;
} foo_t;

In the previous example, struct foo is defined using the same type as its alias, foo_t. Linux C system headers often use the suffix _t to denote a typedef alias.

Defining symbolic names for constants in a program eases readability and simplifies the process of maintaining the program in the future. One method is to define an enumeration, which associates a set of integers with a set of identifiers called enumerators that the compiler recognizes and replaces with the corresponding integer value. An enumeration is defined by using a declaration such as the following:

enum colors {
  RED,
  GREEN,
  BLUE
};

The first enumerator in the enumeration, RED, is assigned the value zero and each subsequent identifier is assigned the next integer value.

You can also specify an explicit integer value for any enumerator by suffixing it with an equal sign and an integer constant, as shown in the following example:

enum colors {
  RED = 7,
  GREEN = 9,
  BLUE
};

The enumerator BLUE is assigned the value 10 by the compiler because it has no value specified and the previous enumerator is set to 9. When an enumeration is defined, the enumerators can be used anywhere in a D program that an integer constant is used. In addition, the enumeration enum colors is also defined as a type that is equivalent to an int. The D compiler allows a variable of enum type to be used anywhere an int can be used and will allow any integer value to be assigned to a variable of enum type. You can also omit the enum name in the declaration, if the type name is not needed.

Enumerators are visible in all subsequent clauses and declarations in your program. Therefore, you cannot define the same enumerator identifier in more than one enumeration. However, you can define more than one enumerator with the same value in either the same or different enumerations. You may also assign integers that have no corresponding enumerator to a variable of the enumeration type.

The D enumeration syntax is the same as the corresponding syntax in ANSI C. D also provides access to enumerations that are defined in the operating system kernel and its loadable modules. Note that these enumerators are not globally visible in your D program. Kernel enumerators are only visible if you specify one as an argument in a comparison with an object of the corresponding enumeration type. This feature protects your D programs against inadvertent identifier name conflicts, with the large collection of enumerations that are defined in the operating system kernel.

The following example D program displays information about I/O requests. The program uses the enumerators B_READ and B_WRITE to differentiate between read and write operations:

io:::done,
io:::start,
io:::wait-done,
io:::wait-start
{
    printf("%8s %10s: %d %16s (%s size %d @ sect %d)\n",
    	args[1]->dev_statname, probename,  
    	timestamp, execname,  
    args[0]->b_flags & B_READ ? "R" : 
    args[0]->b_flags & B_WRITE ? "W" : "?",
    args[0]->b_bcount, args[0]->b_blkno);
}

D named constants can also be defined by using inline directives, which provide a more general means of creating identifiers that are replaced by predefined values or expressions during compilation. Inline directives are a more powerful form of lexical replacement than the #define directive provided by the C preprocessor because the replacement is assigned an actual type and is performed by using the compiled syntax tree and not simply a set of lexical tokens. An inline directive is specified by using a declaration of the following form:

inline type name = expression;

where type is a type declaration of an existing type, name is any valid D identifier that is not previously defined as an inline or global variable, and expression is any valid D expression. After the inline directive is processed, the D compiler substitutes the compiled form of expression for each subsequent instance of name in the program source.

For example, the following D program would trace the string "hello" and integer value 123:

inline string hello = "hello";
inline int number = 100 + 23;

BEGIN
{
  trace(hello);
  trace(number);
}

An inline name can be used anywhere a global variable of the corresponding type is used. If the inline expression can be evaluated to an integer or string constant at compile time, then the inline name can also be used in contexts that require constant expressions, such as scalar array dimensions.

The inline expression is validated for syntax errors as part of evaluating the directive. The expression result type must be compatible with the type that is defined by the inline, according to the same rules used for the D assignment operator (=). An inline expression may not reference the inline identifier itself: recursive definitions are not permitted.

The DTrace software packages install a number of D source files in the system directory /usr/lib64/dtrace/installed-version , which contain inline directives that you can use in your D programs.

For example, the signal.d library includes directives of the following form:

inline int SIGHUP = 1;
inline int SIGINT = 2;
inline int SIGQUIT = 3;
...

These inline definitions provide you with access to the current set of Oracle Linux signal names, as described in the sigaction(2) manual page. Similarly, the errno.d library contains inline directives for the C errno constants that are described in the errno(3) manual page.

By default, the D compiler includes all of the provided D library files automatically so that you can use these definitions in any D program.

In traditional languages such as ANSI C, type visibility is determined by whether a type is nested inside of a function or other declaration. Types declared at the outer scope of a C program are associated with a single global namespace and are visible throughout the entire program. Types that are defined in C header files are typically included in this outer scope. Unlike these languages, D provides access to types from multiple outer scopes.

D is a language that facilitates dynamic observability across multiple layers of a software stack, including the operating system kernel, an associated set of loadable kernel modules, and user processes that are running on the system. A single D program can instantiate probes to gather data from multiple kernel modules or other software entities that are compiled into independent binary objects. Therefore, more than one data type of the same name, perhaps with different definitions, might be present in the universe of types that are available to DTrace and the D compiler. To manage this situation, the D compiler associates each type with a namespace, which is identified by the containing program object. Types from a particular program object can be accessed by specifying the object name and the back quote (`) scoping operator in any type name.

For example, for a kernel module named foo that contains the following C type declaration:

typedef struct bar {
  int x;
} bar_t;

The types struct bar and bar_t could be accessed from D using the following type names:

struct foo`bar
foo`bar_t

The back quote operator can be used in any context where a type name is appropriate, including when specifying the type for D variable declarations or cast expressions in D probe clauses.

The D compiler also provides two special, built-in type namespaces that use the names C and D, respectively. The C type namespace is initially populated with the standard ANSI C intrinsic types, such as int. In addition, type definitions that are acquired by using the C preprocessor (cpp), by running the dtrace -C command, are processed by and added to the C scope. As a result, you can include C header files containing type declarations that are already visible in another type namespace without causing a compilation error.

The D type namespace is initially populated with the D type intrinsics, such as int and string, as well as the built-in D type aliases, such as uint64_t. Any new type declarations that appear in the D program source are automatically added to the D type namespace. If you create a complex type such as a struct in a D program consisting of member types from other namespaces, the member types are copied into the D namespace by the declaration.

When the D compiler encounters a type declaration that does not specify an explicit namespace using the back quote operator, the compiler searches the set of active type namespaces to find a match by using the specified type name. The C namespace is always searched first, followed by the D namespace. If the type name is not found in either the C or D namespace, the type namespaces of the active kernel modules are searched in load address order, which does not guarantee any ordering properties among the loadable modules. To avoid type name conflicts with other kernel modules, you should use the scoping operator when accessing types that are defined in loadable kernel modules.

The D compiler uses the compressed ANSI C debugging information that is provided with the core Linux kernel modules to automatically access the types that are associated with the operating system source code, without the need to access the corresponding C include files. Note that this symbolic debugging information might not be available for all kernel modules on your system. The D compiler reports an error if you attempt to access a type within the namespace of a module that lacks the compressed C debugging information that is intended for use with DTrace.