1TNF_DECLARE_RECORD(3TNF) TNF Library Functions TNF_DECLARE_RECORD(3TNF)
2
6 TNF_DECLARE_RECORD, TNF_DEFINE_RECORD_1, TNF_DEFINE_RECORD_2,
7 TNF_DEFINE_RECORD_3, TNF_DEFINE_RECORD_4, TNF_DEFINE_RECORD_5 - TNF
8 type extension interface for probes
9
11 cc [ flag ... ] file ...[ -ltnfprobe ] [ library ... ]
12 #include <tnf/probe.h>
13 TNF_DECLARE_RECORD(c_type, tnf_type);
17 TNF_DEFINE_RECORD_1(c_type, tnf_type, tnf_member_type_1, c_member_name_1);
20 TNF_DEFINE_RECORD_2(c_type, tnf_type, tnf_member_type_1, c_member_name_1,
23 tnf_member_type_2, c_member_name_2);
24 TNF_DEFINE_RECORD_3(c_type, tnf_type, tnf_member_type_1, c_member_name_1,
27 tnf_member_type_2, c_member_name_2, tnf_member_type_3,
28 c_member_name_3);
29 TNF_DEFINE_RECORD_4(c_type, tnf_type, tnf_member_type_1, c_member_name_1,
32 tnf_member_type_2, c_member_name_2, tnf_member_type_3,
33 c_member_name_3, tnf_member_type_4, c_member_name_4);
34 TNF_DEFINE_RECORD_5(c_type, tnf_type, tnf_member_type_1, c_member_name_1,
37 tnf_member_type_2, c_member_name_2, tnf_member_type_3,
38 c_member_name_3,tnf_member_type_4, c_member_name_4,
39 tnf_member_type_5, c_member_name_5);
40
43 This macro interface is used to extend the TNF (Trace Normal Form)
44 types that can be used in TNF_PROBE(3TNF).
45 There should be only one TNF_DECLARE_RECORD and one TNF_DEFINE_RECORD
48 per new type being defined. The TNF_DECLARE_RECORD should precede the
49 TNF_DEFINE_RECORD. It can be in a header file that multiple source
50 files share if those source files need to use the tnf_type being
51 defined. The TNF_DEFINE_RECORD should only appear in one of the source
52 files.
53 The TNF_DEFINE_RECORD macro interface defines a function as well as a
56 couple of data structures. Hence, this interface has to be used in a
57 source file (.c or .cc file) at file scope and not inside a function.
58 Note that there is no semicolon after the TNF_DEFINE_RECORD interface.
61 Having one will generate a compiler warning.
62 Compiling with the preprocessor option -DNPROBE or with the preproces‐
65 sor control statement #define NPROBE ahead of the #include
66 <tnf/probe.h> statement, will stop the TNF type extension code from
67 being compiled into the program.
68 The c_type argument must be a C struct type. It is the template from
71 which the new tnf_type is being created. Not all elements of the C
72 struct need be provided in the TNF type being defined.
73 The tnf_type argument is the name being given to the newly created
76 type. Use of this interface uses the name space prefixed by tnf_type.
77 If a new type called "xxx_type" is defined by a library, then the
78 library should not use "xxx_type" as a prefix in any other symbols it
79 defines. The policy on managing the type name space is the same as man‐
80 aging any other name space in a library; that is, prefix any new TNF
81 types by the unique prefix that the rest of the symbols in the library
82 use. This would prevent name space collisions when linking multiple
83 libraries that define new TNF types. For example, if a library libpal‐
84 loc.so uses the prefix "pal" for all symbols it defines, then it should
85 also use the prefix "pal" for all new TNF types being defined.
86 The tnf_member_type_n argument is the TNF type of the nth provided mem‐
89 ber of the C structure.
90 The tnf_member_name_n argument is the name of the nth provided member
93 of the C structure.
94
96 Example 1 Defining and using a TNF type.
97 The following example demonstrates how a new TNF type is defined and
100 used in a probe. This code is assumed to be part of a fictitious
101 library called "libpalloc.so" which uses the prefix "pal" for all it's
102 symbols.
103 #include <tnf/probe.h>
106 typedef struct pal_header {
107 long size;
108 char * descriptor;
109 struct pal_header *next;
110 } pal_header_t;
111 TNF_DECLARE_RECORD(pal_header_t, pal_tnf_header);
112 TNF_DEFINE_RECORD_2(pal_header_t, pal_tnf_header,
113 tnf_long, size,
114 tnf_string, descriptor)
115 /*
116 * Note: name space prefixed by pal_tnf_header should not
117 * be used by this client anymore.
118 */
119 void
120 pal_free(pal_header_t *header_p)
121 {
122 int state;
123 TNF_PROBE_2(pal_free_start, "palloc pal_free",
124 "sunw%debug entering pal_free",
125 tnf_long, state_var, state,
126 pal_tnf_header, header_var, header_p);
127 . . .
128 }
129
132 See attributes(5) for descriptions of the following attributes:
133 ┌─────────────────────────────┬─────────────────────────────┐
138 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
139 ├─────────────────────────────┼─────────────────────────────┤
140 │Availability │SUNWtnfd │
141 ├─────────────────────────────┼─────────────────────────────┤
142 │MT-Level │MT-Safe │
143 └─────────────────────────────┴─────────────────────────────┘
144
146 prex(1), tnfdump(1), TNF_PROBE(3TNF), tnf_process_disable(3TNF),
147 attributes(5)
148
150 It is possible to make a tnf_type definition be recursive or mutually
151 recursive e.g. a structure that uses the "next" field to point to
152 itself (a linked list). If such a structure is sent in to a
153 TNF_PROBE(3TNF), then the entire linked list will be logged to the
154 trace file (until the "next" field is NULL). But, if the list is circu‐
155 lar, it will result in an infinite loop. To break the recursion, either
156 do not include the "next" field in the tnf_type, or define the type
157 of the "next" member as tnf_opaque.
158SunOS 5.11 31 Dec 1996 TNF_DECLARE_RECORD(3TNF)