9.3 Macro Arguments

The D compiler also provides a set of macro variables corresponding to any additional argument operands that are specified as part of the dtrace command invocation. These macro arguments are accessed by using the built-in names $0, for the name of the D program file or dtrace command, $1, for the first additional operand, $2 for the second operand, and so on. If you use the -s option, $0 expands to the value of the name of the input file that is used with this option. For D programs that are specified on the command line, $0 expands to the value of argv[0], which is used to execute the dtrace command itself.

Macro arguments can expand to integers, identifiers, or strings, depending on the form of the corresponding text. As with all macro variables, macro arguments can be used anywhere integer, identifier, and string tokens can be used in a D program.

All of the following examples could form valid D expressions assuming appropriate macro argument values:

execname == $1  /* with a string macro argument */

x += $1         /* with an integer macro argument */

trace(x->$1)    /* with an identifier macro argument */

Macro arguments can be used to create DTrace interpreter files that act like real Linux commands and use information that is specified by a user or by another tool to modify their behavior.

For example, the following D interpreter file traces write() system calls that are executed by a particular process ID and saved in a file named tracewrite:

#!/usr/sbin/dtrace -s 
/pid == $1/

If you make this interpreter file executable, you can specify the value of $1 by using an additional command-line argument to your interpreter file, for example:

# chmod a+rx ./tracewrite
# ./tracewrite 12345

The resulting command invocation counts each write() system call that is executed by the process ID 12345.

If your D program references a macro argument that is not provided on the command line, an appropriate error message is printed and your program fails to compile, as shown in the following example:

# ./tracewrite
dtrace: failed to compile script ./tracewrite: line 4: 
  macro argument $1 is not defined

D programs can reference unspecified macro arguments if you set the defaultargs option. If defaultargs is set, unspecified arguments have the value 0. See Chapter 10, Options and Tunables for more information about D compiler options. The D compiler also produces an error message if additional arguments that are not referenced by your D program are specified on the command line.

The macro argument values must match the form of an integer, identifier, or string. If the argument does not match any of these forms, the D compiler reports an appropriate error message. When specifying string macro arguments to a DTrace interpreter file, you should surround the argument in an extra pair of single quotes to avoid interpretation of the double quotes and string contents by your shell:

# ./foo '"a string argument"'

If you want your D macro arguments to be interpreted as string tokens, even if they match the form of an integer or identifier, prefix the macro variable or argument name with two leading dollar signs, for example, $$1, which forces the D compiler to interpret the argument value as if it were a string surrounded by double quotes. All of the usual D string escape sequences, per Table 2.6, “Character Escape Sequences”, are expanded inside of any string macro arguments, regardless of whether they are referenced by using the $arg or $$arg form of the macro. If the defaultargs option is set, unspecified arguments that are referenced with the $$arg form have the value of the empty string ("").