libtnfctl - library for TNF probe control in a process or the kernel


cc [ flag ... ] file ... -ltnfctl [ library ... ]
#include <tnf/tnfctl.h>


The libtnfctl library provides an API to control TNF ("Trace Normal
Form") probes within a process or the kernel. See tracing(3TNF) for an
overview of the Solaris tracing architecture. The client of libtnfctl
controls probes in one of four modes:

internal mode
The target is the controlling process itself; that is,
the client controls its own probes.

direct mode
The target is a separate process; a client can either
exec(2) a program or attach to a running process for
probe control. The libtnfctl library uses proc(5) on the
target process for probe and process control in this
mode, and additionally provides basic process control

indirect mode
The target is a separate process, but the controlling
process is already using proc(5) 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.

kernel mode
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

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.


Upon successful completion, these functions return TNFCTL_ERR_NONE.


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.

TNFCTL_ERR_NOLIBTNFPROBE 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(7) for descriptions of the following attributes:

|MT Level | MT-Safe with exceptions |


prex(1), exec(2), dlclose(3C), dlopen(3C), libtnfctl(3LIB),
TNF_PROBE(3TNF), tnfctl_buffer_alloc(3TNF), tnfctl_buffer_dealloc(3TNF),
tnfctl_check_libs(3TNF), tnfctl_close(3TNF), tnfctl_continue(3TNF),
tnfctl_exec_open(3TNF), tnfctl_filter_list_add(3TNF),
tnfctl_filter_list_delete(3TNF), tnfctl_filter_list_get(3TNF),
tnfctl_filter_state_set(3TNF), tnfctl_indirect_open(3TNF),
tnfctl_internal_open(3TNF), tnfctl_kernel_open(3TNF),
tnfctl_pid_open(3TNF), tnfctl_probe_apply(3TNF),
tnfctl_probe_apply_ids(3TNF), tnfctl_probe_connect(3TNF),
tnfctl_probe_disable(3TNF), tnfctl_probe_enable(3TNF),
tnfctl_probe_state_get(3TNF), tnfctl_probe_trace(3TNF),
tnfctl_probe_untrace(3TNF), tnfctl_register_funcs(3TNF),
tnfctl_strerror(3TNF), tnfctl_trace_attrs_get(3TNF),
tnfctl_trace_state_set(3TNF), proc(5), attributes(7)

Linker and Libraries Guide


This API is MT-Safe. Multiple threads may concurrently operate on
independent tnfctl handles, which is the typical behavior expected. The
libtnfctl library 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.

June 20, 2021 LIBTNFCTL(3TNF)