dtrace(1M) Utility

The [{{dtrace}}(1M)|http://docs.sun.com/doc/819-2240/dtrace-1m?a=view] command is a generic front-end to the DTrace facility. The command implements a simple interface to invoke the D language compiler, the ability to retrieve buffered trace data from the DTrace kernel facility, and a set of basic routines to format and print traced data. This chapter provides a complete reference for the {{dtrace}} command.

[Top|#top]
h2. {anchor:CHP-DTRACE1M-1} Description
The {{dtrace}} command provides a generic interface to all of the essential services provided by the DTrace facility, including:
* Options to list the set of probes and providers currently published by DTrace
* Options to enable probes directly using any of the probe description specifiers (provider, module, function, name)
* Options to run the D compiler and compile one or more D program files or programs written directly on the command-line
* Options to generate anonymous tracing programs (see [Chapter 36, Anonymous Tracing|Anonymous Tracing])
* Options to generate program stability reports (see [Chapter 39, Stability|Stability])
* Options to modify DTrace tracing and buffering behavior and enable additional D compiler features (see [Chapter 16, Options and Tunables|Options and Tunables])

{{dtrace}} can also be used to create D scripts by using it in a {{#!}} declaration to create an interpreter file (see [Chapter 15, Scripting|Scripting]). Finally, you can use {{dtrace}} to attempt to compile D programs and determine their properties without actually enabling any tracing using the \-e option, described below.

[Top|#top]
h2. {anchor:CHP-DTRACE1M-2} Options
The {{dtrace}} command accepts the following options:
\\
\\ {{dtrace}}\[\-32\| \-64\]\[\-aACeFGHlqSvVwZ\]\[\-b _bufsz_\]\[\-c _cmd_\]\[\-D _name_\[_=def_\]\]\[\-I _path_\]\[\-L _path_\]\[\-o _output_\]\[\-p _pid_\]\[\-s _script_\]\[\-U _name_\]\[\-x _arg_\[_=val_\]\]\[\-X\[a\| c\| s\| t\]\]\[\-P _provider_\[\[_predicate_\]_action_\]\]\[\-m \[\[_provider:_\]_module_\[\[_predicate_\]_action_\]\]\]\[\-f \[\[_provider:_\]_module:_\]_func_\[\[_predicate_\]_action_\]\]\[\-n \[\[\[_provider:_\]_module:_\]_func:_\]_name_\[\[_predicate_\]_action_\]\]\[\-i _probe-id_\[\[_predicate_\]_action_\]\]\\
\\
where _predicate_ is any D predicate enclosed in slashes {{/ /}} and _action_ is any D statement list enclosed in braces {{{ }}} according to the previously described D language syntax. If D program code is provided as an argument to the \-P, \-m, \-f, \-n, or \-i options this text must be appropriately quoted to avoid interpretation by the shell. The options are as follows:
{section}
{column:width=15%}
\-32, \-64
{column}
{column:width=85%}
The D compiler produces programs using the native data model of the operating system kernel. You can use the [{{isainfo}}(1)|http://docs.sun.com/doc/819-2239/isainfo-1?a=view] \-b command to determine the current operating system data model. If the \-32 option is specified, {{dtrace}} will force the D compiler to compile a D program using the 32-bit data model. If the \-64 option is specified, {{dtrace}} will force the D compiler to compile a D program using the 64-bit data model. These options are typically not required as {{dtrace}} selects the native data model as the default. The data model affects the sizes of integer types and other language properties. D programs compiled for either data model may be executed on both 32-bit and 64-bit kernels. The \-32 and \-64 options also determine the ELF file format (ELF32 or ELF64) produced by the \-G option.
{column}
{section}
{section}
{column:width=15%}
\-a
{column}
{column:width=85%}
Claim anonymous tracing state and display the traced data. You can combine the \-a option with the \-e option to force {{dtrace}} to exit immediately after consuming the anonymous tracing state rather than continuing to wait for new data. See [Chapter 36, Anonymous Tracing|Anonymous Tracing] for more information about anonymous tracing.
{column}
{section}
{section}
{column:width=15%}
\-A
{column}
{column:width=85%}
Generate [{{driver.conf}}(4)|http://docs.sun.com/doc/819-2251/driver.conf-4?a=view] directives for anonymous tracing. If the \-A option is specified, {{dtrace}} compiles any D programs specified using the \-s option or on the command-line and constructs a set of [{{dtrace}}(7D)|http://docs.sun.com/doc/819-2254/dtrace-7d?a=view] configuration file directives to enable the specified probes for anonymous tracing (see [Chapter 36, Anonymous Tracing|Anonymous Tracing]) and then exits. By default, {{dtrace}} attempts to store the directives to the file {{/kernel/drv/dtrace.conf}}. This behavior can be modified using the \-o option to specify an alternate output file.
{column}
{section}
{section}
{column:width=15%}
\-b
{column}
{column:width=85%}
Set principal trace buffer size. The trace buffer size can include any of the size suffixes {{k}}, {{m}}, {{g}}, or {{t}} as described in [Chapter 36, Anonymous Tracing|Anonymous Tracing]. If the buffer space cannot be allocated, {{dtrace}} attempts to reduce the buffer size or exit depending on the setting of the {{bufresize}} property.
{column}
{section}
{section}
{column:width=15%}
\-c
{column}
{column:width=85%}
Run the specified command _cmd_ and exit upon its completion. If more than one \-c option is present on the command line, {{dtrace}} exits when all commands have exited, reporting the exit status for each child process as it terminates. The process-ID of the first command is made available to any D programs specified on the command line or using the \-s option through the {{$target}} macro variable. Refer to [Chapter 15, Scripting|Scripting] for more information on macro variables.
{column}
{section}
{section}
{column:width=15%}
\-C
{column}
{column:width=85%}
Run the C preprocessor [{{cpp}}(1)|http://docs.sun.com/doc/819-2239/cpp-1?a=view] over D programs before compiling them. Options can be passed to the C preprocessor using the \-D, \-U, \-I, and \-H options. The degree of C standard conformance can be selected using the \-X option. Refer to the description of the \-X option for a description of the set of tokens defined by the D compiler when invoking the C preprocessor.
{column}
{section}
{section}
{column:width=15%}
\-D
{column}
{column:width=85%}
Define the specified _name_ when invoking [{{cpp}}(1)|http://docs.sun.com/doc/819-2239/cpp-1?a=view] (enabled using the \-C option). If an equals sign ({{=}}) and additional _value_ are specified, the name is assigned the corresponding value. This option passes the \-D option to each {{cpp}} invocation.
{column}
{section}
{section}
{column:width=15%}
\-e
{column}
{column:width=85%}
Exit after compiling any requests and consuming anonymous tracing state (\-a option) but prior to enabling any probes. This option can be combined with the \-a option to print anonymous tracing data and exit, or it can be combined with D compiler options to verify that the programs compile without actually executing them and enabling the corresponding instrumentation.
{column}
{section}
{section}
{column:width=15%}
\-f
{column}
{column:width=85%}
Specify function name to trace or list (\-l option). The corresponding argument can include any of the probe description forms _provider:module:function_, _module:function_, or _function_. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than _function_ are specified in the description, all probes with the corresponding _function_ are matched. The \-f argument can be suffixed with an optional D probe clause. More than one \-f option may be specified on the command-line at a time.
{column}
{section}
{section}
{column:width=15%}
\-F
{column}
{column:width=85%}
Coalesce trace output by identifying function entry and return. Function entry probe reports are indented and their output is prefixed with {{->}}. Function return probe reports are unindented and their output is prefixed with {{<-}}.
{column}
{section}
{section}
{column:width=15%}
\-G
{column}
{column:width=85%}
Generate an ELF file containing an embedded DTrace program. The DTrace probes specified in the program are saved inside of a relocatable ELF object that can be linked into another program. If the \-o option is present, the ELF file is saved using the pathname specified as the argument for this operand. If the \-o option is not present and the DTrace program is contained with a file whose name is _filename_{{.s}}, then the ELF file is saved using the name _file_{{.o}}; otherwise the ELF file is saved using the name {{d.out}}.
{column}
{section}
{section}
{column:width=15%}
\-H
{column}
{column:width=85%}
Print the pathnames of included files when invoking [{{cpp}}(1)|http://docs.sun.com/doc/819-2239/cpp-1?a=view] (enabled using the \-C option). This option passes the \-H option to each {{cpp}} invocation, causing it to display the list of pathnames, one per line, to {{stderr}}.
{column}
{section}
{section}
{column:width=15%}
\-i
{column}
{column:width=85%}
Specify probe identifier to trace or list (\-l option). Probe IDs are specified using decimal integers as shown by {{dtrace \-l}}. The \-i argument can be suffixed with an optional D probe clause. More than one \-i option may be specified on the command-line at a time.
{column}
{section}
{section}
{column:width=15%}
\-I
{column}
{column:width=85%}
Add the specified directory _path_ to the search path for {{#include}} files when invoking {{cpp(1)}} (enabled using the \-C option). This option passes the \-I option to each {{cpp}} invocation. The specified directory is inserted into the search path ahead of the default directory list.
{column}
{section}
{section}
{column:width=15%}
\-l
{column}
{column:width=85%}
List probes instead of enabling them. If the \-l option is specified, {{dtrace}} produces a report of the probes matching the descriptions given using the \-P, \-m, \-f, \-n, \-i, and \-s options. If none of these options are specified, all probes are listed.
{column}
{section}
{section}
{column:width=15%}
\-L
{column}
{column:width=85%}
Add the specified directory _path_ to the search path for DTrace libraries. DTrace libraries are used to contain common definitions that may be used when writing D programs. The specified _path_ is added after the default library search path.
{column}
{section}
{section}
{column:width=15%}
\-m
{column}
{column:width=85%}
Specify module name to trace or list (\-l option). The corresponding argument can include any of the probe description forms _provider:module_ or _module_. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than _module_ are specified in the description, all probes with a corresponding _module_ are matched. The \-m argument can be suffixed with an optional D probe clause. More than one \-m option may be specified on the command-line at a time.
{column}
{section}
{section}
{column:width=15%}
\-n
{column}
{column:width=85%}
Specify probe name to trace or list (\-l option). The corresponding argument can include any of the probe description forms _provider:module:function:name_, _module:function:name_, _function:name_, or _name_. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than _name_ are specified in the description, all probes with a corresponding _name_ are matched. The \-n argument can be suffixed with an optional D probe clause. More than one \-n option may be specified on the command-line at a time.
{column}
{section}
{section}
{column:width=15%}
\-o
{column}
{column:width=85%}
Specify the _output_ file for the \-A , \-G, and \-l options, or for the traced data. If the \-A option is present and \-o is not present, the default output file is {{/kernel/drv/dtrace.conf}}. If the \-G option is present and the \-s option's argument is of the form _filename_{{.d}} and \-o is not present, the default output file is _filename_{{.o}}; otherwise the default output file is {{d.out}}.
{column}
{section}
{section}
{column:width=15%}
\-p
{column}
{column:width=85%}
Grab the specified process-ID _pid_, cache its symbol tables, and exit upon its completion. If more than one \-p option is present on the command line, {{dtrace}} exits when all commands have exited, reporting the exit status for each process as it terminates. The first process-ID is made available to any D programs specified on the command line or using the \-s option through the {{$target}} macro variable. Refer to [Chapter 15, Scripting|Scripting] for more information on macro variables.
{column}
{section}
{section}
{column:width=15%}
\-P
{column}
{column:width=85%}
Specify provider name to trace or list (\-l option). The remaining probe description fields module, function, and name are left blank and match any probes regardless of the values in those fields. The \-P argument can be suffixed with an optional D probe clause. More than one \-P option may be specified on the command-line at a time.
{column}
{section}
{section}
{column:width=15%}
\-q
{column}
{column:width=85%}
Set quiet mode. {{dtrace}} will suppress messages such as the number of probes matched by the specified options and D programs and will not print column headers, the CPU ID, the probe ID, or insert newlines into the output. Only data traced and formatted by D program statements such as {{trace}} and {{printf}} will be displayed to {{stdout}}.
{column}
{section}
{section}
{column:width=15%}
\-s
{column}
{column:width=85%}
Compile the specified D program source file. If the \-e option is present, the program is compiled but no instrumentation is enabled. If the \-l option is present, the program is compiled and the set of probes matched by it is listed, but no instrumentation will be enabled. If neither \-e nor \-l are present, the instrumentation specified by the D program is enabled and tracing begins.
{column}
{section}
{section}
{column:width=15%}
\-S
{column}
{column:width=85%}
Show D compiler intermediate code. The D compiler will produce a report of the intermediate code generated for each D program to {{stderr}}.
{column}
{section}
{section}
{column:width=15%}
\-U
{column}
{column:width=85%}
Undefine the specified _name_ when invoking [{{cpp}}(1)|http://docs.sun.com/doc/819-2239/cpp-1?a=view] (enabled using the \-C option). This option passes the \-U option to each {{cpp}} invocation.
{column}
{section}
{section}
{column:width=15%}
\-v
{column}
{column:width=85%}
Set verbose mode. If the \-v option is specified, {{dtrace}} produces a program stability report showing the minimum interface stability and dependency level for the specified D programs. DTrace stability levels are explained in further detail in [Chapter 39, Stability|Stability].
{column}
{section}
{section}
{column:width=15%}
\-V
{column}
{column:width=85%}
Report the highest D programming interface version supported by {{dtrace}}. The version information is printed to {{stdout}} and the {{dtrace}} command exits. See [Chapter 41, Versioning|Versioning] for more information about DTrace versioning features.
{column}
{section}
{section}
{column:width=15%}
\-w
{column}
{column:width=85%}
Permit destructive actions in D programs specified using the \-s, \-P, \-m, \-f, \-n, or \-i options. If the \-w option is not specified, {{dtrace}} will not permit the compilation or enabling of a D program that contains destructive actions. Destructive actions are described in further detail in [Chapter 10, Actions and Subroutines|Actions and Subroutines].
{column}
{section}
{section}
{column:width=15%}
\-x
{column}
{column:width=85%}
Enable or modify a DTrace runtime option or D compiler option. The options are listed in [Chapter 16, Options and Tunables|Options and Tunables]. Boolean options are enabled by specifying their name. Options with values are set by separating the option name and value with an equals sign ({{=}}).
{column}
{section}
{section}
{column:width=15%}
\-X
{column}
{column:width=85%}
Specify the degree of conformance to the ISO C standard that should be selected when invoking [{{cpp}}(1)|http://docs.sun.com/doc/819-2239/cpp-1?a=view] (enabled using the \-C option). The \-X option argument affects the value and presence of the {{__STDC__}} macro depending upon the value of the argument letter:\\
\\ {{a}} (default)
{quote}
ISO C plus K&R compatibility extensions, with semantic changes required by ISO C. This mode is the default mode if \-X is not specified. The predefined macro {{__STDC__}} has a value of 0 when {{cpp}} is invoked in conjunction with the \-Xa option.\\
{quote}
\\ {{c}} (conformance)
{quote}
Strictly conformant ISO C, without K&R C compatibility extensions. The predefined macro {{__STDC__}} has a value of 1 when {{cpp}} is invoked in conjunction with the \-Xc option.\\
{quote}
\\ {{s}} (K&R C)
{quote}
K&R C only. The macro {{__STDC__}} is not defined when {{cpp}} is invoked in conjunction with the \-Xs option.\\
{quote}
\\ {{t}} (transition)
{quote}
ISO C plus K&R C compatibility extensions, without semantic changes required by ISO C. The predefined macro {{__STDC__}} has a value of 0 when {{cpp}} is invoked in conjunction with the \-Xt option.
{quote}
Because the \-X option affects only how the D compiler invokes the C preprocessor, the \-Xa and \-Xt options are equivalent from the perspective of D. Both options are provided to ease re-use of settings from a C build environment.\\
\\Regardless of the \-X mode, the following additional C preprocessor definitions are always specified and valid in all modes:
* {{__sun}}
* {{__unix}}
* {{__SVR4}}
* {{__sparc}} (on SPARC® systems only)
* {{__sparcv9}} (on SPARC® systems only when 64–bit programs are compiled)
* {{__i386}} (on x86 systems only when 32–bit programs are compiled)
* {{__amd64}} (on x86 systems only when 64–bit programs are compiled)
* {{__}}_`uname -s`_{{_}}_`uname -r`_ (for example, {{__SunOS_5_10}})
* {{__SUNW_D=1}}
* {{__SUNW_D_VERSION=0x}}_MMmmmuuu_ (where _MM_ is the Major release value in hexadecimal, _mmm_ is the Minor release value in hexadecimal, and _uuu_ is the Micro release value in hexadecimal; see [Chapter 41, Versioning|Versioning] for more information about DTrace versioning)

{column}
{section}
{section}
{column:width=15%}
\-Z
{column}
{column:width=85%}
Permit probe descriptions that match zero probes. If the \-Z option is not specified, {{dtrace}} will report an error and exit if any probe descriptions specified in D program files (\-s option) or on the command-line (\-P, \-m, \-f, \-n, or \-i options) contain descriptions that do not match any known probes.
{column}
{section}

[Top|#top]
h2. {anchor:CHP-DTRACE1M-3} Operands
Zero or more additional arguments may be specified on the {{dtrace}} command line to define a set of macro variables ({{$1}}, {{$2}}, and so on) to be used in any D programs specified using the \-s option or on the command-line. The use of macro variables is described further in [Chapter 15, Scripting|Scripting].

[Top|#top]
h2. {anchor:CHP-DTRACE1M-4} Exit Status
The following exit values are returned by the {{dtrace}} utility:
{section}
{column:width=15%}
0
{column}
{column:width=85%}
The specified requests were completed successfully. For D program requests, the 0 exit status indicates that programs were successfully compiled, probes were successfully enabled, or anonymous state was successfully retrieved. {{dtrace}} returns 0 even if the specified tracing requests encounted errors or drops.
{column}
{section}
{section}
{column:width=15%}
1
{column}
{column:width=85%}
A fatal error occurred. For D program requests, the 1 exit status indicates that program compilation failed or that the specified request could not be satisfied.
{column}
{section}
{section}
{column:width=15%}
2
{column}
{column:width=85%}
Invalid command-line options or arguments were specified.
{column}
{section}
{excerpt:hidden=true}Converted by tech dogg's sgml2wiki on Tue 20 Nov 2007 at 9:23:27 PM{excerpt}