4 .\" The contents of this file are subject to the terms of the
5 .\" Common Development and Distribution License (the "License").
6 .\" You may not use this file except in compliance with the License.
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 .\" or http://www.opensolaris.org/os/licensing.
10 .\" See the License for the specific language governing permissions
11 .\" and limitations under the License.
13 .\" When distributing Covered Code, include this CDDL HEADER in each
14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 .\" If applicable, add the following below this CDDL HEADER, with the
16 .\" fields enclosed by brackets "[]" replaced with your own identifying
17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
20 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
29 .Nd dynamic tracing compiler and tracing utility
33 .Op Fl aACeFGhHlqSvVwZ
36 .Op Fl D Ar name Op Ns = Ns value
42 .Op Fl x Ar arg Op Ns = Ns value
43 .Op Fl X Cm a | c | s | t
45 .Op Fl P Ar provider Oo Oo Ar predicate Oc Ar action Oc
46 .Op Fl m Oo Ar provider : Oc Ar module Oo Oo Ar predicate Oc Ar action Oc
47 .Op Fl f Oo Oo Ar provider : Oc Ar module : Oc Ar function Oo Oo Ar predicate \
49 .Op Fl n Oo Oo Oo Ar provider : Oc Ar module : Oc Ar function : Oc Ar name \
50 Oo Oo Ar predicate Oc Ar action Oc
51 .Op Fl i Ar probe-id Oo Oo Ar predicate Oc Ar action Oc
53 DTrace is a comprehensive dynamic tracing framework ported from Solaris.
54 DTrace provides a powerful infrastructure that permits administrators,
55 developers, and service personnel to concisely answer arbitrary questions about
56 the behavior of the operating system and user programs.
60 command provides a generic interface to the essential services provided by the
61 DTrace facility, including:
62 .Bl -bullet -offset indent
64 Options that list the set of probes and providers currently published by DTrace
66 Options that enable probes directly using any of the probe description
67 specifiers (provider, module, function, name)
69 Options that run the D compiler and compile one or more D program files or
70 programs written directly on the command line
72 Options that generate anonymous tracing programs
74 Options that generate program stability reports
76 Options that modify DTrace tracing and buffering behavior and enable
77 additional D compiler features
82 to create D scripts by using it in a shebang declaration to create an
86 to attempt to compile D programs and determine their properties without
87 actually enabling traces using the
91 The arguments accepted by the
98 options can include an optional D language
100 enclosed in slashes and an optional D language
102 statement list enclosed in braces.
103 D program code specified on the command line must be appropriately quoted to
104 avoid interpretation of meta-characters by the shell.
106 The following options are supported:
107 .Bl -tag -width indent
109 The D compiler produces programs using the native data model of the operating
115 forces the D compiler to compile a D program using the 32-bit data model.
120 forces the D compiler to compile a D program using the 64-bit data model.
121 These options are typically not required as
123 selects the native data model as the default.
124 The data model affects the sizes of integer types and other language properties.
125 D programs compiled for either data model can be executed on both 32-bit and
131 options also determine the
133 file format (ELF32 or ELF64) produced by the
137 Claim anonymous tracing state and display the traced data.
144 to exit immediately after consuming the anonymous tracing state rather than
145 continuing to wait for new data.
147 Generate directives for anonymous tracing and write them to
148 .Pa /boot/dtrace.dof .
149 This option constructs a set of dtrace configuration file directives to enable
150 the specified probes for anonymous tracing and then exits.
153 attempts to store the directives to the file
154 .Pa /boot/dtrace.dof .
155 This behavior can be modified using the
157 option to specify an alternate output file.
159 Set the principal trace buffer size to
161 The trace buffer size can include any of the size suffixes k, m, g, or t.
162 If the buffer space cannot be allocated,
164 attempts to reduce the buffer size or exit depending on the setting of the
167 Run the specified command
169 and exit upon its completion.
172 option is present on the command line,
174 exits when all commands have exited, reporting the exit status for each child
175 process as it terminates.
176 The process ID of the first command is made available to any D programs
177 specified on the command line or using the
183 Run the C preprocessor
185 over D programs before compiling them.
186 You can pass options to the C preprocessor using the
193 You can select the degree of C standard conformance if you use the
196 For a description of the set of tokens defined by the D compiler when invoking
197 the C preprocessor, see
199 .It Fl D Ar name Op Ns = Ns value
207 If you specify an additional
209 the name is assigned the corresponding value.
210 This option passes the
216 Exit after compiling any requests and consuming anonymous tracing state
218 option) but prior to enabling any probes.
219 You can combine this option with the
221 option to print anonymous tracing data and exit.
222 You can also combine this option with D compiler options.
223 This combination verifies that the programs compile without actually executing
224 them and enabling the corresponding instrumentation.
225 .It Fl f Oo Oo Ar provider : Oc Ar module : Oc Ar function Oo Oo Ar predicate \
227 Specify function name to trace or list
230 The corresponding argument can include any of the probe description forms
231 .Ar provider:module:function ,
232 .Ar module:function ,
235 Unspecified probe description fields are left blank and match any probes
236 regardless of the values in those fields.
237 If no qualifiers other than
239 are specified in the description, all probes with the corresponding
244 argument can be suffixed with an optional D probe clause.
245 You can specify more than one
247 option on the command line at a time.
249 Coalesce trace output by identifying function entry and return.
250 Function entry probe reports are indented and their output is prefixed with
252 Function return probe reports are unindented and their output is prefixed with
254 System call entry probe reports are indented and their output is prefixed with
256 System call return probe reports are unindented and their output is prefixed
260 Generate an ELF file containing an embedded DTrace program.
261 The DTrace probes specified in the program are saved inside of a relocatable ELF
262 object which can be linked into another program.
265 option is present, the ELF file is saved using the pathname specified as the
266 argument for this operand.
269 option is not present and the DTrace program is contained with a file whose name
272 then the ELF file is saved using the name
274 Otherwise the ELF file is saved using the name d.out.
276 Generate a header file containing macros that correspond to probes in the
277 specified provider definitions.
278 This option should be used to generate a header file that is included by other
279 source files for later use with the
284 option is present, the header file is saved using the pathname specified as the
285 argument for that option.
288 option is not present and the DTrace program is contained within a file whose
291 then the header file is saved using the name
294 Print the pathnames of included files when invoking
299 This option passes the
303 invocation, causing it to display the list of pathnames, one for each line, to
305 .It Fl i Ar probe-id Op Oo Ar predicate Oc Ar action
306 Specify probe identifier
311 You can specify probe IDs using decimal integers as shown by `dtrace -l`.
314 argument can be suffixed with an optional D probe clause.
315 You can specify more than one
319 Add the specified directory
321 to the search path for #include files when invoking
326 This option passes the
333 is inserted into the search path ahead of the default directory list.
335 List probes instead of enabling them.
340 produces a report of the probes matching the descriptions given using the
341 .Fl P , m , f , n , i ,
345 If none of these options are specified, this option lists all probes.
347 Add the specified directory
349 to the search path for DTrace libraries.
350 DTrace libraries are used to contain common definitions that can be used when
354 is added after the default library search path.
355 .It Fl m Oo Ar provider : Oc Ar module Oo Oo Ar predicate Oc Ar action Oc
356 Specify module name to trace or list
359 The corresponding argument can include any of the probe description forms
363 Unspecified probe description fields are left blank and match any probes
364 regardless of the values in those fields.
365 If no qualifiers other than
367 are specified in the description, all probes with a corresponding
372 argument can be suffixed with an optional D probe clause.
375 option can be specified on the command line at a time.
376 .It Fl n Oo Oo Oo Ar provider : Oc Ar module : Oc Ar function : Oc Ar name \
377 Oo Oo Ar predicate Oc Ar action Oc
378 Specify probe name to trace or list
381 The corresponding argument can include any of the probe description forms
382 .Ar provider:module:function:name , module:function:name , function:name ,
385 Unspecified probe description fields are left blank and match any probes
386 regardless of the values in those fields.
387 If no qualifiers other than
389 are specified in the description, all probes with a corresponding
394 argument can be suffixed with an optional D probe clause.
397 option can be specified on the command line at a time.
405 options, or for the traced data itself.
408 option is present and
410 is not present, the default output file is
411 .Pa /boot/dtrace.dof .
414 option is present and the
416 option's argument is of the form
420 is not present, the default output file is
422 Otherwise the default output file is
425 Grab the specified process-ID
427 cache its symbol tables, and exit upon its completion.
430 option is present on the command line,
432 exits when all commands have exited, reporting the exit status for each process
434 The first process-ID is made available to any D programs specified on the
435 command line or using the
440 .It Fl P Ar provider Oo Oo Ar predicate Oc Ar action Oc
441 Specify provider name to trace or list
444 The remaining probe description fields module, function, and name are left
445 blank and match any probes regardless of the values in those fields.
448 argument can be suffixed with an optional D probe clause.
449 You can specify more than one
451 option on the command line at a time.
455 suppresses messages such as the number of probes matched by the specified
456 options and D programs and does not print column headers, the CPU ID, the probe
457 ID, or insert newlines into the output.
458 Only data traced and formatted by D program statements such as
462 is displayed to standard output.
464 Compile the specified D program source file.
467 option is present, the program is compiled but instrumentation is not enabled.
470 option is present, the program is compiled and the set of probes matched by it
471 is listed, but instrumentation is not enabled.
476 are present, the instrumentation specified by the D program is enabled and
479 Show D compiler intermediate code.
480 The D compiler produces a report of the intermediate code generated for each D
481 program to standard error.
483 Undefine the specified
490 This option passes the
501 produces a program stability report showing the minimum interface stability and
502 dependency level for the specified D programs.
504 Report the highest D programming interface version supported by
506 The version information is printed to standard output and the
510 Permit destructive actions in D programs specified using the
511 .Fl s , P , m , f , n ,
517 option is not specified,
519 does not permit the compilation or enabling of a D program that contains
521 .It Fl x Ar arg Op Ns = Ns value
522 Enable or modify a DTrace runtime option or D compiler option.
523 Boolean options are enabled by specifying their name.
524 Options with values are set by separating the option name and value with an
526 .It Fl X Cm a | c | s | t
527 Specify the degree of conformance to the ISO C standard that should be selected
535 option argument affects the value and presence of the __STDC__ macro depending
536 upon the value of the argument letter.
540 option supports the following arguments:
541 .Bl -tag -width indent
544 ISO C plus K&R compatibility extensions, with semantic changes required by ISO
546 This is the default mode if
549 The predefined macro __STDC__ has a value of 0 when
551 is invoked in conjunction with the
556 Strictly conformant ISO C, without K&R C compatibility extensions.
557 The predefined macro __STDC__ has a value of 1 when
559 is invoked in conjunction with the
564 The macro __STDC__ is not defined when
566 is invoked in conjunction with the
571 ISO C plus K&R C compatibility extensions, without semantic changes required by
573 The predefined macro __STDC__ has a value of 0 when
575 is invoked in conjunction with the
582 option only affects how the D compiler invokes the C preprocessor, the
586 options are equivalent from the perspective of D and both are provided only to
587 ease re-use of settings from a C build environment.
591 mode, the following additional C preprocessor definitions are always specified
592 and valid in all modes:
593 .Bl -bullet -offset indent
601 __sparc (on SPARC systems only)
603 __sparcv9 (on SPARC systems only when 64-bit programs are compiled)
605 __i386 (on x86 systems only when 32-bit programs are compiled)
607 __amd64 (on x86 systems only when 64-bit programs are compiled)
609 __`uname -s`_`uname -r` (for example,
610 .Ql FreeBSD_9.2-RELEASE .
614 .No __SUNW_D_VERSION=0x Ns Ar MMmmmuuu
618 is the major release value in hexadecimal,
620 is the minor release value in hexadecimal, and
622 is the micro release value in hexadecimal.
625 Permit probe descriptions that match zero probes.
628 option is not specified,
630 reports an error and exits if any probe descriptions specified in D program
633 option) or on the command line
634 .Fl ( P , m , f , n ,
637 options) contain descriptions that do not match any known probes.
640 You can specify zero or more additional arguments on the
642 command line to define a set of macro variables and so forth).
643 The additional arguments can be used in D programs specified using the
645 option or on the command line.
647 .Bl -tag -width /boot/dtrace.dof -compact
648 .It Pa /boot/dtrace.dof
649 File for anonymous tracing directives.
652 The following exit statuses are returned:
653 .Bl -tag -width indent
655 Successful completion.
657 For D program requests, an exit status of 0 indicates that programs were
658 successfully compiled, probes were successfully enabled, or anonymous state
659 was successfully retrieved.
661 returns 0 even if the specified tracing requests encountered errors or drops.
665 For D program requests, an exit status of 1 indicates that program compilation
666 failed or that the specified request could not be satisfied.
668 Invalid command line options or arguments were specified.
676 .%T Solaris Dynamic Tracing Guide