path: root/usr/src/man/man3tnf/libtnfctl.3tnf

'\" te
.\"  Copyright (c) 2004 Sun Microsystems, Inc.  All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH LIBTNFCTL 3TNF "Mar 1, 2004"
.SH NAME
libtnfctl \- library for TNF probe control in a process or the kernel
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ]
#include <tnf/tnfctl.h>
.fi

.SH DESCRIPTION
.sp
.LP
The \fBlibtnfctl\fR library provides an  \fBAPI\fR to control  \fBTNF\fR
("Trace Normal Form") probes within a process or the kernel. See
\fBtracing\fR(3TNF) for an overview of the Solaris tracing architecture. The
client of \fBlibtnfctl\fR controls probes in one of four modes:
.sp
.ne 2
.na
\fBinternal mode\fR
.ad
.RS 17n
The target is the controlling process itself; that is, the client controls its
own probes.
.RE

.sp
.ne 2
.na
\fBdirect mode\fR
.ad
.RS 17n
The target is a separate process; a client can either  \fBexec\fR(2) a program
or attach to a running process for probe control. The \fBlibtnfctl\fR library
uses \fBproc\fR(4) on the target process for probe and process control in this
mode, and additionally provides basic process control features.
.RE

.sp
.ne 2
.na
\fBindirect mode\fR
.ad
.RS 17n
The target is a separate process, but the controlling process is already using
\fBproc\fR(4) to control the target, and hence  \fBlibtnfctl\fR 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
\fBlibtnfctl\fR can use to query and update the target process.
.RE

.sp
.ne 2
.na
\fBkernel mode\fR
.ad
.RS 17n
The target is the Solaris kernel.
.RE

.sp
.LP
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.
.sp
.LP
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 \fBlibtnfctl\fR 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.
.sp
.LP
The following tables denotes the modes applicable to all \fBlibtnfctl\fR
interfaces (INT = internal mode; D = direct mode; IND = indirect mode; K =
kernel mode).
.sp
.LP
These interfaces create handles in the specified modes:
.sp

.sp
.TS
l l l l l
l l l l l .
\fBtnfctl_internal_open()\fR	INT			
\fBtnfctl_exec_open()\fR		D		
\fBtnfctl_pid_open()\fR		D		
\fBtnfctl_indirect_open()\fR			IND	
\fBtnfctl_kernel_open()\fR				K
.TE

.sp
.LP
These interfaces are used with the specified modes:
.sp

.sp
.TS
l l l l l
l l l l l .
\fBtnfctl_continue()\fR		D		
\fBtnfctl_probe_connect()\fR	INT	D	IND	
\fBtnfctl_probe_disconnect_all ()\fR	INT	D	IND	
\fBtnfctl_trace_attrs_get()\fR	INT	D	IND	K
\fBtnfctl_buffer_alloc()\fR	INT	D	IND	K
\fBtnfctl_register_funcs()\fR	INT	D	IND	K
\fBtnfctl_probe_apply()\fR	INT	D	IND	K
\fBtnfctl_probe_apply_ids()\fR	INT	D	IND	K
\fBtnfctl_probe_state_get ()\fR	INT	D	IND	K
\fBtnfctl_probe_enable()\fR	INT	D	IND	K
\fBtnfctl_probe_disable()\fR	INT	D	IND	K
\fBtnfctl_probe_trace()\fR	INT	D	IND	K
\fBtnfctl_probe_untrace()\fR	INT	D	IND	K
\fBtnfctl_check_libs()\fR	INT	D	IND	K
\fBtnfctl_close()\fR	INT	D	IND	K
\fBtnfctl_strerror()\fR	INT	D	IND	K
\fBtnfctl_buffer_dealloc()\fR				K
\fBtnfctl_trace_state_set()\fR				K
\fBtnfctl_filter_state_set()\fR				K
\fBtnfctl_filter_list_get()\fR				K
\fBtnfctl_filter_list_add()\fR				K
\fBtnfctl_filter_list_delete()\fR				K
.TE

.sp
.LP
When using \fBlibtnfctl\fR, the first task is to create a handle for
controlling probes. The \fBtnfctl_internal_open()\fR function creates an
internal mode handle for controlling probes in the same process, as described
above. The \fBtnfctl_pid_open()\fR and \fBtnfctl_exec_open()\fR functions
create handles in direct mode. The \fBtnfctl_indirect_open()\fR function
creates an indirect mode handle, and the \fBtnfctl_kernel_open()\fR function
creates a kernel mode handle. A handle is required for use in nearly all other
\fBlibtnfctl\fR functions. The \fBtnfctl_close()\fR function releases the
resources associated with a handle.
.sp
.LP
The \fBtnfctl_continue()\fR function is used in direct mode to resume execution
of the target process.
.sp
.LP
The \fBtnfctl_buffer_alloc()\fR function allocates a trace file or, in kernel
mode, a trace buffer.
.sp
.LP
The \fBtnfctl_probe_apply()\fR and \fBtnfctl_probe_apply_ids()\fR functions
call a specified function for each probe or for a designated set of probes.
.sp
.LP
The \fBtnfctl_register_funcs()\fR 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.
.sp
.LP
The \fBtnfctl_check_libs()\fR function is used primarily in indirect mode to
check whether any new probes have appeared, that is, they have been made
available by  \fBdlopen\fR(3C), or have disappeared, that is, they have
disassociated from the process by \fBdlclose\fR(3C).
.sp
.LP
The \fBtnfctl_probe_enable()\fR and \fBtnfctl_probe_disable()\fR functions
control whether the probe, when hit, will be ignored.
.sp
.LP
The \fBtnfctl_probe_trace()\fR and \fBtnfctl_probe_untrace()\fR functions
control whether an enabled probe, when hit, will cause an entry to be made in
the trace file.
.sp
.LP
The \fBtnfctl_probe_connect()\fR and \fBtnfctl_probe_disconnect_all()\fR
functions control which functions, if any, are called when an enabled probe is
hit.
.sp
.LP
The \fBtnfctl_probe_state_get()\fR function returns information about the
status of a probe, such as whether it is currently enabled.
.sp
.LP
The \fBtnfctl_trace_attrs_get()\fR function returns information about the
tracing session, such as the  size of the trace buffer or trace file.
.sp
.LP
The \fBtnfctl_strerror()\fR function maps a  \fBtnfctl\fR error code to a
string, for reporting purposes.
.sp
.LP
The remaining functions apply only to kernel mode.
.sp
.LP
The \fBtnfctl_trace_state_set()\fR function controls the master switch for
kernel tracing.  See \fBprex\fR(1) for more details.
.sp
.LP
The \fBtnfctl_filter_state_set()\fR, \fBtnfctl_filter_list_get()\fR,
\fBtnfctl_filter_list_add()\fR, and \fBtnfctl_filter_list_delete()\fR 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.
.sp
.LP
The \fBtnfctl_buffer_dealloc()\fR function deallocates the kernel's internal
trace buffer.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, these functions return\fBTNFCTL_ERR_NONE\fR.
.SH ERRORS
.sp
.LP
The error codes for  \fBlibtnfctl\fR are:
.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_ACCES\fR\fR
.ad
.RS 28n
Permission denied.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_NOTARGET\fR\fR
.ad
.RS 28n
The target process completed.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR
.ad
.RS 28n
A memory allocation failure occurred.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_INTERNAL\fR\fR
.ad
.RS 28n
An internal error occurred.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_SIZETOOSMALL\fR\fR
.ad
.RS 28n
The requested trace size is too small.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_SIZETOOBIG\fR\fR
.ad
.RS 28n
The requested trace size is too big.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_BADARG\fR\fR
.ad
.RS 28n
Bad input argument.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_NOTDYNAMIC\fR\fR
.ad
.RS 28n
The target is not a dynamic executable.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_NOLIBTNFPROBE\fR\fR
.ad
.RS 28n
\fBlibtnfprobe.so\fR not linked in target.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_BUFBROKEN\fR\fR
.ad
.RS 28n
Tracing is broken in the target.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_BUFEXISTS\fR\fR
.ad
.RS 28n
A buffer already exists.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_NOBUF\fR\fR
.ad
.RS 28n
No buffer exists.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_BADDEALLOC\fR\fR
.ad
.RS 28n
Cannot deallocate buffer.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_NOPROCESS\fR\fR
.ad
.RS 28n
No such target process exists.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_FILENOTFOUND\fR\fR
.ad
.RS 28n
File not found.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_BUSY\fR\fR
.ad
.RS 28n
Cannot attach to process or kernel because it is already tracing.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_INVALIDPROBE\fR\fR
.ad
.RS 28n
Probe no longer valid.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_USR1\fR\fR
.ad
.RS 28n
Error code reserved for user.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_USR2\fR\fR
.ad
.RS 28n
Error code reserved for user.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_USR3\fR\fR
.ad
.RS 28n
Error code reserved for user.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_USR4\fR\fR
.ad
.RS 28n
Error code reserved for user.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_USR5\fR\fR
.ad
.RS 28n
Error code reserved for user.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT Level	MT-Safe with exceptions
.TE

.SH SEE ALSO
.sp
.LP
\fBprex\fR(1), \fBexec\fR(2), \fBdlclose\fR(3C), \fBdlopen\fR(3C),
\fBTNF_PROBE\fR(3TNF), \fBtnfctl_buffer_alloc\fR(3TNF),
\fBtnfctl_buffer_dealloc\fR(3TNF), \fBtnfctl_check_libs\fR(3TNF),
\fBtnfctl_close\fR(3TNF), \fBtnfctl_continue\fR(3TNF),
\fBtnfctl_internal_open\fR(3TNF), \fBtnfctl_exec_open\fR(3TNF),
\fBtnfctl_filter_list_add\fR(3TNF), \fBtnfctl_filter_list_delete\fR(3TNF),
\fBtnfctl_filter_list_get\fR(3TNF), \fBtnfctl_filter_state_set\fR(3TNF),
\fBtnfctl_kernel_open\fR(3TNF), \fBtnfctl_pid_open\fR(3TNF),
\fBtnfctl_probe_apply\fR(3TNF), \fBtnfctl_probe_apply_ids\fR(3TNF),
\fBtnfctl_probe_connect\fR(3TNF), \fBtnfctl_probe_disable\fR(3TNF),
\fBtnfctl_probe_enable\fR(3TNF), \fBtnfctl_probe_state_get\fR(3TNF),
\fBtnfctl_probe_trace\fR(3TNF), \fBtnfctl_probe_untrace\fR(3TNF),
\fBtnfctl_indirect_open\fR(3TNF), \fBtnfctl_register_funcs\fR(3TNF),
\fBtnfctl_strerror\fR(3TNF), \fBtnfctl_trace_attrs_get\fR(3TNF),
\fBtnfctl_trace_state_set\fR(3TNF), \fBlibtnfctl\fR(3LIB), \fBproc\fR(4),
\fBattributes\fR(5)
.sp
.LP
\fILinker and Libraries Guide\fR
.SH NOTES
.sp
.LP
This  \fBAPI\fR is MT-Safe.  Multiple threads may concurrently operate on
independent \fBtnfctl\fR handles, which is the typical behavior expected.  The
\fBlibtnfctl\fR library does not support multiple threads operating on the same
\fBtnfctl\fR handle.  If this is desired, it is the client's responsibility to
implement  locking to ensure that two threads that use the same \fBtnfctl\fR
handle are not simultaneously in a \fBlibtnfctl\fR interface.