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
       Operating System. DTrace provides a powerful infrastructure  that  per-
       mits  administrators,  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  description  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 ser-
       vices provided by the DTrace facility, including:

           o      Options that list the set of probes and providers  currently
                  published by DTrace

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

           o      Options that run the D compiler and compile one  or  more  D
                  program  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 language action statement list enclosed in braces {}. D pro-
       gram 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
           operating  system  kernel.  You  can  use the isainfo -b command to
           determine the current operating system  data  model.   If  the  -32
           option  is  specified,  dtrace forces the D compiler to compile a D
           program using the 32-bit data model. If the -64  option  is  speci-
           fied, dtrace forces the D compiler to compile a D program using the
           64-bit data model. These options  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) produced by the -G option.


       -a

           Claim  anonymous tracing state and display the traced data. You can
           combine the -a option with the -e option to force  dtrace  to  exit
           immediately after consuming the anonymous tracing state rather than
           continuing 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  /kernel/drv/dtrace.conf.  You can modify this behavior if you
           use the -o option to specify an alternate output file.


       -b bufsz

           Set principal trace buffer size (bufsz). The trace buffer size  can
           include  any  of  the  size  suffixes k, m, g, or t.  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 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  Dynamic  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 confor-
           mance  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 option 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  actu-
           ally executing them and enabling the corresponding instrumentation.


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

           Specify function name to trace or list (-l option). The correspond-
           ing  argument  can  include  any  of  the  probe  description forms
           provider:module:function, module:function, or  function.   Unspeci-
           fied  probe  description fields are left blank and match any probes
           regardless of the values 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  suf-
           fixed  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.
           Function  entry probe reports are indented and their output is pre-
           fixed 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 relo-
           catable 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 argument 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  file-
           name.o.  Otherwise the ELF file is saved using the name d.out.


       -H

           Print the pathnames of included files when invoking cpp(1) (enabled
           using the -C option). This option passes the -H option to each  cpp
           invocation,  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 generate 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 direc-
           tory list.


       -L path

           Add the specified directory path to  the  search  path  for  DTrace
           libraries.  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 speci-
           fied, dtrace produces a report of the probes matching the  descrip-
           tions  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
           argument   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 qualifiers other than module  are  specified  in  the
           description,  all  probes  with a corresponding module are matched.
           The -m argument can be suffixed 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
           argument   can   include   any   of  the  probe  description  forms
           provider:module:function:name, module:function:name, function:name,
           or  name.   Unspecified 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  file-
           name.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  command  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  column headers, the CPU ID, the probe ID, or insert newlines
           into the output. Only data traced and formatted by D program state-
           ments 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 instru-
           mentation 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 invoca-
           tion.


       -v

           Set verbose mode. If the -v option is specified, dtrace produces  a
           program  stability  report  showing the minimum interface stability
           and dependency level for the specified D programs. DTrace stability
           levels are explained in further detail in the Solaris Dynamic Trac-
           ing Guide.


       -V

           Report the highest D programming  interface  version  supported  by
           dtrace. The version information is printed to stdout and the dtrace
           command exits. 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 contains 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 options 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 seman-
                tic 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 compati-
                bility  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
                semantic 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 perspec-
           tive 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
           definitions 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
                      compiled)

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

               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
           descriptions  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
       additional  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 pro-
            grams  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 sat-
            isfied.


       2    Invalid command line options or arguments were specified.


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




       tab()  box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT-
       TRIBUTE VALUE _ AvailabilitySUNWdtrc _ Interface StabilitySee below.



       The command-line syntax is  Committed.  The  human-readable  output  is
       Uncommitted.

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)

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias <christia@softlab.ntua.gr>
©1996-2016 Modified for NetBSD by Kimmo Suominen