Debian Codegraph @

man/dtrace.1

raw
1 .\" -*- nroff -*-
2 .TH DTRACE 1
3 .SH NAME
4 dtrace \- Dtrace compatible user application static probe generation tool.
5
6 .\" macros
7 .\" do not nest SAMPLEs
8 .de SAMPLE
9 .br
10
11 .nr oldin \\n(.i
12 .RS
13 .nf
14 .nh
15 ..
16 .de ESAMPLE
17 .hy
18 .fi
19 .RE
20 .in \\n[oldin]u
21
22 ..
23
24 .SH SYNOPSIS
25
26 .br
27 .B dtrace \-s \fIfile\fR [\fBOPTIONS\fR]
28
29 .SH DESCRIPTION
30
31 The dtrace command converts probe descriptions defined in \fIfile.d\fR
32 into a probe header
33 file via the \fB\-h\fR option
34 or a probe description file via the \fB\-G\fR option.
35
36 .SH OPTIONS
37 .PP
38 .TP
39 .B \-h
40 generate a systemtap header file.
41
42 .TP
43 .B \-G
44 generate a systemtap probe definition object file. This invokes the C
45 compiler with a sensible set of compiler flags. If you need to add
46 more, flags found in the \fBCFLAGS\fP environment variable will be
47 transcribed to the compiler. If this is not enough control, use the
48 \-k option to capture the generated C file and compile as needed.
49
50 .TP
51 .B \-o \fIfile\fR
52 is the name of the output file. If the \fB\-G\fR option is given then
53 the output file will be called \fIfile.o\fR; if the \fB\-h\fR option is
54 given then the output file will be called \fIfile.h\fR.
55
56 .TP
57 .B \-C
58 run the cpp preprocessor on the input file when the \fB\-h\fR option
59 is given.
60
61 .TP
62 .B \-I \fIfile\fR
63 give this include path to cpp when the \fB\-C\fR option is given.
64
65 .TP
66 .B \-k
67 keep temporary files, for example the C language source for the
68 \fB\-G\fR option.
69
70 .SH EXAMPLES
71
72 Systemtap is source compatible with dtrace user application static
73 probe support.
74 Given a file \fItest.d\fR containing:
75 .SAMPLE
76 provider sdt_probes
77 {
78 probe test_0 (int type);
79 probe test_1 (struct astruct node);
80 };
81 struct astruct {int a; int b;};
82 .ESAMPLE
83 Then the command \fI"dtrace\ \-s\ test.d\ \-G"\fR will create the
84 probe definition file \fItest.o\fR and the command \fI"dtrace\ \-s\
85 test.d\ \-h"\fR will create the probe header file \fItest.h\fR
86 Subsequently the application can use the generated macros this way:
87 .SAMPLE
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(expensive_function(s));
96 .ESAMPLE
97
98 .SH SEMAPHORES
99
100 Semaphores are flag variables used by probes as a way of bypassing
101 potentially costly processing to prepare arguments for probes that may
102 not even be active. They are automatically set/cleared by systemtap
103 when a relevant script is running, so the argument setup cost is only
104 paid when necessary. These semaphore variables are defined within the
105 the \fI"test.o"\fR object file, which must therefore be linked into an
106 application.
107 .PP
108 Sometimes, semaphore variables are not necessary nor helpful. Skipping
109 them can simplify the build process, by omitting the extra \fI"test.o"\fR
110 file. To skip dependence upon semaphore variables, include \fI"<sys/sdt.h>"\fR
111 within the application before \fI"test.h"\fR:
112 .SAMPLE
113 #include <sys/sdt.h>
114 #include "test.h"
115 \.\.\.
116 struct astruct s;
117 \.\.\.
118 SDT_PROBES_TEST_0(value);
119 \.\.\.
120 if (SDT_PROBES_TEST_1_ENABLED())
121 SDT_PROBES_TEST_1(cheap_function(s));
122 .ESAMPLE
123 In this mode, the ENABLED() test is fixed at 1.
124
125 .SH SEE ALSO
126 .nh
127 .nf
128 .IR stap (1),
129 .IR stappaths (7)
130
131
132 .SH BUGS
133 Use the Bugzilla link of the project web page or our mailing list.
134 .nh
135 .BR http://sourceware.org/systemtap/ ", " <[email protected]> .
136 .hy
137 .PP
138 .IR error::reporting (7stap),
139 .nh
140 .BR https://sourceware.org/systemtap/wiki/HowToReportBugs
141 .hy