# dtrace

## NAME



           dtrace - Dtrace compatible user application static probe
           generation tool.
    


## SYNOPSIS



           **dtrace -s** _file_ [**OPTIONS**]
    


## DESCRIPTION



           The dtrace command converts probe descriptions defined in _file.d_
           into a probe header file via the **-h** option or a probe description
           file via the **-G** option.
    


## OPTIONS



           **-h** generate a systemtap header file.
    
           **-G** generate a systemtap probe definition object file.  This
                  invokes the C compiler with a sensible set of compiler
                  flags.  If you need to add more, flags found in the **CFLAGS**
                  environment variable will be transcribed to the compiler.
                  If this is not enough control, use the -k option to capture
                  the generated C file and compile as needed.
    
           **-o** _file_
                  is the name of the output file.  If the **-G** option is given
                  then the output file will be called _file.o_ ; if the **-h**
                  option is given then the output file will be called _file.h_.
    
           **-C** run the cpp preprocessor on the input file when the **-h**
                  option is given.
    
           **-I** _file_
                  give this include path to cpp when the **-C** option is given.
    
           **-k** keep temporary files, for example the C language source for
                  the **-G** option.
    


## EXAMPLES



           Systemtap is source compatible with dtrace user application static
           probe support.  Given a file _test.d_ containing:
    
                  provider sdt_probes
                  {
                    probe test_0 (int type);
                    probe test_1 (struct astruct node);
                  };
                  struct astruct {int a; int b;};
    
           Then the command _"dtrace -s test.d -G"_ will create the probe defi‐
           nition file _test.o_ and the command _"dtrace -stest.d -h"_ will cre‐
           ate the probe header file _test.h_ Subsequently the application can
           use the generated macros this way:
    
                  #include "test.h"
                   ...
                  struct astruct s;
                   ...
                  SDT_PROBES_TEST_0(value);
                   ...
                  if (SDT_PROBES_TEST_1_ENABLED())
                      SDT_PROBES_TEST_1(expensive_function(s));
    


## SEMAPHORES



           Semaphores are flag variables used by probes as a way of bypassing
           potentially costly processing to prepare arguments for probes that
           may not even be active.  They are automatically set/cleared by
           systemtap when a relevant script is running, so the argument setup
           cost is only paid when necessary.  These semaphore variables are
           defined within the the _"test.o"_ object file, which must therefore
           be linked into an application.
    
           Sometimes, semaphore variables are not necessary nor helpful.
           Skipping them can simplify the build process, by omitting the ex‐
           tra _"test.o"_ file.  To skip dependence upon semaphore variables,
           include _" <sys/sdt.h>"_ within the application before _"test.h"_ :
    
                  #include <sys/sdt.h>
                  #include "test.h"
                   ...
                  struct astruct s;
                   ...
                  SDT_PROBES_TEST_0(value);
                   ...
                  if (SDT_PROBES_TEST_1_ENABLED())
                     SDT_PROBES_TEST_1(cheap_function(s));
    
           In this mode, the ENABLED() test is fixed at 1.
    


## BUGS



           Use the Bugzilla link of the project web page or our mailing list.
           **http://sourceware.org/systemtap/ **, **< systemtap@sourceware.org>**.
    
           error::reporting(7stap),
           **https://sourceware.org/systemtap/wiki/HowToReportBugs **
    


* * *