1libtnfctl(3TNF) TNF Library Functions libtnfctl(3TNF)
2
6 libtnfctl - library for TNF probe control in a process or the kernel
7
9 cc [ flag ... ] file ... -ltnfctl [ library ... ]
10 #include <tnf/tnfctl.h>
11
14 The libtnfctl library provides an API to control TNF ("Trace Normal
15 Form") probes within a process or the kernel. See tracing(3TNF) for an
16 overview of the Solaris tracing architecture. The client of libtnfctl
17 controls probes in one of four modes:
18 internal mode The target is the controlling process itself; that is,
20 the client controls its own probes.
21 direct mode The target is a separate process; a client can either
24 exec(2) a program or attach to a running process for
25 probe control. The libtnfctl library uses proc(4) on
26 the target process for probe and process control in
27 this mode, and additionally provides basic process
28 control features.
29 indirect mode The target is a separate process, but the controlling
32 process is already using proc(4) to control the tar‐
33 get, and hence libtnfctl cannot use those interfaces
34 directly. Use this mode to control probes from within
35 a debugger. In this mode, the client must provide a
36 set of functions that libtnfctl can use to query and
37 update the target process.
38 kernel mode The target is the Solaris kernel.
41 A process is controlled "externally" if it is being controlled in
45 either direct mode or indirect mode. Alternatively, a process is con‐
46 trolled "internally" when it uses internal mode to control its own
47 probes.
48 There can be only one client at a time doing probe control on a given
51 process. Therefore, it is not possible for a process to be controlled
52 internally while it is being controlled externally. It is also not pos‐
53 sible to have a process controlled by multiple external processes. Sim‐
54 ilarly, there can be only one process at a time doing kernel probe con‐
55 trol. Note, however, that while a given target may only be controlled
56 by one libtnfctl client, a single client may control an arbitrary num‐
57 ber of targets. That is, it is possible for a process to simultaneously
58 control its own probes, probes in other processes, and probes in the
59 kernel.
60 The following tables denotes the modes applicable to all libtnfctl
63 interfaces (INT = internal mode; D = direct mode; IND = indirect mode;
64 K = kernel mode).
65 These interfaces create handles in the specified modes:
68 tnfctl_internal_open() INT
73 tnfctl_exec_open() D
74 tnfctl_pid_open() D
75 tnfctl_indirect_open() IND
76 tnfctl_kernel_open() K
77 These interfaces are used with the specified modes:
81 tnfctl_continue() D
86 tnfctl_probe_connect() INT D IND
87 tnfctl_probe_disconnect_all () INT D IND
88 tnfctl_trace_attrs_get() INT D IND K
89 tnfctl_buffer_alloc() INT D IND K
90 tnfctl_register_funcs() INT D IND K
91 tnfctl_probe_apply() INT D IND K
92 tnfctl_probe_apply_ids() INT D IND K
93 tnfctl_probe_state_get () INT D IND K
94 tnfctl_probe_enable() INT D IND K
95 tnfctl_probe_disable() INT D IND K
96 tnfctl_probe_trace() INT D IND K
97 tnfctl_probe_untrace() INT D IND K
98 tnfctl_check_libs() INT D IND K
99 tnfctl_close() INT D IND K
100 tnfctl_strerror() INT D IND K
101 tnfctl_buffer_dealloc() K
102 tnfctl_trace_state_set() K
103 tnfctl_filter_state_set() K
104 tnfctl_filter_list_get() K
105 tnfctl_filter_list_add() K
106 tnfctl_filter_list_delete() K
107 When using libtnfctl, the first task is to create a handle for control‐
111 ling probes. The tnfctl_internal_open() function creates an internal
112 mode handle for controlling probes in the same process, as described
113 above. The tnfctl_pid_open() and tnfctl_exec_open() functions create
114 handles in direct mode. The tnfctl_indirect_open() function creates an
115 indirect mode handle, and the tnfctl_kernel_open() function creates a
116 kernel mode handle. A handle is required for use in nearly all other
117 libtnfctl functions. The tnfctl_close() function releases the resources
118 associated with a handle.
119 The tnfctl_continue() function is used in direct mode to resume execu‐
122 tion of the target process.
123 The tnfctl_buffer_alloc() function allocates a trace file or, in kernel
126 mode, a trace buffer.
127 The tnfctl_probe_apply() and tnfctl_probe_apply_ids() functions call a
130 specified function for each probe or for a designated set of probes.
131 The tnfctl_register_funcs() function registers functions to be called
134 whenever new probes are seen or probes have disappeared, providing an
135 opportunity to do one-time processing for each probe.
136 The tnfctl_check_libs() function is used primarily in indirect mode to
139 check whether any new probes have appeared, that is, they have been
140 made available by dlopen(3C), or have disappeared, that is, they have
141 disassociated from the process by dlclose(3C).
142 The tnfctl_probe_enable() and tnfctl_probe_disable() functions control
145 whether the probe, when hit, will be ignored.
146 The tnfctl_probe_trace() and tnfctl_probe_untrace() functions control
149 whether an enabled probe, when hit, will cause an entry to be made in
150 the trace file.
151 The tnfctl_probe_connect() and tnfctl_probe_disconnect_all() functions
154 control which functions, if any, are called when an enabled probe is
155 hit.
156 The tnfctl_probe_state_get() function returns information about the
159 status of a probe, such as whether it is currently enabled.
160 The tnfctl_trace_attrs_get() function returns information about the
163 tracing session, such as the size of the trace buffer or trace file.
164 The tnfctl_strerror() function maps a tnfctl error code to a string,
167 for reporting purposes.
168 The remaining functions apply only to kernel mode.
171 The tnfctl_trace_state_set() function controls the master switch for
174 kernel tracing. See prex(1) for more details.
175 The tnfctl_filter_state_set(), tnfctl_filter_list_get(), tnfctl_fil‐
178 ter_list_add(), and tnfctl_filter_list_delete() functions allow a set
179 of processes to be specified for which probes will not be ignored when
180 hit. This prevents kernel activity caused by uninteresting processes
181 from cluttering up the kernel's trace buffer.
182 The tnfctl_buffer_dealloc() function deallocates the kernel's internal
185 trace buffer.
186
188 Upon successful completion, these functions returnTNFCTL_ERR_NONE.
189
191 The error codes for libtnfctl are:
192 TNFCTL_ERR_ACCES Permission denied.
194 TNFCTL_ERR_NOTARGET The target process completed.
197 TNFCTL_ERR_ALLOCFAIL A memory allocation failure occurred.
200 TNFCTL_ERR_INTERNAL An internal error occurred.
203 TNFCTL_ERR_SIZETOOSMALL The requested trace size is too small.
206 TNFCTL_ERR_SIZETOOBIG The requested trace size is too big.
209 TNFCTL_ERR_BADARG Bad input argument.
212 TNFCTL_ERR_NOTDYNAMIC The target is not a dynamic executable.
215 TNFCTL_ERR_NOLIBTNFPROBE libtnfprobe.so not linked in target.
218 TNFCTL_ERR_BUFBROKEN Tracing is broken in the target.
221 TNFCTL_ERR_BUFEXISTS A buffer already exists.
224 TNFCTL_ERR_NOBUF No buffer exists.
227 TNFCTL_ERR_BADDEALLOC Cannot deallocate buffer.
230 TNFCTL_ERR_NOPROCESS No such target process exists.
233 TNFCTL_ERR_FILENOTFOUND File not found.
236 TNFCTL_ERR_BUSY Cannot attach to process or kernel because
239 it is already tracing.
240 TNFCTL_ERR_INVALIDPROBE Probe no longer valid.
243 TNFCTL_ERR_USR1 Error code reserved for user.
246 TNFCTL_ERR_USR2 Error code reserved for user.
249 TNFCTL_ERR_USR3 Error code reserved for user.
252 TNFCTL_ERR_USR4 Error code reserved for user.
255 TNFCTL_ERR_USR5 Error code reserved for user.
258
261 See attributes(5) for descriptions of the following attributes:
262 ┌─────────────────────────────┬─────────────────────────────┐
267 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
268 ├─────────────────────────────┼─────────────────────────────┤
269 │Availability │SUNWtnfc │
270 ├─────────────────────────────┼─────────────────────────────┤
271 │MT Level │MT-Safe with exceptions │
272 └─────────────────────────────┴─────────────────────────────┘
273
275 prex(1), exec(2), dlclose(3C), dlopen(3C), TNF_PROBE(3TNF), tnfctl_buf‐
276 fer_alloc(3TNF), tnfctl_buffer_dealloc(3TNF), tnfctl_check_libs(3TNF),
277 tnfctl_close(3TNF), tnfctl_continue(3TNF), tnfctl_internal_open(3TNF),
278 tnfctl_exec_open(3TNF), tnfctl_filter_list_add(3TNF), tnfctl_fil‐
279 ter_list_delete(3TNF), tnfctl_filter_list_get(3TNF), tnfctl_fil‐
280 ter_state_set(3TNF), tnfctl_kernel_open(3TNF), tnfctl_pid_open(3TNF),
281 tnfctl_probe_apply(3TNF), tnfctl_probe_apply_ids(3TNF),
282 tnfctl_probe_connect(3TNF), tnfctl_probe_disable(3TNF),
283 tnfctl_probe_enable(3TNF), tnfctl_probe_state_get(3TNF),
284 tnfctl_probe_trace(3TNF), tnfctl_probe_untrace(3TNF), tnfctl_indi‐
285 rect_open(3TNF), tnfctl_register_funcs(3TNF), tnfctl_strerror(3TNF),
286 tnfctl_trace_attrs_get(3TNF), tnfctl_trace_state_set(3TNF), libtn‐
287 fctl(3LIB), proc(4), attributes(5)
288 Linker and Libraries Guide
291
293 This API is MT-Safe. Multiple threads may concurrently operate on
294 independent tnfctl handles, which is the typical behavior expected.
295 The libtnfctl library does not support multiple threads operating on
296 the same tnfctl handle. If this is desired, it is the client's respon‐
297 sibility to implement locking to ensure that two threads that use the
298 same tnfctl handle are not simultaneously in a libtnfctl interface.
299SunOS 5.11 1 Mar 2004 libtnfctl(3TNF)