1TNF_PROBE(3TNF)              TNF Library Functions             TNF_PROBE(3TNF)
2
3
4

NAME

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

SYNOPSIS

12       cc [ flag ... ] [ -DTNF_DEBUG ] file ... [ -ltnfprobe ] [ library ... ]
13       #include <tnf/probe.h>
14
15       TNF_PROBE_0(name, keys, detail);
16
17
18       TNF_PROBE_1(name, keys, detail, arg_type_1, arg_name_1, arg_value_1);
19
20
21       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
24
25       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
29
30       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
35
36       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
42
43       TNF_PROBE_0_DEBUG(name, keys, detail);
44
45
46       TNF_PROBE_1_DEBUG(name, keys, detail, arg_type_1, arg_name_1, arg_value_1);
47
48
49       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
52
53       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
57
58       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
63
64       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
70

DESCRIPTION

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
76
77       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
83
84       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
90
91       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
96
97       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
110
111       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
115   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
121   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
128   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
139
140       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
150         "XYZ%debug 'entering function A'; XYZ%exception 'no file';
151         XYZ%func_entry; XYZ%color red blue"
152
153
154
155       consists of 4 units:
156
157
158
159
160       ┌─────────────────────────────────────────────────────────────────────────┐
161Attribute                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
169
170       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
175
176
177
178       ┌───────────────────────────────────────────────────────────┐
179Attribute                     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
195   arg_type_n
196       This  is  the  type  of the  nth argument. The following are predefined
197       TNF types:
198
199
200
201
202       ┌────────────────────────────────────────────────────────────────┐
203tnf 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
219
220       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
224   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
230   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

EXAMPLES

238       Example 1 tracing(3TNF)
239
240
241       See  tracing(3TNF)  for  complete examples showing debug and production
242       probes in source code.
243
244

ATTRIBUTES

246       See attributes(5) for descriptions of the following attributes:
247
248
249
250
251       ┌─────────────────────────────┬─────────────────────────────┐
252       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
253       ├─────────────────────────────┼─────────────────────────────┤
254       │Availability                 │SUNWtnfd                     │
255       ├─────────────────────────────┼─────────────────────────────┤
256       │MT Level                     │MT-Safe                      │
257       └─────────────────────────────┴─────────────────────────────┘
258

SEE ALSO

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

NOTES

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.
271
272
273
274SunOS 5.11                        1 Mar 2004                   TNF_PROBE(3TNF)
Impressum