11.4 Calling DTrace from the Command Line

The software described in this documentation is either in Extended Support or Sustaining Support. See https://www.oracle.com/us/support/library/enterprise-linux-support-policies-069172.pdf for more information.
Oracle recommends that you upgrade the software described by this documentation as soon as possible.

11.4 Calling DTrace from the Command Line

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 exit 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 the commands have exited, and reports the exit status for each child process as it terminates. dtrace 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. You can 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 using the -C option. You can specify the -D option multiple times to the command.

-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['D-probe_clause']

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. dtrace indents entry probe reports and leaves return probe reports unindented. dtrace prefixes the output from function entry probe reports with -> and the output from function return probe reports with <-. dtrace 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. dtrace saves the DTrace probes that are specified in the program 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 given the same name as the source file for the D program, except with a .o extension instead of .s. 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, dtrace saves the header file to the specified path name. If you do not specify the -o option, the header file is given the same name as the source file for the D program, except with a .h extension instead of .d. 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 using the -C option.

-i probe_ID['D-probe_clause']

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 using the -C option. The specified directory is inserted at the head of the default directory list.

-l

List probes instead of enabling them. dtrace filters the list of probes based on the arguments to the -f, -i, -m, -n, -P, and -s options. If no options are specified, dtrace lists all 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['D-probe_clause']

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

-n [[[provider]:][module]:][function]]probe['D-probe_clause']

Specify a probe name (optionally specifying the provider, module, and function) that you want to trace or list. You can append an optional D-probe clause. 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 specified by its process ID, cache its symbol tables, and exit upon its completion. If you specify more than one -p option, dtrace exits when all the processes have exited, and reports the exit status for each process as it terminates. dtrace makes the first process ID specified available to D programs as the $target macro variable.

-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. dtrace suppresses informational messages, column headers, the CPU ID, the probe ID, and additional newlines. Only 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

Specifies a D program source file to be compiled by dtrace.

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 it 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 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 it generated for each D program to stderr.

-U name

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

-v

Set verbose mode. dtrace 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 supported by dtrace to stdout.

-w

Permit destructive actions by D programs. If you do not specify this option, dtrace 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 using the -C option.

-Xs

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

-Z

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