LIBTNFCTL(3TNF) | TNF Library Functions | LIBTNFCTL(3TNF) |
cc [ flag ... ] file ... -ltnfctl [ library ... ] #include <tnf/tnfctl.h>
internal mode
direct mode
indirect mode
kernel mode
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. The tnfctl_internal_open() function creates an internal mode handle for controlling probes in the same process, as described above. The tnfctl_pid_open() and tnfctl_exec_open() functions create handles in direct mode. The tnfctl_indirect_open() function creates an indirect mode handle, and the tnfctl_kernel_open() function creates a kernel mode handle. A handle is required for use in nearly all other libtnfctl functions. The tnfctl_close() function releases the resources associated with a handle.
The tnfctl_continue() function is used in direct mode to resume execution of the target process.
The tnfctl_buffer_alloc() function allocates a trace file or, in kernel mode, a trace buffer.
The tnfctl_probe_apply() and tnfctl_probe_apply_ids() functions call a specified function for each probe or for a designated set of probes.
The tnfctl_register_funcs() function 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.
The tnfctl_check_libs() function is used primarily in indirect mode to check whether any new probes have appeared, that is, they have been made available by dlopen(3C), or have disappeared, that is, they have disassociated from the process by dlclose(3C).
The tnfctl_probe_enable() and tnfctl_probe_disable() functions control whether the probe, when hit, will be ignored.
The tnfctl_probe_trace() and tnfctl_probe_untrace() functions control whether an enabled probe, when hit, will cause an entry to be made in the trace file.
The tnfctl_probe_connect() and tnfctl_probe_disconnect_all() functions control which functions, if any, are called when an enabled probe is hit.
The tnfctl_probe_state_get() function returns information about the status of a probe, such as whether it is currently enabled.
The tnfctl_trace_attrs_get() function returns information about the tracing session, such as the size of the trace buffer or trace file.
The tnfctl_strerror() function maps a tnfctl error code to a string, for reporting purposes.
The remaining functions apply only to kernel mode.
The tnfctl_trace_state_set() function controls the master switch for kernel tracing. See prex(1) for more details.
The tnfctl_filter_state_set(), tnfctl_filter_list_get(), tnfctl_filter_list_add(), and tnfctl_filter_list_delete() functions 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.
The tnfctl_buffer_dealloc() function deallocates the kernel's internal trace buffer.
TNFCTL_ERR_ACCES
TNFCTL_ERR_NOTARGET
TNFCTL_ERR_ALLOCFAIL
TNFCTL_ERR_INTERNAL
TNFCTL_ERR_SIZETOOSMALL
TNFCTL_ERR_SIZETOOBIG
TNFCTL_ERR_BADARG
TNFCTL_ERR_NOTDYNAMIC
TNFCTL_ERR_NOLIBTNFPROBE
TNFCTL_ERR_BUFBROKEN
TNFCTL_ERR_BUFEXISTS
TNFCTL_ERR_NOBUF
TNFCTL_ERR_BADDEALLOC
TNFCTL_ERR_NOPROCESS
TNFCTL_ERR_FILENOTFOUND
TNFCTL_ERR_BUSY
TNFCTL_ERR_INVALIDPROBE
TNFCTL_ERR_USR1
TNFCTL_ERR_USR2
TNFCTL_ERR_USR3
TNFCTL_ERR_USR4
TNFCTL_ERR_USR5
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
MT Level | MT-Safe with exceptions |
Linker and Libraries Guide
June 20, 2021 | OmniOS |