1. DTrace Reference Guide
  2. dtrace Command Reference

8 dtrace Command Reference

The dtrace command is a generic front-end utility for the DTrace facility. The command implements a simple interface to invoke the D language compiler. The dtrace command also has the ability to retrieve buffered trace data from the DTrace kernel facility and a includes a set of basic routines to format and print traced data. This chapter provides a complete reference for the dtrace command.

dtrace Command Description

The dtrace command provides a generic interface to all of the essential services that are provided by the DTrace facility, including options to do the following:

  • List the set of probes and providers currently published by DTrace.

  • Enable probes directly by using any of the probe description specifiers (provider, module, function, name).

  • Run the D compiler and compile one or more D program files or programs written directly on the command line.

  • Generate program stability reports. See DTrace Stability Features.

  • Modify DTrace tracing and buffering behavior and enable additional D compiler features. See Options and Tunables.

You can also use the dtrace command to create D scripts by using the command in a #! declaration to create an interpreter file. See Scripting. Finally, you can use the -e option to dtrace to compile D programs and determine their properties without actually enabling any tracing.

dtrace Command Options

The dtrace command accepts the following options: 

dtrace [-CeFGhHlqSvVwZ]
[-b bufsz] [-c command] [-D name[=value]] [-I pathname] [-L pathname]
[-o pathname] [-p PID] [-s source_pathname]
[-U name] [-x option[=value]] [-X a|c|s|t]
[-P provider[[predicate]action]]
[-m [[provider:]module[[predicate]action]]]
[-f [[provider:]module:]function[[predicate]action]]
[-n [[[provider:]module:]function:]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 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:

-b bufsize

Set the principal trace buffer size, which can include any of the size suffixes k (kilobyte), m (megabyte), g (gigabyte), or t (terabyte). If the buffer space cannot be allocated, dtrace attempts to reduce the buffer size or exits, depending on the setting of the bufresize property.

-c command

Run the specified command and exit upon its completion. If you specify more than one -c option, dtrace exits when all of the commands have exited, and then reports the exit status for each child process as it terminates. The dtrace command makes the process ID of the first command available to D programs as the $target macro variable.

-C

Run the C preprocessor (cpp) on D programs before compiling them. You can pass options to the C preprocessor by using the -D, -H, -I, and -U options. Use the -X option to select the degree of conformance with the C standard.

-D name[=value]

Define the specified macro name and optional value when invoking cpp with the -C option. You can specify the -D option to the command multiple times.

-e

Exit after compiling any requests and before enabling any probes. You can combine this option with the -D option to verify that your D programs compile without executing them or enabling the corresponding instrumentation.

-f [[provider:]module:] function [[predicate]action]

Specify a function  (optionally specifying the provider and module) that you want to trace or list. You can append an optional D-probe clause. You can specify the -f option multiple times to the command.

-F

Reduce trace output by combining the output for function and system call entry and return points. The dtrace command indents entry probe reports and leaves return probe reports unindented. The command prefixes the output from function entry probe reports with -> and the output from function return probe reports with <-. The dtrace command prefixes the output from system call entry probe reports with => and the output from system call return probe reports with <=.

-G

Generate an ELF file that contains an embedded D program. The command saves the DTrace probes that are specified in the program by using a relocatable ELF object that can be linked with another program. If you specify the -o option, dtrace saves the  ELF file to the specified path name. If you do not specify the -o option, the ELF file is assigned the same name as the source file for the D program, except with a .o extension rather than the .s extension. Otherwise, the ELF file is saved with the name d.out.

-h

Create a header file based on probe definitions in the file that is specified as the argument to the -s option. If you specify the -o option, the command saves the header file to the specified path name. If you do not specify the -o option, the header file is assigned the same name as the source file for the D program, except with a .h extension rather than a .d extension. You should amend the source file of the program to be traced so that it includes this header file.

-H

Print the path names of included files on stderr when you invoke cpp with the -C option.

-i probe_ID [[predicate]action]

Specify a probe identifier that you want to trace or list. You must specify the probe ID as a decimal integer, as displayed by dtrace -l. You can append an optional D-probe clause. You can specify the -i option multiple times to the command.

-I pathname

Add the specified directory path to the search path for #include files when you invoke cpp with the -C option. The specified directory is inserted at the head of the default directory list.

-l

List probes instead of enabling them. The dtrace command filters the list of probes based on the arguments to the -f, -i, -m, -n, -P, and -s options. If no options are specified, the command lists all of the probes.

-L pathname

Add the specified directory path to the end of the library search path. Use this option to specify the path to DTrace libraries, which contain common definitions for D programs.

-m [[provider:]module [[predicate]action]]

Specify a module that you want to trace or list. You can optionally specify the provider. You can append an optional D-probe clause. You can specify the -m option multiple times to the command.

-n [[[provider:]module:] function:]name [[predicate]action]

Specify a probe name that you want to trace or list. You can append an optional D-probe clause. You can optionally specify the provider, module, and function. You can specify the -n option multiple times to the command.

-o pathname

Specify the output file for the -G and -l options, or for traced data.

-p PID

Grab a process by specifying its process ID, cache its symbol tables, and exit upon its completion. If you specify more than one -p option,  dtrace exits when all of the processes have exited. In addition, the command reports the exit status for each process as it terminates. The dtrace command makes the first process ID that is specified available to D programs  as the macro variable $target.

-P provider['D-probe_clause']

Specify a provider that you want to trace or list. You can append an optional D-probe clause. You can specify the -P option multiple times to the command.

-q

Set quiet mode. The dtrace command suppresses informational messages, column headers, CPU ID, probe ID, and additional newlines. Only the data that is traced and formatted by the printa(), printf(), and trace() D program statements is displayed on stdout. This option is equivalent to specifying #pragma D option quiet in a D program.

-s source_pathname

Specify the name of a D program source file to be compiled by the dtrace command, as follows:

  • If you specify the -h option, dtrace creates a header file using the probe definitions in the file.

  • If you specify the -G option, dtrace generates a relocatable ELF object that can be linked with another program.

  • If you specify the -e option, dtrace compiles the program, but does not enable any instrumentation.

  • If you specify the -l option, dtrace compiles the program and lists the set of matching probes, but it does not enable any instrumentation.

  • If you do not specify an option, dtrace enables the instrumentation that is specified by the D program and begins tracing.

-S

Show the D compiler intermediate code. The D compiler writes a report of the intermediate code that was generated for each D program to stderr.

-U name

Undefine the specified name when invoking cpp with the -C option. You can specify the -U option multiple times to the command.

-v

Set verbose mode. The dtrace command produces a program stability report showing the minimum interface stability and dependency level for any specified D programs.

-V

Write the highest D programming interface version that is supported by dtrace to stdout.

The combination -vV adds other version information, such as the version of the user-space binaries from the dtrace-utils package.

-w

Permit destructive actions by D programs. Note that if you do not specify this option, the command does not compile or enable a D program that contains destructive actions. This option is equivalent to specifying #pragma D option destructive in a D program.

-x option[=value]

Enable or modify a DTrace runtime option or D compiler option.

-X a|c|t

Include the option -std=gnu99 (conformance with 1999 C standard including GNU extensions) when invoking cpp with the -C option.

-Xs

Include the option -traditional-cpp (conformance with K&R C) when invoking cpp with the -C option.

Regardless of the -X mode, the following additional C preprocessor definitions are always specified and valid in all modes:

  • __linux

  • __unix

  • __SVR4

  • __`uname -s` (for example, __Linux)

  • __SUNW_D=1

  • __SUNW_D_64

  • __SUNW_D_VERSION=0xMMmmmuuu

    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 DTrace Versioning for more information about DTrace versioning.

-Z

Permit probe descriptions that do not match any probes. If you do not specify this option, the dtrace command reports an error and exits if a probe description does not match a known probe.

dtrace Command Operands

You can specify zero or more additional arguments on the dtrace command line to define a set of macro variables, such as $1, $2, and so on, to be used in any D programs that are specified with the -s option or on the command line. The use of macro variables is described further in Scripting.

dtrace Command Exit Status

The following exit values are returned by the dtrace command:

0

Indicates that 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 an anonymous state was successfully retrieved. The dtrace command returns 0 even if the specified tracing requests encountered errors or drops.

1

Indicates that 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.

2

Indicates that invalid command-line options or arguments were specified.