NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO | NOTES
#include <tnf/tnfctl.h> cc [ flag ... ] file ... -ltnfctl [ library ... ]
libtnfctl is a library that provides an API to control TNF ("Trace Normal Form") probes within a process or the kernel. See tracing(3X) for an overview of the Solaris tracing architecture. The client of libtnfctl controls probes in one of four modes:
The target is the controlling process itself; that is, the client controls its own probes.
The target is a separate process; a client can either exec(2) a program or attach to a running process for probe control. libtnfctl uses proc(4) on the target process for probe and process control in this mode, and additionally provides basic process control features.
The target is a separate process, but the controlling process is already using proc(4) to control the target, and hence libtnfctl cannot use those interfaces directly. Use this mode to control probes from within a debugger. In this mode, the client must provide a set of functions that libtnfctl can use to query and update the target process.
The target is the Solaris kernel.
A process is controlled "externally" if it is being controlled in either direct mode or indirect mode. Alternatively, a process is controlled "internally" when it uses internal mode to control its own probes.
There can be only one client at a time doing probe control on a given process. Therefore, it is not possible for a process to be controlled internally while it is being controlled externally. It is also not possible to have a process controlled by multiple external processes. Similarly, there can be only one process at a time doing kernel probe control. Note, however, that while a given target may only be controlled by one libtnfctl client, a single client may control an arbitrary number of targets. That is, it is possible for a process to simultaneously control its own probes, probes in other processes, and probes in the kernel.
The following tables denotes the modes applicable to all libtnfctl interfaces (INT = internal mode; D = direct mode; IND = indirect mode; K = kernel mode).
These interfaces create handles in the specified modes:
tnfctl_internal_open() | INT | |||
tnfctl_exec_open() | D | |||
tnfctl_pid_open() | D | |||
tnfctl_indirect_open() | IND | |||
tnfctl_kernel_open() | K |
These interfaces are used with the specified modes:
tnfctl_continue() | D | |||
tnfctl_probe_connect() | INT | D | IND | |
tnfctl_probe_disconnect_all () | INT | D | IND | |
tnfctl_trace_attrs_get() | INT | D | IND | K |
tnfctl_buffer_alloc() | INT | D | IND | K |
tnfctl_register_funcs() | INT | D | IND | K |
tnfctl_probe_apply() | INT | D | IND | K |
tnfctl_probe_apply_ids() | INT | D | IND | K |
tnfctl_probe_state_get () | INT | D | IND | K |
tnfctl_probe_enable() | INT | D | IND | K |
tnfctl_probe_disable() | INT | D | IND | K |
tnfctl_probe_trace() | INT | D | IND | K |
tnfctl_probe_untrace() | INT | D | IND | K |
tnfctl_check_libs() | INT | D | IND | K |
tnfctl_close() | INT | D | IND | K |
tnfctl_strerror() | INT | D | IND | K |
tnfctl_buffer_dealloc() | K | |||
tnfctl_trace_state_set() | K | |||
tnfctl_filter_state_set() | K | |||
tnfctl_filter_list_get() | K | |||
tnfctl_filter_list_add() | K | |||
tnfctl_filter_list_delete() | K |
When using libtnfctl, the first task is to create a handle for controlling probes. Function tnfctl_internal_open() creates an internal mode handle for controlling probes in the same process, as described above. Functions tnfctl_pid_open() and tnfctl_exec_open() create handles in direct mode. tnfctl_indirect_open() creates an indirect mode handle, and tnfctl_kernel_open() creates a kernel mode handle. A handle is required for use in nearly all other libtnfctl functions. tnfctl_close() releases the resources associated with a handle.
tnfctl_continue() is used in direct mode to resume execution of the target process.
tnfctl_buffer_alloc() allocates a trace file or, in kernel mode, a trace buffer.
tnfctl_probe_apply() and tnfctl_probe_apply_ids() call a specified function for each probe or for a designated set of probes.
tnfctl_register_funcs() registers functions to be called whenever new probes are seen or probes have disappeared, providing an opportunity to do one-time processing for each probe.
tnfctl_check_libs() is used primarily in indirect mode to check whether any new probes have appeared, that is, they have been made available by dlopen(3X), or have disappeared, that is, they have disassociated from the process by dlclose(3X).
tnfctl_probe_enable() and tnfctl_probe_disable() control whether the probe, when hit, will be ignored.
tnfctl_probe_trace() and tnfctl_probe_untrace() control whether an enabled probe, when hit, will cause an entry to be made in the trace file.
tnfctl_probe_connect() and tnfctl_probe_disconnect_all() control which functions, if any, are called when an enabled probe is hit.
tnfctl_probe_state_get() returns information about the status of a probe, such as whether it is currently enabled.
tnfctl_trace_attrs_get() returns information about the tracing session, such as the size of the trace buffer or trace file.
tnfctl_strerror() maps a tnfctl error code to a string, for reporting purposes.
The remaining interfaces apply only to kernel mode.
tnfctl_trace_state_set() controls the master switch for kernel tracing. See prex(1) for more details.
tnfctl_filter_state_set(), tnfctl_filter_list_get(), tnfctl_filter_list_add(), and tnfctl_filter_list_delete() allow a set of processes to be specified for which probes will not be ignored when hit. This prevents kernel activity caused by uninteresting processes from cluttering up the kernel's trace buffer.
tnfctl_buffer_dealloc() deallocates the kernel's internal trace buffer.
TNFCTL_ERR_NONE is returned upon success.
The error codes for libtnfctl are:
Permission denied.
The target process completed.
A memory allocation failure occurred.
An internal error occurred.
The requested trace size is too small.
The requested trace size is too big.
Bad input argument.
The target is not a dynamic executable.
libtnfprobe.so not linked in target.
Tracing is broken in the target.
A buffer already exists.
No buffer exists.
Cannot deallocate buffer.
No such target process exists.
File not found.
Cannot attach to process or kernel because it is already tracing.
Probe no longer valid.
Error code reserved for user.
Error code reserved for user.
Error code reserved for user.
Error code reserved for user.
Error code reserved for user.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Availability | SUNWtnfc |
MT Level | MT-Safe with exceptions |
prex(1), exec(2), dlclose(3X), dlopen(3X), TNF_PROBE(3X), tnfctl_buffer_alloc(3X ), tnfctl_buffer_dealloc(3X), tnfctl_check_libs(3X), tnfctl_close(3X), tnfctl_continue(3X), tnfctl_internal_open(3X), tnfctl_exec_open(3X), tnfctl_filter_list_add(3X), tnfctl_filter_list_delete(3X), tnfctl_filter_list_get(3X), tnfctl_filter_state_set(3X), tnfctl_kernel_open(3X), tnfctl_pid_open(3X), tnfctl_probe_apply(3X), tnfctl_probe_apply_ids(3X), tnfctl_probe_connect(3X), tnfctl_probe_disable( 3X), tnfctl_probe_enable(3X), tnfctl_probe_state_get(3X), tnfctl_probe_trace(3X), tnfctl_probe_untrace(3X), tnfctl_indirect_open(3X), tnfctl_register_funcs(3X), tnfctl_strerror(3X), tnfctl_trace_attrs_get(3X), tnfctl_trace_state_set(3X), libtnfctl(4), proc(4), attributes(5)
This API is MT-Safe. Multiple threads may concurrently operate on independent tnfctl handles, which is the typical behavior expected. libtnfctl does not support multiple threads operating on the same tnfctl handle. If this is desired, it is the client's responsibility to implement locking to ensure that two threads that use the same tnfctl handle are not simultaneously in a libtnfctl interface.
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO | NOTES