1TNF_PROBE(3TNF) TNF Library Functions TNF_PROBE(3TNF)
2
6 TNF_PROBE, TNF_PROBE_0, TNF_PROBE_1, TNF_PROBE_2, TNF_PROBE_3,
7 TNF_PROBE_4, TNF_PROBE_5, TNF_PROBE_0_DEBUG, TNF_PROBE_1_DEBUG,
8 TNF_PROBE_2_DEBUG, TNF_PROBE_3_DEBUG, TNF_PROBE_4_DEBUG,
9 TNF_PROBE_5_DEBUG, TNF_DEBUG - probe insertion interface
10
12 cc [ flag ... ] [ -DTNF_DEBUG ] file ... [ -ltnfprobe ] [ library ... ]
13 #include <tnf/probe.h>
14 TNF_PROBE_0(name, keys, detail);
16 TNF_PROBE_1(name, keys, detail, arg_type_1, arg_name_1, arg_value_1);
19 TNF_PROBE_2(name, keys, detail, arg_type_1, arg_name_1, arg_value_1,
22 arg_type_2, arg_name_2, arg_value_2);
23 TNF_PROBE_3(name, keys, detail, arg_type_1, arg_name_1,arg_value_1,
26 arg_type_2, arg_name_2, arg_value_2,
27 arg_type_3, arg_name_3, arg_value_3);
28 TNF_PROBE_4(name, keys, detail, arg_type_1, arg_name_1, arg_value_1,
31 arg_type_2, arg_name_2, arg_value_2,
32 arg_type_3, arg_name_3, arg_value_3,
33 arg_type_4, arg_name_4, arg_value_4);
34 TNF_PROBE_5(name, keys, detail, arg_type_1, arg_name_1, arg_value_1,
37 arg_type_2, arg_name_2, arg_value_2,
38 arg_type_3, arg_name_3, arg_value_3,
39 arg_type_4, arg_name_4, arg_value_4,
40 arg_type_5, arg_name_5, arg_value_5);
41 TNF_PROBE_0_DEBUG(name, keys, detail);
44 TNF_PROBE_1_DEBUG(name, keys, detail, arg_type_1, arg_name_1, arg_value_1);
47 TNF_PROBE_2_DEBUG(name, keys, detail, arg_type_1, arg_name_1, arg_value_1,
50 arg_type_2, arg_name_2, arg_value_2);
51 TNF_PROBE_3_DEBUG(name, keys, detail, arg_type_1, arg_name_1, arg_value_1,
54 arg_type_2, arg_name_2, arg_value_2,
55 arg_type_3, arg_name_3, arg_value_3);
56 TNF_PROBE_4_DEBUG(name, keys, detail, arg_type_1, arg_name_1, arg_value_1,
59 arg_type_2, arg_name_2, arg_value_2,
60 arg_type_3, arg_name_3, arg_value_3,
61 arg_type_4, arg_name_4, arg_value_4);
62 TNF_PROBE_5_DEBUG(name, keys, detail, arg_type_1, arg_name_1, arg_value_1,
65 arg_type_2, arg_name_2, arg_value_2,
66 arg_type_3, arg_name_3, arg_value_3,
67 arg_type_4, arg_name_4, arg_value_4,
68 arg_type_5, arg_name_5, arg_value_5);
69
72 This macro interface is used to insert probes into C or C++ code for
73 tracing. See tracing(3TNF) for a discussion of the Solaris tracing
74 architecture, including example source code that uses it.
75 You can place probes anywhere in C and C++ programs including .init
78 sections, .fini sections, multi-threaded code, shared objects, and
79 shared objects opened by dlopen(3C). Use probes to generate trace data
80 for performance analysis or to write debugging output to stderr.
81 Probes are controlled at runtime by prex(1).
82 The trace data is logged to a trace file in Trace Normal Form ( TNF).
85 The interface for the user to specify the name and size of the trace
86 file is described in prex(1). Think of the trace file as the least
87 recently used circular buffer. Once the file has been filled, newer
88 events will overwrite the older ones.
89 Use TNF_PROBE_0 through TNF_PROBE_5 to create production probes. These
92 probes are compiled in by default. Developers are encouraged to embed
93 such probes strategically, and to leave them compiled within production
94 software. Such probes facilitate on-site analysis of the software.
95 Use TNF_PROBE_0_DEBUG through TNF_PROBE_5_DEBUG to create debug
98 probes. These probes are compiled out by default. If you compile the
99 program with the preprocessor option -DTNF_DEBUG or with the pre‐
100 processor control statement #define TNF_DEBUG ahead of the #include
101 <tnf/probe.h> statement, the debug probes will be compiled into the
102 program. When compiled in, debug probes differ in only one way from the
103 equivalent production probes. They contain an additional "debug"
104 attribute which may be used to distinguish them from production probes
105 at runtime, for example, when using prex(). Developers are encouraged
106 to embed any number of probes for debugging purposes. Disabled probes
107 have such a small runtime overhead that even large numbers of them do
108 not make a significant impact.
109 If you compile with the preprocessor option -DNPROBE or place the pre‐
112 processor control statement #define NPROBE ahead of the #include
113 <tnf/probe.h> statement, no probes will be compiled into the program.
114 name
116 The name of the probe should follow the syntax guidelines for identi‐
117 fiers in ANSI C. The use of name declares it, hence no separate decla‐
118 ration is necessary. This is a block scope declaration, so it does not
119 affect the name space of the program.
120 keys
122 keys is a string of space-separated keywords that specify the groups
123 that the probe belongs to. Semicolons, single quotation marks, and the
124 equal character (=) are not allowed in this string. If any of the
125 groups are enabled, the probe is enabled. keys cannot be a variable.
126 It must be a string constant.
127 detail
129 detail is a string that consists of <attribute> <value> pairs that are
130 each separated by a semicolon. The first word (up to the space) is
131 considered to be the attribute and the rest of the string (up to the
132 semicolon) is considered the value. Single quotation marks are used to
133 denote a string value. Besides quotation marks, spaces separate multi‐
134 ple values. The value is optional. Although semicolons or single quota‐
135 tion marks generally are not allowed within either the attribute or
136 the value, when text with embedded spaces is meant to denote a single
137 value, use single quotes surrounding this text.
138 Use detail for one of two reasons. First, use detail to supply an
141 attribute that a user can type into prex(1) to select probes. For
142 example, if a user defines an attribute called color, then prex(1) can
143 select probes based on the value of color. Second, use detail to anno‐
144 tate a probe with a string that is written out to a trace file only
145 once. prex(1) uses spaces to tokenize the value when searching for a
146 match. Spaces around the semicolon delimiter are allowed. detail cannot
147 be a variable; it must be a string constant. For example, the detail
148 string:
149 "XYZ%debug 'entering function A'; XYZ%exception 'no file';
151 XYZ%func_entry; XYZ%color red blue"
152 consists of 4 units:
156 ┌─────────────────────────────────────────────────────────────────────────┐
161 │ Attribute Value Values that prex matches on │
162 ├─────────────────────────────────────────────────────────────────────────┤
163 │XYZ%debug 'entering function A' 'entering function A' │
164 │XYZ%exception 'no file' 'no file' │
165 │XYZ%func_entry /.*/ (regular expression) │
166 │XYZ%color red blue red <or> blue │
167 └─────────────────────────────────────────────────────────────────────────┘
168 Attribute names must be prefixed by the vendor stock symbol followed by
171 the '%' character. This avoids conflicts in the attribute name space.
172 All attributes that do not have a '%' character are reserved. The fol‐
173 lowing attributes are predefined:
174 ┌───────────────────────────────────────────────────────────┐
179 │ Attribute Semantics │
180 ├───────────────────────────────────────────────────────────┤
181 │name name of probe │
182 │keys keys of the probe (value is │
183 │ space− separated tokens) │
184 │file file name of the probe │
185 │line line number of the probe │
186 │slots slot names of the probe │
187 │ event (arg_name_n) │
188 │object the executable or shared │
189 │ object that this probe is │
190 │ in. │
191 │debug distinguishes debug probes │
192 │ from production probes │
193 └───────────────────────────────────────────────────────────┘
194 arg_type_n
196 This is the type of the nth argument. The following are predefined
197 TNF types:
198 ┌────────────────────────────────────────────────────────────────┐
203 │ tnf Type Associated C type (and semantics) │
204 ├────────────────────────────────────────────────────────────────┤
205 │tnf_int int │
206 │tnf_uint unsigned int │
207 │tnf_long long │
208 │tnf_ulong unsigned long │
209 │tnf_longlong long long (if implemented in com‐ │
210 │ pilation system) │
211 │tnf_ulonglong unsigned long long (if imple‐ │
212 │ mented in compilation system) │
213 │tnf_float float │
214 │tnf_double double │
215 │tnf_string char * │
216 │tnf_opaque void * │
217 └────────────────────────────────────────────────────────────────┘
218 To define new TNF types that are records consisting of the predefined
221 TNF types or references to other user defined types, use the interface
222 specified in TNF_DECLARE_RECORD(3TNF).
223 arg_name_n
225 arg_name_n is the name that the user associates with the nth argument.
226 Do not place quotation marks around arg_name_n. Follow the syntax
227 guidelines for identifiers in ANSI C. The string version of arg_name_n
228 is stored for every probe and can be accessed as the attribute "slots".
229 arg_value_n
231 arg_value_n is evaluated to yield a value to be included in the trace
232 file. A read access is done on any variables that are in mentioned in
233 arg_value_n. In a multithreaded program, it is the user's responsibil‐
234 ity to place locks around the TNF_PROBE macro if arg_value_n contains
235 a variable that should be read protected.
236
238 Example 1 [22mtracing(3TNF)
239 See tracing(3TNF) for complete examples showing debug and production
242 probes in source code.
243
246 See attributes(5) for descriptions of the following attributes:
247 ┌─────────────────────────────┬─────────────────────────────┐
252 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
253 ├─────────────────────────────┼─────────────────────────────┤
254 │Availability │SUNWtnfd │
255 ├─────────────────────────────┼─────────────────────────────┤
256 │MT Level │MT-Safe │
257 └─────────────────────────────┴─────────────────────────────┘
258
260 ld(1), prex(1), tnfdump(1), dlopen(3C), libtnfctl(3TNF),
261 TNF_DECLARE_RECORD(3TNF), threads(5), tnf_process_disable(3TNF), trac‐
262 ing(3TNF), attributes(5)
263
265 If attaching to a running program with prex(1) to control the probes,
266 compile the program with -ltnfprobe or start the program with the envi‐
267 ronment variable LD_PRELOAD set to libtnfprobe.so.1. See ld(1). If
268 libtnfprobe is explicitly linked into the program, it must be listed
269 before libdoor, which in turn must be listed before libthread on the
270 link line.
271SunOS 5.11 1 Mar 2004 TNF_PROBE(3TNF)