| blob | 29459cc15815cc155ba576633edecc795de54e4e |
1 '\" te
2 .\" Copyright 2004. Sun Microsystems Inc.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
4 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with
5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH TNF_PROBE 3TNF "Mar 1, 2004"
7 .SH NAME
8 TNF_PROBE, TNF_PROBE_0, TNF_PROBE_1, TNF_PROBE_2, TNF_PROBE_3, TNF_PROBE_4,
9 TNF_PROBE_5, TNF_PROBE_0_DEBUG, TNF_PROBE_1_DEBUG, TNF_PROBE_2_DEBUG,
10 TNF_PROBE_3_DEBUG, TNF_PROBE_4_DEBUG, TNF_PROBE_5_DEBUG, TNF_DEBUG \- probe
11 insertion interface
12 .SH SYNOPSIS
13 .LP
14 .nf
15 \fBcc\fR [ \fIflag\fR ... ] [ \fB-DTNF_DEBUG\fR ] \fIfile\fR ... [ \fB-ltnfprobe\fR ] [ \fIlibrary\fR ... ]
16 #include <tnf/probe.h>
18 \fBTNF_PROBE_0\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR);
19 .fi
21 .LP
22 .nf
23 \fBTNF_PROBE_1\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR);
24 .fi
26 .LP
27 .nf
28 \fBTNF_PROBE_2\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR,
29 \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR);
30 .fi
32 .LP
33 .nf
34 \fBTNF_PROBE_3\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR,\fIarg_value_1\fR,
35 \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR,
36 \fIarg_type_3\fR, \fIarg_name_3\fR, \fIarg_value_3\fR);
37 .fi
39 .LP
40 .nf
41 \fBTNF_PROBE_4\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR,
42 \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR,
43 \fIarg_type_3\fR, \fIarg_name_3\fR, \fIarg_value_3\fR,
44 \fIarg_type_4\fR, \fIarg_name_4\fR, \fIarg_value_4\fR);
45 .fi
47 .LP
48 .nf
49 \fBTNF_PROBE_5\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR,
50 \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR,
51 \fIarg_type_3\fR, \fIarg_name_3\fR, \fIarg_value_3\fR,
52 \fIarg_type_4\fR, \fIarg_name_4\fR, \fIarg_value_4\fR,
53 \fIarg_type_5\fR, \fIarg_name_5\fR, \fIarg_value_5\fR);
54 .fi
56 .LP
57 .nf
58 \fBTNF_PROBE_0_DEBUG\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR);
59 .fi
61 .LP
62 .nf
63 \fBTNF_PROBE_1_DEBUG\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR);
64 .fi
66 .LP
67 .nf
68 \fBTNF_PROBE_2_DEBUG\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR,
69 \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR);
70 .fi
72 .LP
73 .nf
74 \fBTNF_PROBE_3_DEBUG\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR,
75 \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR,
76 \fIarg_type_3\fR, \fIarg_name_3\fR, \fIarg_value_3\fR);
77 .fi
79 .LP
80 .nf
81 \fBTNF_PROBE_4_DEBUG\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR,
82 \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR,
83 \fIarg_type_3\fR, \fIarg_name_3\fR, \fIarg_value_3\fR,
84 \fIarg_type_4\fR, \fIarg_name_4\fR, \fIarg_value_4\fR);
85 .fi
87 .LP
88 .nf
89 \fBTNF_PROBE_5_DEBUG\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR,
90 \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR,
91 \fIarg_type_3\fR, \fIarg_name_3\fR, \fIarg_value_3\fR,
92 \fIarg_type_4\fR, \fIarg_name_4\fR, \fIarg_value_4\fR,
93 \fIarg_type_5\fR, \fIarg_name_5\fR, \fIarg_value_5\fR);
94 .fi
96 .SH DESCRIPTION
97 .sp
98 .LP
99 This macro interface is used to insert probes into C or C++ code for tracing.
100 See \fBtracing\fR(3TNF) for a discussion of the Solaris tracing architecture,
101 including example source code that uses it.
102 .sp
103 .LP
104 You can place probes anywhere in C and C++ programs including .init
105 sections, .fini sections, multi-threaded code, shared objects, and shared objects opened
106 by \fBdlopen\fR(3C). Use probes to generate trace data for performance
107 analysis or to write debugging output to stderr. Probes are controlled at
108 runtime by \fBprex\fR(1).
109 .sp
110 .LP
111 The trace data is logged to a trace file in Trace Normal Form ( \fBTNF).\fR
112 The interface for the user to specify the name and size of the trace file is
113 described in \fBprex\fR(1). Think of the trace file as the least recently used
114 circular buffer. Once the file has been filled, newer events will overwrite the
115 older ones.
116 .sp
117 .LP
118 Use \fBTNF_PROBE_0\fR through \fBTNF_PROBE_5\fR to create production probes.
119 These probes are compiled in by default. Developers are encouraged to embed
120 such probes strategically, and to leave them compiled within production
121 software. Such probes facilitate on-site analysis of the software.
122 .sp
123 .LP
124 Use \fBTNF_PROBE_0_DEBUG\fR through \fBTNF_PROBE_5_DEBUG\fR to create debug
125 probes. These probes are compiled out by default. If you compile the program
126 with the preprocessor option \fB-DTNF_DEBUG\fR or with the preprocessor
127 control statement \fB#define\fR \fBTNF_DEBUG\fR ahead of the \fB#include\fR
128 \fB<tnf/probe.h>\fR statement, the debug probes will be compiled into the
129 program. When compiled in, debug probes differ in only one way from the
130 equivalent production probes. They contain an additional "debug" attribute
131 which may be used to distinguish them from production probes at runtime, for
132 example, when using \fBprex()\fR. Developers are encouraged to embed any number
133 of probes for debugging purposes. Disabled probes have such a small runtime
134 overhead that even large numbers of them do not make a significant impact.
135 .sp
136 .LP
137 If you compile with the preprocessor option \fB-DNPROBE\fR or place the
138 preprocessor control statement \fB#define\fR \fBNPROBE\fR ahead of the
139 \fB#include\fR \fB<tnf/probe.h>\fR statement, no probes will be compiled into
140 the program.
141 .SS "name"
142 .sp
143 .LP
144 The \fIname\fR of the probe should follow the syntax guidelines for identifiers
145 in ANSI C. The use of \fIname\fR declares it, hence no separate declaration is
146 necessary. This is a block scope declaration, so it does not affect the name
147 space of the program.
148 .SS "keys"
149 .sp
150 .LP
151 \fIkeys\fR is a string of space-separated keywords that specify the groups that
152 the probe belongs to. Semicolons, single quotation marks, and the equal
153 character (=) are not allowed in this string. If any of the groups are enabled,
154 the probe is enabled. \fIkeys\fR cannot be a variable. It must be a string
155 constant.
156 .SS "detail"
157 .sp
158 .LP
159 \fIdetail\fR is a string that consists of <attribute> <value> pairs that are
160 each separated by a semicolon. The first word (up to the space) is considered
161 to be the attribute and the rest of the string (up to the semicolon) is
162 considered the value. Single quotation marks are used to denote a string value.
163 Besides quotation marks, spaces separate multiple values. The value is
164 optional. Although semicolons or single quotation marks generally are not
165 allowed within either the attribute or the value, when text with embedded
166 spaces is meant to denote a single value, use single quotes surrounding this
167 text.
168 .sp
169 .LP
170 Use \fIdetail\fR for one of two reasons. First, use \fIdetail\fR to supply
171 an attribute that a user can type into \fBprex\fR(1) to select probes. For
172 example, if a user defines an attribute called color, then \fBprex\fR(1) can
173 select probes based on the value of color. Second, use \fIdetail\fR to annotate
174 a probe with a string that is written out to a trace file only once.
175 \fBprex\fR(1) uses spaces to tokenize the value when searching for a match.
176 Spaces around the semicolon delimiter are allowed. \fIdetail\fR cannot be a
177 variable; it must be a string constant. For example, the \fIdetail\fR string:
178 .sp
179 .in +2
180 .nf
181 "XYZ%debug 'entering function A'; XYZ%exception 'no file';
182 XYZ%func_entry; XYZ%color red blue"
183 .fi
184 .in -2
186 .sp
187 .LP
188 consists of 4 units:
189 .sp
191 .sp
192 .TS
193 box;
194 c c c
195 l l l .
196 \fBAttribute\fR \fBValue\fR \fBValues that\fR \fBprex\fR \fBmatches on\fR
197 _
198 XYZ%debug \&'entering function A' \&'entering function A'
199 XYZ%exception \&'no file' \&'no file'
200 XYZ%func_entry /.*/ (regular expression)
201 XYZ%color red blue red <or> blue
202 .TE
204 .sp
205 .LP
206 Attribute names must be prefixed by the vendor stock symbol followed by
207 the '%' character. This avoids conflicts in the attribute name space. All
208 attributes that do not have a '%' character are reserved. The following
209 attributes are predefined:
210 .sp
212 .sp
213 .TS
214 box;
215 c c
216 l l .
217 \fBAttribute\fR \fBSemantics\fR
218 _
219 name name of probe
220 keys T{
221 keys of the probe (value is space\(mi separated tokens)
222 T}
223 file file name of the probe
224 line line number of the probe
225 slots T{
226 slot names of the probe event (\fIarg_name_n\fR)
227 T}
228 object T{
229 the executable or shared object that this probe is in.
230 T}
231 debug T{
232 distinguishes debug probes from production probes
233 T}
234 .TE
236 .SS "arg_type_n"
237 .sp
238 .LP
239 This is the type of the \fIn\fRth argument. The following are predefined
240 \fBTNF\fR types:
241 .sp
243 .sp
244 .TS
245 box;
246 c c
247 l l .
248 \fBtnf Type\fR \fBAssociated C type (and semantics)\fR
249 _
250 tnf_int int
251 tnf_uint unsigned int
252 tnf_long long
253 tnf_ulong unsigned long
254 tnf_longlong T{
255 long long (if implemented in compilation system)
256 T}
257 tnf_ulonglong T{
258 unsigned long long (if implemented in compilation system)
259 T}
260 tnf_float float
261 tnf_double double
262 tnf_string char *
263 tnf_opaque void *
264 .TE
266 .sp
267 .LP
268 To define new \fBTNF\fR types that are records consisting of the predefined
269 \fBTNF\fR types or references to other user defined types, use the interface
270 specified in \fBTNF_DECLARE_RECORD\fR(3TNF).
271 .SS "arg_name_n"
272 .sp
273 .LP
274 \fIarg_name_n\fR is the name that the user associates with the \fIn\fRth
275 argument. Do not place quotation marks around \fIarg_name_n\fR. Follow the
276 syntax guidelines for identifiers in ANSI C. The string version of
277 \fIarg_name_n\fR is stored for every probe and can be accessed as the attribute
278 "slots".
279 .SS "arg_value_n"
280 .sp
281 .LP
282 \fIarg_value_n\fR is evaluated to yield a value to be included in the trace
283 file. A read access is done on any variables that are in mentioned in
284 \fIarg_value_n\fR. In a multithreaded program, it is the user's responsibility
285 to place locks around the \fBTNF_PROBE\fR macro if \fIarg_value_n\fR contains
286 a variable that should be read protected.
287 .SH EXAMPLES
288 .LP
289 \fBExample 1 \fRtracing(3TNF)
290 .sp
291 .LP
292 See \fBtracing\fR(3TNF) for complete examples showing debug and production
293 probes in source code.
295 .SH ATTRIBUTES
296 .sp
297 .LP
298 See \fBattributes\fR(5) for descriptions of the following attributes:
299 .sp
301 .sp
302 .TS
303 box;
304 c | c
305 l | l .
306 ATTRIBUTE TYPE ATTRIBUTE VALUE
307 _
308 MT Level MT-Safe
309 .TE
311 .SH SEE ALSO
312 .sp
313 .LP
314 \fBld\fR(1), \fBprex\fR(1), \fBtnfdump\fR(1), \fBdlopen\fR(3C),
315 \fBlibtnfctl\fR(3TNF), \fBTNF_DECLARE_RECORD\fR(3TNF), \fBthreads\fR(5),
316 \fBtnf_process_disable\fR(3TNF), \fBtracing\fR(3TNF), \fBattributes\fR(5)
317 .SH NOTES
318 .sp
319 .LP
320 If attaching to a running program with \fBprex\fR(1) to control the probes,
321 compile the program with \fB-ltnfprobe\fR or start the program with the
322 environment variable \fBLD_PRELOAD\fR set to \fBlibtnfprobe.so.1\fR. See
323 \fBld\fR(1). If \fBlibtnfprobe\fR is explicitly linked into the program, it
324 must be listed before \fBlibdoor\fR, which in turn must be listed before
325 \fBlibthread\fR on the link line.