8.2 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 Chapter 18, 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.