JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Solaris Dynamic Tracing Guide
search filter icon
search icon

Document Information


1.  Introduction

2.  Types, Operators, and Expressions

3.  Variables

4.  D Program Structure

5.  Pointers and Arrays

6.  Strings

7.  Structs and Unions

8.  Type and Constant Definitions

9.  Aggregations

10.  Actions and Subroutines

11.  Buffers and Buffering

12.  Output Formatting

13.  Speculative Tracing

14.  dtrace(1M) Utility

15.  Scripting

Interpreter Files

Macro Variables

Macro Arguments

Target Process ID

16.  Options and Tunables

17.  dtrace Provider

18.  lockstat Provider

19.  profile Provider

20.  fbt Provider

21.  syscall Provider

22.  sdt Provider

23.  sysinfo Provider

24.  vminfo Provider

25.  proc Provider

26.  sched Provider

27.  io Provider

28.  mib Provider

29.  fpuinfo Provider

30.  pid Provider

31.  plockstat Provider

32.  fasttrap Provider

33.  User Process Tracing

34.  Statically Defined Tracing for User Applications

35.  Security

36.  Anonymous Tracing

37.  Postmortem Tracing

38.  Performance Considerations

39.  Stability

40.  Translators

41.  Versioning



Macro Arguments

The D compiler also provides a set of macro variables corresponding to any additional argument operands specified as part of the dtrace command invocation. These macro arguments are accessed using the built-in names $0 for 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 dtrace -s option, $0 expands to the value of the name of the input file used with this option. For D programs specified on the command-line, $0 expands to the value of argv[0] used to exec dtrace 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 Solaris commands and use information specified by a user or by another tool to modify their behavior. For example, the following D interpreter file traces write(2) system calls executed by a particular process ID:

#!/usr/sbin/dtrace -s

/pid == $1/

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

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

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

If your D program references a macro argument that is not provided on the command-line, an appropriate error message will be printed and your program will fail to compile:

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

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

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 will report an appropriate error message. When specifying string macro arguments to a DTrace interpreter file, 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) to force the D compiler to interpret the argument value as if it were a string surrounded by double quotes. All the usual D string escape sequences (see Table 2-5) are expanded inside of any string macro arguments, regardless of whether they are referenced 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 ("").