| blob | bd02d743ee35bfbfc35920f8bc4caf5adefc33dc |
1 '\" te
2 .\" Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH LIBTNFCTL 3TNF "Mar 1, 2004"
7 .SH NAME
8 libtnfctl \- library for TNF probe control in a process or the kernel
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ]
13 #include <tnf/tnfctl.h>
14 .fi
16 .SH DESCRIPTION
17 .sp
18 .LP
19 The \fBlibtnfctl\fR library provides an \fBAPI\fR to control \fBTNF\fR
20 ("Trace Normal Form") probes within a process or the kernel. See
21 \fBtracing\fR(3TNF) for an overview of the Solaris tracing architecture. The
22 client of \fBlibtnfctl\fR controls probes in one of four modes:
23 .sp
24 .ne 2
25 .na
26 \fBinternal mode\fR
27 .ad
28 .RS 17n
29 The target is the controlling process itself; that is, the client controls its
30 own probes.
31 .RE
33 .sp
34 .ne 2
35 .na
36 \fBdirect mode\fR
37 .ad
38 .RS 17n
39 The target is a separate process; a client can either \fBexec\fR(2) a program
40 or attach to a running process for probe control. The \fBlibtnfctl\fR library
41 uses \fBproc\fR(4) on the target process for probe and process control in this
42 mode, and additionally provides basic process control features.
43 .RE
45 .sp
46 .ne 2
47 .na
48 \fBindirect mode\fR
49 .ad
50 .RS 17n
51 The target is a separate process, but the controlling process is already using
52 \fBproc\fR(4) to control the target, and hence \fBlibtnfctl\fR cannot use
53 those interfaces directly. Use this mode to control probes from within a
54 debugger. In this mode, the client must provide a set of functions that
55 \fBlibtnfctl\fR can use to query and update the target process.
56 .RE
58 .sp
59 .ne 2
60 .na
61 \fBkernel mode\fR
62 .ad
63 .RS 17n
64 The target is the Solaris kernel.
65 .RE
67 .sp
68 .LP
69 A process is controlled "externally" if it is being controlled in either direct
70 mode or indirect mode. Alternatively, a process is controlled "internally" when
71 it uses internal mode to control its own probes.
72 .sp
73 .LP
74 There can be only one client at a time doing probe control on a given process.
75 Therefore, it is not possible for a process to be controlled internally while
76 it is being controlled externally. It is also not possible to have a process
77 controlled by multiple external processes. Similarly, there can be only one
78 process at a time doing kernel probe control. Note, however, that while a given
79 target may only be controlled by one \fBlibtnfctl\fR client, a single client
80 may control an arbitrary number of targets. That is, it is possible for a
81 process to simultaneously control its own probes, probes in other processes,
82 and probes in the kernel.
83 .sp
84 .LP
85 The following tables denotes the modes applicable to all \fBlibtnfctl\fR
86 interfaces (INT = internal mode; D = direct mode; IND = indirect mode; K =
87 kernel mode).
88 .sp
89 .LP
90 These interfaces create handles in the specified modes:
91 .sp
93 .sp
94 .TS
95 l l l l l
96 l l l l l .
97 \fBtnfctl_internal_open()\fR INT
98 \fBtnfctl_exec_open()\fR D
99 \fBtnfctl_pid_open()\fR D
100 \fBtnfctl_indirect_open()\fR IND
101 \fBtnfctl_kernel_open()\fR K
102 .TE
104 .sp
105 .LP
106 These interfaces are used with the specified modes:
107 .sp
109 .sp
110 .TS
111 l l l l l
112 l l l l l .
113 \fBtnfctl_continue()\fR D
114 \fBtnfctl_probe_connect()\fR INT D IND
115 \fBtnfctl_probe_disconnect_all ()\fR INT D IND
116 \fBtnfctl_trace_attrs_get()\fR INT D IND K
117 \fBtnfctl_buffer_alloc()\fR INT D IND K
118 \fBtnfctl_register_funcs()\fR INT D IND K
119 \fBtnfctl_probe_apply()\fR INT D IND K
120 \fBtnfctl_probe_apply_ids()\fR INT D IND K
121 \fBtnfctl_probe_state_get ()\fR INT D IND K
122 \fBtnfctl_probe_enable()\fR INT D IND K
123 \fBtnfctl_probe_disable()\fR INT D IND K
124 \fBtnfctl_probe_trace()\fR INT D IND K
125 \fBtnfctl_probe_untrace()\fR INT D IND K
126 \fBtnfctl_check_libs()\fR INT D IND K
127 \fBtnfctl_close()\fR INT D IND K
128 \fBtnfctl_strerror()\fR INT D IND K
129 \fBtnfctl_buffer_dealloc()\fR K
130 \fBtnfctl_trace_state_set()\fR K
131 \fBtnfctl_filter_state_set()\fR K
132 \fBtnfctl_filter_list_get()\fR K
133 \fBtnfctl_filter_list_add()\fR K
134 \fBtnfctl_filter_list_delete()\fR K
135 .TE
137 .sp
138 .LP
139 When using \fBlibtnfctl\fR, the first task is to create a handle for
140 controlling probes. The \fBtnfctl_internal_open()\fR function creates an
141 internal mode handle for controlling probes in the same process, as described
142 above. The \fBtnfctl_pid_open()\fR and \fBtnfctl_exec_open()\fR functions
143 create handles in direct mode. The \fBtnfctl_indirect_open()\fR function
144 creates an indirect mode handle, and the \fBtnfctl_kernel_open()\fR function
145 creates a kernel mode handle. A handle is required for use in nearly all other
146 \fBlibtnfctl\fR functions. The \fBtnfctl_close()\fR function releases the
147 resources associated with a handle.
148 .sp
149 .LP
150 The \fBtnfctl_continue()\fR function is used in direct mode to resume execution
151 of the target process.
152 .sp
153 .LP
154 The \fBtnfctl_buffer_alloc()\fR function allocates a trace file or, in kernel
155 mode, a trace buffer.
156 .sp
157 .LP
158 The \fBtnfctl_probe_apply()\fR and \fBtnfctl_probe_apply_ids()\fR functions
159 call a specified function for each probe or for a designated set of probes.
160 .sp
161 .LP
162 The \fBtnfctl_register_funcs()\fR function registers functions to be called
163 whenever new probes are seen or probes have disappeared, providing an
164 opportunity to do one-time processing for each probe.
165 .sp
166 .LP
167 The \fBtnfctl_check_libs()\fR function is used primarily in indirect mode to
168 check whether any new probes have appeared, that is, they have been made
169 available by \fBdlopen\fR(3C), or have disappeared, that is, they have
170 disassociated from the process by \fBdlclose\fR(3C).
171 .sp
172 .LP
173 The \fBtnfctl_probe_enable()\fR and \fBtnfctl_probe_disable()\fR functions
174 control whether the probe, when hit, will be ignored.
175 .sp
176 .LP
177 The \fBtnfctl_probe_trace()\fR and \fBtnfctl_probe_untrace()\fR functions
178 control whether an enabled probe, when hit, will cause an entry to be made in
179 the trace file.
180 .sp
181 .LP
182 The \fBtnfctl_probe_connect()\fR and \fBtnfctl_probe_disconnect_all()\fR
183 functions control which functions, if any, are called when an enabled probe is
184 hit.
185 .sp
186 .LP
187 The \fBtnfctl_probe_state_get()\fR function returns information about the
188 status of a probe, such as whether it is currently enabled.
189 .sp
190 .LP
191 The \fBtnfctl_trace_attrs_get()\fR function returns information about the
192 tracing session, such as the size of the trace buffer or trace file.
193 .sp
194 .LP
195 The \fBtnfctl_strerror()\fR function maps a \fBtnfctl\fR error code to a
196 string, for reporting purposes.
197 .sp
198 .LP
199 The remaining functions apply only to kernel mode.
200 .sp
201 .LP
202 The \fBtnfctl_trace_state_set()\fR function controls the master switch for
203 kernel tracing. See \fBprex\fR(1) for more details.
204 .sp
205 .LP
206 The \fBtnfctl_filter_state_set()\fR, \fBtnfctl_filter_list_get()\fR,
207 \fBtnfctl_filter_list_add()\fR, and \fBtnfctl_filter_list_delete()\fR functions
208 allow a set of processes to be specified for which probes will not be ignored
209 when hit. This prevents kernel activity caused by uninteresting processes from
210 cluttering up the kernel's trace buffer.
211 .sp
212 .LP
213 The \fBtnfctl_buffer_dealloc()\fR function deallocates the kernel's internal
214 trace buffer.
215 .SH RETURN VALUES
216 .sp
217 .LP
218 Upon successful completion, these functions return\fBTNFCTL_ERR_NONE\fR.
219 .SH ERRORS
220 .sp
221 .LP
222 The error codes for \fBlibtnfctl\fR are:
223 .sp
224 .ne 2
225 .na
226 \fB\fBTNFCTL_ERR_ACCES\fR\fR
227 .ad
228 .RS 28n
229 Permission denied.
230 .RE
232 .sp
233 .ne 2
234 .na
235 \fB\fBTNFCTL_ERR_NOTARGET\fR\fR
236 .ad
237 .RS 28n
238 The target process completed.
239 .RE
241 .sp
242 .ne 2
243 .na
244 \fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR
245 .ad
246 .RS 28n
247 A memory allocation failure occurred.
248 .RE
250 .sp
251 .ne 2
252 .na
253 \fB\fBTNFCTL_ERR_INTERNAL\fR\fR
254 .ad
255 .RS 28n
256 An internal error occurred.
257 .RE
259 .sp
260 .ne 2
261 .na
262 \fB\fBTNFCTL_ERR_SIZETOOSMALL\fR\fR
263 .ad
264 .RS 28n
265 The requested trace size is too small.
266 .RE
268 .sp
269 .ne 2
270 .na
271 \fB\fBTNFCTL_ERR_SIZETOOBIG\fR\fR
272 .ad
273 .RS 28n
274 The requested trace size is too big.
275 .RE
277 .sp
278 .ne 2
279 .na
280 \fB\fBTNFCTL_ERR_BADARG\fR\fR
281 .ad
282 .RS 28n
283 Bad input argument.
284 .RE
286 .sp
287 .ne 2
288 .na
289 \fB\fBTNFCTL_ERR_NOTDYNAMIC\fR\fR
290 .ad
291 .RS 28n
292 The target is not a dynamic executable.
293 .RE
295 .sp
296 .ne 2
297 .na
298 \fB\fBTNFCTL_ERR_NOLIBTNFPROBE\fR\fR
299 .ad
300 .RS 28n
301 \fBlibtnfprobe.so\fR not linked in target.
302 .RE
304 .sp
305 .ne 2
306 .na
307 \fB\fBTNFCTL_ERR_BUFBROKEN\fR\fR
308 .ad
309 .RS 28n
310 Tracing is broken in the target.
311 .RE
313 .sp
314 .ne 2
315 .na
316 \fB\fBTNFCTL_ERR_BUFEXISTS\fR\fR
317 .ad
318 .RS 28n
319 A buffer already exists.
320 .RE
322 .sp
323 .ne 2
324 .na
325 \fB\fBTNFCTL_ERR_NOBUF\fR\fR
326 .ad
327 .RS 28n
328 No buffer exists.
329 .RE
331 .sp
332 .ne 2
333 .na
334 \fB\fBTNFCTL_ERR_BADDEALLOC\fR\fR
335 .ad
336 .RS 28n
337 Cannot deallocate buffer.
338 .RE
340 .sp
341 .ne 2
342 .na
343 \fB\fBTNFCTL_ERR_NOPROCESS\fR\fR
344 .ad
345 .RS 28n
346 No such target process exists.
347 .RE
349 .sp
350 .ne 2
351 .na
352 \fB\fBTNFCTL_ERR_FILENOTFOUND\fR\fR
353 .ad
354 .RS 28n
355 File not found.
356 .RE
358 .sp
359 .ne 2
360 .na
361 \fB\fBTNFCTL_ERR_BUSY\fR\fR
362 .ad
363 .RS 28n
364 Cannot attach to process or kernel because it is already tracing.
365 .RE
367 .sp
368 .ne 2
369 .na
370 \fB\fBTNFCTL_ERR_INVALIDPROBE\fR\fR
371 .ad
372 .RS 28n
373 Probe no longer valid.
374 .RE
376 .sp
377 .ne 2
378 .na
379 \fB\fBTNFCTL_ERR_USR1\fR\fR
380 .ad
381 .RS 28n
382 Error code reserved for user.
383 .RE
385 .sp
386 .ne 2
387 .na
388 \fB\fBTNFCTL_ERR_USR2\fR\fR
389 .ad
390 .RS 28n
391 Error code reserved for user.
392 .RE
394 .sp
395 .ne 2
396 .na
397 \fB\fBTNFCTL_ERR_USR3\fR\fR
398 .ad
399 .RS 28n
400 Error code reserved for user.
401 .RE
403 .sp
404 .ne 2
405 .na
406 \fB\fBTNFCTL_ERR_USR4\fR\fR
407 .ad
408 .RS 28n
409 Error code reserved for user.
410 .RE
412 .sp
413 .ne 2
414 .na
415 \fB\fBTNFCTL_ERR_USR5\fR\fR
416 .ad
417 .RS 28n
418 Error code reserved for user.
419 .RE
421 .SH ATTRIBUTES
422 .sp
423 .LP
424 See \fBattributes\fR(5) for descriptions of the following attributes:
425 .sp
427 .sp
428 .TS
429 box;
430 c | c
431 l | l .
432 ATTRIBUTE TYPE ATTRIBUTE VALUE
433 _
434 MT Level MT-Safe with exceptions
435 .TE
437 .SH SEE ALSO
438 .sp
439 .LP
440 \fBprex\fR(1), \fBexec\fR(2), \fBdlclose\fR(3C), \fBdlopen\fR(3C),
441 \fBTNF_PROBE\fR(3TNF), \fBtnfctl_buffer_alloc\fR(3TNF),
442 \fBtnfctl_buffer_dealloc\fR(3TNF), \fBtnfctl_check_libs\fR(3TNF),
443 \fBtnfctl_close\fR(3TNF), \fBtnfctl_continue\fR(3TNF),
444 \fBtnfctl_internal_open\fR(3TNF), \fBtnfctl_exec_open\fR(3TNF),
445 \fBtnfctl_filter_list_add\fR(3TNF), \fBtnfctl_filter_list_delete\fR(3TNF),
446 \fBtnfctl_filter_list_get\fR(3TNF), \fBtnfctl_filter_state_set\fR(3TNF),
447 \fBtnfctl_kernel_open\fR(3TNF), \fBtnfctl_pid_open\fR(3TNF),
448 \fBtnfctl_probe_apply\fR(3TNF), \fBtnfctl_probe_apply_ids\fR(3TNF),
449 \fBtnfctl_probe_connect\fR(3TNF), \fBtnfctl_probe_disable\fR(3TNF),
450 \fBtnfctl_probe_enable\fR(3TNF), \fBtnfctl_probe_state_get\fR(3TNF),
451 \fBtnfctl_probe_trace\fR(3TNF), \fBtnfctl_probe_untrace\fR(3TNF),
452 \fBtnfctl_indirect_open\fR(3TNF), \fBtnfctl_register_funcs\fR(3TNF),
453 \fBtnfctl_strerror\fR(3TNF), \fBtnfctl_trace_attrs_get\fR(3TNF),
454 \fBtnfctl_trace_state_set\fR(3TNF), \fBlibtnfctl\fR(3LIB), \fBproc\fR(4),
455 \fBattributes\fR(5)
456 .sp
457 .LP
458 \fILinker and Libraries Guide\fR
459 .SH NOTES
460 .sp
461 .LP
462 This \fBAPI\fR is MT-Safe. Multiple threads may concurrently operate on
463 independent \fBtnfctl\fR handles, which is the typical behavior expected. The
464 \fBlibtnfctl\fR library does not support multiple threads operating on the same
465 \fBtnfctl\fR handle. If this is desired, it is the client's responsibility to
466 implement locking to ensure that two threads that use the same \fBtnfctl\fR
467 handle are not simultaneously in a \fBlibtnfctl\fR interface.