Mac Developer Library Developer
Search

 

This manual page is for Mac OS X version 10.9

If you are running a different version of Mac OS X, view the documentation locally:

  • In Terminal, using the man(1) command

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

  • To learn how the manual is organized or to learn about command syntax, read the manual page for manpages(5).

  • For more information about this technology, look for other documentation in the Apple Developer Library.

  • For general information about writing shell scripts, read Shell Scripting Primer.



DTRACE(1)                                                                                          DTRACE(1)



NAME
       dtrace - generic front-end to the DTrace facility

SYNOPSIS
       dtrace [-aACeFhHlqSvVwZ] [-arch arch_name]
              [-b bufsz] [-c fullPathToCommand] [-D name[=def]]
              [-I path] [-L path] [-o output] [-p pid]
              [-s script] [-U name] [-x arg[=val]]
              [-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]]

OVERVIEW
       The  dtrace  command  is a generic front-end to the DTrace facility.  The command implements a simple
       interface to invoke the D language compiler, the ability to retrieve buffered  trace  data  from  the
       DTrace kernel facility, and a set of basic routines to format and print traced data.  Due to the ker-nel kernel
       nel facility it uses to operate, the dtrace command requires root privileges.

       Users new to DTrace are encouraged to read: How to Use Oracle Solaris DTrace from Oracle Solaris  and
       OpenSolaris System. Oracle, 2010. Available on the web at http://developers.sun.com/solaris/docs/o-s-
       dtrace-htg.pdf

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

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

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

        Options to run the D compiler and compile one or more D program files or programs written  directly
         on the command-line

        Options to generate anonymous tracing programs

        Options to generate program stability reports

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

OPTIONS
       dtrace has the following options:

       -arch arch_name
              Set dtrace's target data model. See arch(1) for a list of currently supported architectures.

       -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.

       -A     Generate  a  plist(5)  of  directives  for  anonymous tracing.  If the -A option is specified,
              dtrace compiles any D programs specified using the -s option or on the command-line  and  con-structs constructs
              structs  a  plist(5) of dtrace directives to enable the specified probes for anonymous trcaing
              and then  exits.   By  default,  dtrace  attempts  to  store  the  plist  to  the  file  /Sys-tem/Library/Extensions/dtrace_dof.kext/Contents/Info.plist. /System/Library/Extensions/dtrace_dof.kext/Contents/Info.plist.
              tem/Library/Extensions/dtrace_dof.kext/Contents/Info.plist.   This  behavior  can  be modified
              using the -o option to specify an alternate output file.

       -b     Set principal trace buffer size.  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     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.

       -C     Run the C preprocessor cpp over D programs before compiling them.  Options can  be  passed  to
              the C preprocessor using the -D, -U, -I, and -H options.  The degree of C standard conformance
              can be selected using the -X option.  Refer to the description of the -X option for a descrip-tion description
              tion of the set of tokens defined by the D compiler when invoking the C preprocessor.

       -D     Define  the specified name when invoking cpp (enabled using the -C option).  If an equals sign
              (=) and additional value are specified, the name is assigned the  corresponding  value.   This
              options 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.  This option can be combined with the -a  option  to  print  anonymous
              tracing  data  and exit, or it can be compiled with D compiler options to verify that programs
              compile without actually executing them and enabling the corresponding instrumentation.

       -f     Specify function name to trace or list (-l option).  The corresponding  argument  can  include
              any  of  the  probe  description forms provider:module:function, module:function, or function.
              Unspecified 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 descrip-tion, description,
              tion, all probes with the  corresponding  function  are  matched.   The  -f  argument  can  be
              suffiexed  with  an  optional D probe clause.  More than one -f option may be specified 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 prefixed with ->.  Function return probe reports are unin-dented unindented
              dented and their output is prefixed with <-.

       -h     Generate a header file containing macro definitions for USDT  probes.  If  the  -o  option  is
              present,  the header file is saved using the pathname specified as the argument for this flag.
              If the -o option is not present and the DTrace program is contained in a file  whose  name  is
              filename.d, the header file is saved using the name filename.h.

       -H     Print  the  pathnames of included files when invoking cpp (enabled using the -C option).  This
              option passes the -H option to each cpp invocation, causing it to display the  list  of  path-
              names, one per line, to stderr.

       -i     Specify  probe identifier to trace or list (-l option).  Probe IDs are specified using decimal
              integers as shown by dtrace -l.  The -i argument can be suffixed  with  an  optional  D  probe
              clause.  More than one -i option may be specified on the command-line at a time.

       -I     Add  the  specified  directory  path  to  the search path for #include files when invoking cpp
              (enabled using the -C option).  This option passes the -I option to each cpp invocation.   The
              specified directory is inserted into the search path ahead of the default directory list.

       -l     List  all  probes matching probe specifications appearing in -f, -i, -m, -n, or -P options. No
              tracing is initiated for any probes.

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

       -m     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 may be specified on the command-line at a time.

       -n     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,  func-tion:name, function:name,
              tion: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 may  be  specified  on  the
              command-line at a time.

       -o     Specify  the  output file for the -A and -l options, or for the traced data.  If the -A option
              is present, and -o is not present, the default output file is /kernel/drv/dtrace.conf.

       -p     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 spe cified on the command line or using the -s option through
              the $target macro variable.

       -P     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.  More than one
              -P option may be specified on the command-line at a time.

       -q     Set  quiet  mode.   dtrace  will suppress messages such as the number of probes matched by the
              specified options and D programs will not print column headers, the CPU ID, the probe  ID,  or
              insert  newlines into the output.  Only data traced and formatted by D program statements such
              as trace() and printf() will be displayed to stdout.

       -s     Compile the specified D program source file.  If the -e option is present, the program is com-piled compiled
              piled  but  no instrumentation is enabled.  If the -l option is specified, the program is com-piled compiled
              piled and the set of probes matched by it is listed, but no instrumentation will  be  enabled.
              If neither -e or -l are present, the instrumentation specified by the D program is enabled and
              tracing begins.

       -S     Show D compiler intermediate code.  The D compiler will produce a report of  the  intermediate
              code generated for each D program to stderr.

       -U     Undefine  the  specified  name  when  invoking cpp (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 program  stability  report
              showing the minimum interface stability and dependency level for the specified D programs.

       -V     Report  the  highest  D programming interface version supported by dtrace.  The version infor-maion informaion
              maion is printed to stdout and the dtrace command exits.

       -w     Allow destructive actions. D programs containing destructive  actions  will  fail  to  compile
              unless this flag is specified.

       -x     Enable or modify a DTrace runtime option or D compiler option.  Boolean options are enabled by
              specifying their name.  Options with values are set by separating the option  name  and  value
              with an equals sign (=).

       -Z     Permit  probe  descriptions that match zero probes.  If the -Z option is not specified, dtrace
              will report an error and exit 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
       Zero or more additional arguments may be specified on the dtrace command line  to  define  a  set  of
       macro  variables ($1, $2, and so on) to be used in any D programs specified using the -s option or on
       the command-line.

C++ MANGLED NAMES
       By default, dtrace uses the demangled names of C++ symbols. You can tell dtrace to  use  the  mangled
       symbol names by passing -xmangled to the command.

OBJECTIVE C PROVIDER
       The  Objective  C  provider is similar to the pid provider, and allows instrumentation of Objective C
       classes and methods. Objective C probe specifiers use the following format:

       objcpid:[class-name[(category-name)]]:[[+|-]method-name]:[name]

       pid    The id number of the process.

       class-name
              The name of the Objective C class.

       category-name
              The name of the category within the Objective C class.

       method-name
              The name of the Objective C method.

       name   The name of the probe, entry, return, or an integer instruction offset within the method.

OBJECTIVE C PROVIDER EXAMPLES
       objc123:NSString:-*:entry
              Every instance method of class NSString in process 123.

       objc123:NSString(*)::entry
              Every method on every category of class NSString in process 123.

       objc123:NSString(foo):+*:entry
              Every class method in NSString's foo category in process 123.

       objc123::-*:entry
              Every instance method in every class and category in process 123.

       objc123:NSString(foo):-dealloc:entry
              The dealloc method in the foo category of class NSString in process 123.

       objc123::method?with?many?colons:entry
              The method method:with:many:colons in every class in process 123. (A ? wildcard must  be  used
              to  match  colon  characters  inside  of  Objective C method names, as they would otherwise be
              parsed as the provider field separators.)

BUILDING CODE CONTAINING USDT PROBES
       The process of adding USDT probes to code is  slightly  different  than  documented  in  the  Solaris
       Dynamic Tracing Guide. The steps for adding probes are as follows:

       1. Name the provider and specify its probes, using the following form:

               provider Example {
                    probe increment(int);
               };

          This  defines  the  Example  provider with one probe, increment, that takes a single int argument.
          Providers can define multiple probes and probes can take multiple arguments.

       2. Process the provider description into a header file.

          The provider description must be converted into a form usable by ObjC/C/C++ code. The dtrace  com-mand command
          mand should be invoked with the -h flag to do this.

               dtrace -h -s exampleProvider.d

          This will generate a header file named exampleProvider.h

       3. Add probe invocations to the application

          For  each probe defined in the provider, the provider.h file will contain two macros.The naming is
          as follows:

               PROVIDER_PROBENAME()
               PROVIDER_PROBENAME_ENABLED()

          In the Example provider, the increment probe becomes:

               EXAMPLE_INCREMENT()
               EXAMPLE_INCREMENT_ENABLED()

          Place a macro invocation in the code at each site to be traced. If the arguments passed to a probe
          are expensive to calculate, you may guard the probe placement like this:

               if (EXAMPLE_INCREMENT_ENABLED()) {
                    argument = /* Expensive argument calculation code here */;
                    EXAMPLE_INCREMENT(argument);
               };

          The if test will only succeed when the increment probe is active.

       4. Compile and link your program normally. No additional compiler or linker flags are required.


OS X BUILTIN VARIABLE CHANGES
       A small number of DTrace builtin variables have OS X specific changes:

       execname
              A  string  giving  the  name  that  was passed to exec(2) to execute the current process.  The
              string consists of at most MAXCOMLEN-1 characters.   The  constant  MAXCOMLEN  is  defined  in
              /usr/include/sys/param.h to be 16.

       tid    A  uint64_t  thread  ID  of  the currently executing thread. The thread ID is guaranteed to be
              unique and non repeating. The tid value is not equivalent to pthread_self.

OS X SPECIFIC ACTIONS
       pidresume(pid)
              The pidresume(pid) action is a destructive action meant to be used  in  conjunction  with  the
              stop()  action.   While the stop() action will task_suspend the currently running process, the
              pidresume(pid) action will task_resume it.  The pidresume(pid)  action  will  only  act  on  a
              process  that  has  been  stopped using the dtrace stop() action.  Passing a pid for a process
              that does not exist, or that was not stopped using dtrace stop() action,  will  result  in  an
              error.

EXIT STATUS
       The following exit values are returned by the dtrace utility:

       0      The specified requests were completed successfully.  For D program requests, the 0 exit status
              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      A fatal error occurred.  For D program requests, the 1 exit status indicates that program com-pilation compilation
              pilation failed or that the specified request could not be satisfied.

       2      Invalid command-line options or arguments were specified.

SEE ALSO
       How  to Use Oracle Solaris DTrace from Oracle Solaris and OpenSolaris System. Oracle, 2010. Available
       on the web at http://www.oracle.com/technetwork/server-storage/solaris10/solaris-dtrace-wp-167895.pdf
       Solaris   Dynamic   Tracing   Guide.    Sun   Microsystems,   2005.    Available   on   the   web  at
       http://docs.sun.com/app/docs/doc/817-6223




Version 1.0                                       July 2006                                        DTRACE(1)

Reporting Problems

The way to report a problem with this manual page depends on the type of problem:

Content errors
Report errors in the content of this documentation with the feedback links below.
Bug reports
Report bugs in the functionality of the described tool or API through Bug Reporter.
Formatting problems
Report formatting mistakes in the online version of these pages with the feedback links below.

Feedback