home | help 
dtrace(1M)		 System Administration Commands 	      dtrace(1M)

NAME
     dtrace - DTrace dynamic tracing compiler and tracing utility

SYNOPSIS
     dtrace [-32 | -64] [-aACeFGHhlqSvVwZ] [-b bufsz] [-c cmd]
	 [-D name [=value]] [-I path] [-L path] [-o output]
	 [-s script] [-U name] [-x arg [=val]]
	 [-X a | c | s | t] [-p pid]
	 [-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]]

DESCRIPTION
     DTrace is a comprehensive dynamic tracing framework for the Solaris Operat-
     ing System. DTrace provides a powerful infrastructure that permits adminis-
     trators,  developers,  and  service personnel to concisely answer arbitrary
     questions about the behavior of the operating system and user programs.

     The Solaris Dynamic Tracing Guide describes how to use DTrace  to	observe,
     debug, and tune system behavior. Refer to this book for a detailed descrip-
     tion  of DTrace features, including the bundled DTrace observability tools,
     instrumentation providers, and the D programming language.

     The dtrace command provides a generic interface to the  essential	services
     provided by the DTrace facility, including:

	 o	Options that list the set of probes and providers currently pub-
		lished by DTrace

	 o	Options  that  enable probes directly using any of the probe de-
		scription specifiers (provider, module, function, name)

	 o	Options that run the D compiler and compile one or more  D  pro-
		gram files or programs written directly on the command line

	 o	Options that generate anonymous tracing programs

	 o	Options that generate program stability reports

	 o	Options  that  modify  DTrace tracing and buffering behavior and
		enable additional D compiler features

     You can use dtrace to create D scripts by using it in a #!  declaration  to
     create an interpreter file. You can also use dtrace to attempt to compile D
     programs  and  determine their properties without actually enabling tracing
     using the -e option. See OPTIONS. See the Solaris Dynamic Tracing Guide for
     detailed examples of how to use the dtrace utility to perform these tasks.

OPTIONS
     The arguments accepted by the -P, -m, -f, -n, and -i options can include an
     optional D language predicate enclosed in slashes // and  optional  D  lan-
     guage action statement list enclosed in braces {}. D program code specified
     on  the command line must be appropriately quoted to avoid intepretation of
     meta-characters by the shell.

     The following options are supported:

     -32 | -64

	 The D compiler produces programs using the native data model of the op-
	 erating system kernel. You can use the isainfo -b command to  determine
	 the  current  operating system data model.  If the -32 option is speci-
	 fied, dtrace forces the D compiler to compile a  D  program  using  the
	 32-bit  data model. If the -64 option is specified, dtrace forces the D
	 compiler to compile a D program using the 64-bit data model. These  op-
	 tions	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	can  be  executed on both 32-bit and 64-bit kernels. The -32 and
	 -64 options also determine the ELF file format (ELF32	or  ELF64)  pro-
	 duced by the -G option.

     -a

	 Claim anonymous tracing state and display the traced data. You can com-
	 bine  the  -a option with the -e option to force dtrace to exit immedi-
	 ately after consuming the anonymous tracing state rather than	continu-
	 ing  to  wait	for  new data. See the Solaris Dynamic Tracing Guide for
	 more information about anonymous tracing.

     -A

	 Generate driver.conf(4) directives for anonymous tracing.  This  option
	 constructs  a set of dtrace(7D) configuration file directives to enable
	 the specified probes for anonymous tracing and then exits. By	default,
	 dtrace   attempts   to   store   the	directives  to	the  file  /ker-
	 nel/drv/dtrace.conf. You can modify this behavior if you use the -o op-
	 tion to specify an alternate output file.

     -b bufsz

	 Set principal trace buffer size (bufsz). The trace buffer size can  in-
	 clude any of the size suffixes k, m, g, or t.	If the buffer space can-
	 not be allocated, dtrace attempts to reduce the buffer size or exit de-
	 pending on the setting of the bufresize property.

     -c cmd

	 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 the Solaris  Dy-
	 namic Tracing Guide for more information on macro variables.

     -C

	 Run  the  C  preprocessor cpp(1) over D programs before compiling them.
	 You can pass options to the C preprocessor using the -D, -U, -I, and -H
	 options. You can select the degree of C standard conformance if you use
	 the -X option. For a description of the set of tokens defined by the  D
	 compiler when invoking the C preprocessor, see -X.

     -D name [=value]

	 Define  name when invoking cpp(1) (enabled using the -C option). If you
	 specify the equals sign (=) and additional value, the name is	assigned
	 the  corresponding  value. This option passes the -D option to each cpp
	 invocation.

     -e

	 Exit after compiling any requests and consuming anonymous tracing state
	 (-a option) but prior to enabling any probes. You can combine this  op-
	 tion  with  the -a option to print anonymous tracing data and exit. You
	 can also combine this option with D compiler options. This  combination
	 verifies  that the programs compile without actually executing them and
	 enabling the corresponding instrumentation.

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

	 Specify function name to trace or list (-l option).  The  corresponding
	 argument  can	include any of the probe description forms provider:mod-
	 ule:function, module:function, or function.  Unspecified probe descrip-
	 tion fields are left blank and match any probes regardless of the  val-
	 ues 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.  You can specify more than one -f option on the command line at
	 a time.

     -F

	 Coalesce trace output by identifying function entry and  return.  Func-
	 tion entry probe reports are indented and their output is prefixed with
	 ->.  Function	return	probe reports are unindented and their output is
	 prefixed with <-. System call entry  probe  reports  are  indented  and
	 their	output is prefixed with =>. System call return probe reports are
	 unindented and their output is prefixed with <=.

     -G

	 Generate an ELF file containing an embedded DTrace program. The  DTrace
	 probes  specified  in the program are saved inside of a relocatable ELF
	 object which can be linked into another program. If the  -o  option  is
	 present,  the ELF file is saved using the pathname specified as the ar-
	 gument for this operand. If the -o option is not present and the DTrace
	 program is contained with a file whose name is filename.d, then the ELF
	 file is saved using the name filename.o.  Otherwise  the  ELF	file  is
	 saved using the name d.out.

     -H

	 Print the pathnames of included files when invoking cpp(1) (enabled us-
	 ing  the -C option). This option passes the -H option to each cpp invo-
	 cation, causing it to display the list of pathnames, one for each line,
	 to stderr.

     -h

	 Generate a header file containing macros that correspond to  probes  in
	 the  specified provider definitions. This option should be used to gen-
	 erate a header file that is included by other source  files  for  later
	 use with the -G option. If the -o option is present, the header file is
	 saved	using the pathname specified as the argument for that option. If
	 the -o option is not present and the DTrace program is contained with a
	 file whose name is filename.d, then the header file is saved using  the
	 name filename.h.

     -i probe-id[[predicate] action]

	 Specify  probe  identifier (probe-id) to trace or list (-l option). You
	 can specify probe IDs using decimal integers as shown by dtrace -l. The
	 -i argument can be suffixed with an optional D probe  clause.	You  can
	 specify more than one -i option at a time.

     -I path

	 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 path is inserted
	 into the search path ahead of the default directory list.

     -L path

	 Add the specified directory path to the  search  path	for  DTrace  li-
	 braries.  DTrace  libraries are used to contain common definitions that
	 can be used when writing D programs. The specified path is added  after
	 the default library search path.

     -l

	 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, this option lists all probes.

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

	 Specify module name to trace or list (-l option). The corresponding ar-
	 gument 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 quali-
	 fiers other than module are specified in the  description,  all  probes
	 with  a  corresponding  module are matched. The -m argument can be suf-
	 fixed with an optional D probe clause. More than one -m option  can  be
	 specified on the command line at a time.

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

	 Specify  probe name to trace or list (-l option). The corresponding ar-
	 gument can include any of the	probe  description  forms  provider:mod-
	 ule:function:name,  module:function:name,  function:name, or name.  Un-
	 specified 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 can be specified on  the  command
	 line at a time.

     -o output

	 Specify  the  output  file  for the -A , -G, and -l options, or for the
	 traced data itself. 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.

     -p pid

	 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  com-
	 mand  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 the Solaris
	 Dynamic Tracing Guide for more information on macro variables.

     -P provider [[predicate] action]

	 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. You can  specify  more
	 than one -P option on the command line at a time.

     -q

	 Set quiet mode. dtrace suppresses messages such as the number of probes
	 matched by the specified options and D programs and does not print col-
	 umn headers, the CPU ID, the probe ID, or insert newlines into the out-
	 put.  Only  data  traced  and formatted by D program statements such as
	 trace() and printf() is displayed to stdout.

     -s

	 Compile the specified D program  source  file.  If  the  -e  option  is
	 present, the program is compiled but instrumentation is not enabled. If
	 the -l option is present, the program is compiled and the set of probes
	 matched by it is listed, but instrumentation is not enabled. If none of
	 -e,  -l,  -G, or -A are present, the instrumentation specified by the D
	 program is enabled and tracing begins.

     -S

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

     -U name

	 Undefine  the specified name when invoking cpp(1) (enabled using the -C
	 option). This option passes the -U option to each cpp invocation.

     -v

	 Set verbose mode. If the -v option is specified, dtrace produces a pro-
	 gram stability report showing the minimum interface stability	and  de-
	 pendency  level  for  the specified D programs. DTrace stability levels
	 are explained in further detail in the Solaris Dynamic Tracing Guide.

     -V

	 Report the highest D programming interface version supported by dtrace.
	 The version information is printed to stdout and the dtrace command ex-
	 its. Refer to the Solaris Dynamic Tracing Guide  for  more  information
	 about DTrace versioning features.

     -w

	 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
	 does  not  permit  the compilation or enabling of a D program that con-
	 tains destructive actions.

     -x arg [=val]

	 Enable or modify a DTrace runtime option or D compiler option. The list
	 of options is found in the Solaris Dynamic Tracing Guide.  Boolean  op-
	 tions are enabled by specifying their name. Options with values are set
	 by separating the option name and value with an equals sign (=).

     -X a | c | s | t

	 Specify  the degree of conformance to the ISO C standard that should be
	 selected when invoking cpp(1) (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.

	 The -X option supports the following arguments:

	 a    Default. ISO C plus K&R compatibility  extensions,  with	semantic
	      changes  required  by ISO C. This 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.

	 c    Conformance. Strictly conformant ISO C, without K&R C  compatibil-
	      ity  extensions.	The  predefined  macro __STDC__ has a value of 1
	      when cpp is invoked in conjunction with the -Xc option.

	 s    K&R C only. The macro __STDC__ is not defined when cpp is  invoked
	      in conjunction with the -Xs option.

	 t    Transition. ISO C plus K&R C compatibility extensions, without se-
	      mantic  changes  required  by ISO C. The predefined macro __STDC__
	      has a value of 0 when cpp is invoked in conjunction with	the  -Xt
	      option.

	 As  the  -X  option  only affects how the D compiler invokes the C pre-
	 processor, the -Xa and -Xt options are equivalent from the  perspective
	 of  D	and  both  are provided only to ease re-use of settings from a C
	 build environment.

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

	     o	    __sun

	     o	    __unix

	     o	    __SVR4

	     o	    __sparc (on SPARC systems only)

	     o	    __sparcv9 (on SPARC systems only when  64-bit  programs  are
		    compiled)

	     o	    __i386  (on  x86  systems only when 32-bit programs are com-
		    piled)

	     o	    __amd64 (on x86 systems only when 64-bit programs  are  com-
		    piled)

	     o	    __`uname -s`_`uname -r` (for example, __SunOS_5_10)

	     o	    __SUNW_D=1

	     o	    __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. Refer to the	Solaris  Dynamic
		    Tracing Guide for more information about DTrace versioning.

     -Z

	 Permit  probe	descriptions that match zero probes. If the -Z option is
	 not specified, dtrace reports an error and exits if any probe	descrip-
	 tions	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.

OPERANDS
     You  can  specify	zero  or more additional arguments on the dtrace command
     line to define a set of macro variables ($1, $2, and so forth).  The  addi-
     tional arguments can be used in D programs specified using the -s option or
     on the command line. The use of macro variables is described further in the
     Solaris Dynamic Tracing Guide.

EXIT STATUS
     The following exit values are returned:

     0	  Successful completion.

	  For  D  program  requests, an exit status of 0 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 encountered errors or drops.

     1	  An error occurred.

	  For D program requests, an exit status of  1	indicates  that  program
	  compilation  failed  or that the specified request could not be satis-
	  fied.

     2	  Invalid command line options or arguments were specified.

ATTRIBUTES
     See attributes(5) for descriptions of the following attributes:

     +------------------------------+-----------------------------+
     |	     ATTRIBUTE TYPE	    |	   ATTRIBUTE VALUE	  |
     +------------------------------+-----------------------------+
     | Availability		    |SUNWdtrc			  |
     +------------------------------+-----------------------------+
     | Interface Stability	    |See below. 		  |
     +------------------------------+-----------------------------+

     The command-line syntax is Committed. The human-readable output  is  Uncom-
     mitted.

SEE ALSO
     cpp(1),   isainfo(1),   libdtrace(3LIB),	driver.conf(4),   attributes(5),
     dtrace(7D)

     Solaris Dynamic Tracing Guide

SunOS 5.11			   5 Sep 2006			      dtrace(1M)
home | help