dtrace(1)

1DTRACE(1)                   General Commands Manual                  DTRACE(1)
2
3
4

NAME

6       dtrace  -  Dtrace  compatible  user application static probe generation
7       tool.
8
9
10

SYNOPSIS

12       dtrace -s file [OPTIONS]
13
14

DESCRIPTION

16       The dtrace command converts probe descriptions defined in file.d into a
17       probe header file via the -h option or a probe description file via the
18       -G option.
19
20

OPTIONS

22       -h     generate a systemtap header file.
23
24
25       -G     generate a systemtap probe definition object file.
26
27
28       -o file
29              is the name of the output file.  If the -G option is given  then
30              the output file will be called file.o; if the -h option is given
31              then the output file will be called file.h.
32
33
34       -C     run the cpp preprocessor on the input file when the -h option is
35              given.
36
37
38       -I file
39              give this include path to cpp when the -C option is given.
40
41
42       -k     keep  temporary files, for example the C language source for the
43              -G option.
44
45

EXAMPLES

47       Systemtap is source compatible  with  dtrace  user  application  static
48       probe support.  Given a file test.d containing:
49
50              provider sdt_probes
51              {
52                probe test_0 (int type);
53                probe test_1 (struct astruct node);
54              };
55              struct astruct {int a; int b;};
56
57       Then the command "dtrace -s test.d -G" will create the probe definition
58       file test.o and the command "dtrace -stest.d -h" will create the  probe
59       header  file  test.h Subsequently the application can use the generated
60       macros this way:
61
62              #include "test.h"
63               ...
64              struct astruct s;
65               ...
66              SDT_PROBES_TEST_0(value);
67               ...
68              if (SDT_PROBES_TEST_1_ENABLED())
69                  SDT_PROBES_TEST_1(expensive_function(s));
70
71
72

SEMAPHORES

74       Semaphores are flag variables used by probes as a way of bypassing  po‐
75       tentially  costly  processing  to prepare arguments for probes that may
76       not even be active.  They are automatically  set/cleared  by  systemtap
77       when  a  relevant script is running, so the argument setup cost is only
78       paid when necessary.  These semaphore variables are defined within  the
79       the "test.o" object file, which must therefore be linked into an appli‐
80       cation.
81
82       Sometimes, semaphore variables are not necessary nor helpful.  Skipping
83       them  can  simplify  the  build process, by omitting the extra "test.o"
84       file.   To  skip   dependence   upon   semaphore   variables,   include
85       "<sys/sdt.h>" within the application before "test.h":
86
87              #include <sys/sdt.h>
88              #include "test.h"
89               ...
90              struct astruct s;
91               ...
92              SDT_PROBES_TEST_0(value);
93               ...
94              if (SDT_PROBES_TEST_1_ENABLED())
95                 SDT_PROBES_TEST_1(cheap_function(s));
96
97       In this mode, the ENABLED() test is fixed at 1.
98
99

BUGS

107       Use  the  Bugzilla  link  of  the project web page or our mailing list.
108       http://sourceware.org/systemtap/, <systemtap@sourceware.org>.
109
110       error::reporting(7stap),
111       https://sourceware.org/systemtap/wiki/HowToReportBugs
112
113
114
115                                                                     DTRACE(1)