1tnfctl_probe_state_get(3TNF) TNF Library Functionstnfctl_probe_state_get(3TNF)
2
6 tnfctl_probe_state_get, tnfctl_probe_enable, tnfctl_probe_disable,
7 tnfctl_probe_trace, tnfctl_probe_untrace, tnfctl_probe_connect,
8 tnfctl_probe_disconnect_all - interfaces to query and to change the
9 state of a probe
10
12 cc [ flag ... ] file ... -ltnfctl [ library ... ]
13 #include <tnf/tnfctl.h>
14 tnfctl_errcode_t tnfctl_probe_state_get(tnfctl_handle_t *hndl,
16 tnfctl_probe_t *probe_hndl, tnfctl_probe_state_t *state);
17 tnfctl_errcode_t tnfctl_probe_enable(tnfctl_handle_t *hndl,
20 tnfctl_probe_t *probe_hndl, void *ignored);
21 tnfctl_errcode_t tnfctl_probe_disable(tnfctl_handle_t *hndl,
24 tnfctl_probe_t *probe_hndl, void *ignored);
25 tnfctl_errcode_t tnfctl_probe_trace(tnfctl_handle_t *hndl,
28 tnfctl_probe_t *probe_hndl, void *ignored);
29 tnfctl_errcode_t tnfctl_probe_untrace(tnfctl_handle_t *hndl,
32 tnfctl_probe_t *probe_hndl, void *ignored);
33 tnfctl_errcode_t tnfctl_probe_disconnect_all(tnfctl_handle_t *hndl,
36 tnfctl_probe_t *probe_hndl, void *ignored);
37 tnfctl_errcode_t tnfctl_probe_connect(tnfctl_handle_t *hndl,
40 tnfctl_probe_t *probe_hndl, const char *lib_base_name,
41 const char *func_name);
42
45 tnfctl_probe_state_get() returns the state of the probe specified by
46 probe_hndl in the process or kernel specified by hndl. The user will
47 pass these in to an apply iterator. The caller must also allocate state
48 and pass in a pointer to it. The semantics of the individual members
49 of state are:
50 id The unique integer assigned to this probe.
52 This number does not change over the lifetime
53 of this probe. A probe_hndl can be obtained
54 by using the calls tnfctl_apply(), tan‐
55 fctl_apply_ids(), or tnfctl_register_funcs().
56 attr_string A string that consists of attribute value
59 pairs separated by semicolons. For the syn‐
60 tax of this string, see the syntax of the
61 detail argument of the TNF_PROBE(3TNF) macro.
62 The attributes name, slots, keys, file, and
63 line are defined for every probe. Additional
64 user-defined attributes can be added by using
65 the detail argument of the TNF_PROBE(3TNF)
66 macro. An example of attr_string follows:
67 "name pageout;slots vnode pages_pageout ;
69 keys vm pageio io;file vm.c;line 25;"
70 enabled B_TRUE if the probe is enabled, or B_FALSE
74 if the probe is disabled. Probes are disabled
75 by default. Use tnfctl_probe_enable() or
76 tnfctl_probe_disable() to change this state.
77 traced B_TRUE if the probe is traced, or B_FALSE if
80 the probe is not traced. Probes in user pro‐
81 cesses are traced by default. Kernel probes
82 are untraced by default. Use
83 tnfctl_probe_trace() or
84 tnfctl_probe_untrace() to change this state.
85 new_probe B_TRUE if this is a new probe brought in
88 since the last change in libraries. See
89 dlopen(3C) or dlclose(3C). Otherwise, the
90 value of new_probe will be B_FALSE. This
91 field is not meaningful for kernel probe
92 control.
93 obj_name The name of the shared object or executable
96 in which the probe is located. This string
97 can be freed, so the client should make a
98 copy of the string if it needs to be saved
99 for use by other libtnfctl interfaces. In
100 kernel mode, this string is always NULL.
101 func_names A null-terminated array of pointers to
104 strings that contain the names of functions
105 connected to this probe. Whenever an enabled
106 probe is encountered at runtime, these func‐
107 tions are executed. This array also will be
108 freed by the library when the state of the
109 probe changes. Use tnfctl_probe_connect() or
110 tnfctl_probe_disconnect_all() to change this
111 state.
112 func_addrs A null-terminated array of pointers to
115 addresses of functions in the target image
116 connected to this probe. This array also
117 will be freed by the library when the state
118 of the probe changes.
119 client_registered_data Data that was registered by the client for
122 this probe by the creator function in
123 tnfctl_register_funcs(3TNF).
124 tnfctl_probe_enable(), tnfctl_probe_disable(), tnfctl_probe_trace(),
128 tnfctl_probe_untrace(), and tnfctl_probe_disconnect_all() ignore the
129 last argument. This convenient feature permits these functions to be
130 used in the probe_op field of tnfctl_probe_apply(3TNF) and
131 tnfctl_probe_apply_ids(3TNF). tnfctl_probe_enable() enables the probe
132 specified by probe_hndl. This is the master switch on a probe. A probe
133 does not perform any action until it is enabled.
134 tnfctl_probe_disable() disables the probe specified by probe_hndl.
137 tnfctl_probe_trace() turns on tracing for the probe specified by
140 probe_hndl. Probes emit a trace record only if the probe is traced.
141 tnfctl_probe_untrace() turns off tracing for the probe specified by
144 probe_hndl. This is useful if you want to connect probe functions to a
145 probe without tracing it.
146 tnfctl_probe_connect() connects the function func_name which exists in
149 the library lib_base_name, to the probe specified by probe_hndl.
150 tnfctl_probe_connect() returns an error code if used on a kernel tnfctl
151 handle. lib_base_name is the base name (not a path) of the library. If
152 it is NULL, and multiple functions in the target process match
153 func_name, one of the matching functions is chosen arbitrarily. A probe
154 function is a function that is in the target's address space and is
155 written to a certain specification. The specification is not cur‐
156 rently published.
157 tnf_probe_debug() is one function exported by libtnfprobe.so.1 and is
160 the debug function that prex(1) uses. When the debug function is exe‐
161 cuted, it prints out the probe arguments and the value of the
162 sunw%debug attribute of the probe to stderr.
163 tnfctl_probe_disconnect_all() disconnects all probe functions from the
166 probe specified by probe_hndl.
167 Note that no libtnfctl call returns a probe handle (tnfctl_probe_t),
170 yet each of the routines described here takes a probe_hndl as an argu‐
171 ment. These routines may be used by passing them to one of the
172 tnfctl_probe_apply(3TNF) iterators as the "op" argument. Alternatively,
173 probe handles may be obtained and saved by a user's "op" function, and
174 they can be passed later as the probe_hndl argument when using any of
175 the functions described here.
176
178 tnfctl_probe_state_get(), tnfctl_probe_enable(), tnfctl_probe_dis‐
179 able(), tnfctl_probe_trace(), tnfctl_probe_untrace(), tnfctl_probe_dis‐
180 connect_all() and tnfctl_probe_connect() return TNFCTL_ERR_NONE upon
181 success.
182
184 The following error codes apply to tnfctl_probe_state_get():
185 TNFCTL_ERR_INVALIDPROBE probe_hndl is no longer valid. The library
187 that the probe was in could have been dynam‐
188 ically closed by dlclose(3C).
189 The following error codes apply to tnfctl_probe_enable(),
193 tnfctl_probe_disable(), tnfctl_probe_trace(), tnfctl_probe_untrace(),
194 and tnfctl_probe_disconnect_all()
195 TNFCTL_ERR_INVALIDPROBE probe_hndl is no longer valid. The library
197 that the probe was in could have been dynam‐
198 ically closed by dlclose(3C).
199 TNFCTL_ERR_BUFBROKEN Cannot do probe operations because tracing
202 is broken in the target.
203 TNFCTL_ERR_NOBUF Cannot do probe operations until a buffer is
206 allocated. See tnfctl_buffer_alloc(3TNF).
207 This error code does not apply to kernel
208 probe control.
209 The following error codes apply to tnfctl_probe_connect():
213 TNFCTL_ERR_INVALIDPROBE probe_hndl is no longer valid. The library
215 that the probe was in could have been dynam‐
216 ically closed by dlclose(3C).
217 TNFCTL_ERR_BADARG The handle is a kernel handle, or func_name
220 could not be found.
221 TNFCTL_ERR_BUFBROKEN Cannot do probe operations because tracing
224 is broken in the target.
225 TNFCTL_ERR_NOBUF Cannot do probe operations until a buffer is
228 allocated. See tnfctl_buffer_alloc(3TNF).
229
232 See attributes(5) for description of the following attributes:
233 ┌─────────────────────────────┬─────────────────────────────┐
238 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
239 ├─────────────────────────────┼─────────────────────────────┤
240 │Availability │SUNWtnfc │
241 ├─────────────────────────────┼─────────────────────────────┤
242 │MT Level │MT-Safe │
243 └─────────────────────────────┴─────────────────────────────┘
244
246 prex(1), TNF_PROBE(3TNF), libtnfctl(3TNF), tnfctl_check_libs(3TNF),
247 tnfctl_continue(3TNF), tnfctl_probe_apply(3TNF),
248 tnfctl_probe_apply_ids(3TNF), tracing(3TNF), tnf_kernel_probes(4),
249 attributes(5)
250SunOS 5.11 1 Mar 2004 tnfctl_probe_state_get(3TNF)