'\" 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 TNFCTL_PROBE_STATE_GET 3TNF "Mar 1, 2004"
.SH NAME
tnfctl_probe_state_get, tnfctl_probe_enable, tnfctl_probe_disable,
tnfctl_probe_trace, tnfctl_probe_untrace, tnfctl_probe_connect,
tnfctl_probe_disconnect_all \- interfaces to query and to change the state of a
probe
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ]
#include <tnf/tnfctl.h>

\fBtnfctl_errcode_t\fR \fBtnfctl_probe_state_get\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR,
     \fBtnfctl_probe_t *\fR\fIprobe_hndl\fR, \fBtnfctl_probe_state_t *\fR\fIstate\fR);
.fi

.LP
.nf
\fBtnfctl_errcode_t\fR \fBtnfctl_probe_enable\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR,
     \fBtnfctl_probe_t *\fR\fIprobe_hndl\fR, \fBvoid *\fR\fIignored\fR);
.fi

.LP
.nf
\fBtnfctl_errcode_t\fR \fBtnfctl_probe_disable\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR,
     \fBtnfctl_probe_t *\fR\fIprobe_hndl\fR, \fBvoid *\fR\fIignored\fR);
.fi

.LP
.nf
\fBtnfctl_errcode_t\fR \fBtnfctl_probe_trace\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR,
     \fBtnfctl_probe_t *\fR\fIprobe_hndl\fR, \fBvoid *\fR\fIignored\fR);
.fi

.LP
.nf
\fBtnfctl_errcode_t\fR \fBtnfctl_probe_untrace\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR,
     \fBtnfctl_probe_t *\fR\fIprobe_hndl\fR, \fBvoid *\fR\fIignored\fR);
.fi

.LP
.nf
\fBtnfctl_errcode_t\fR \fBtnfctl_probe_disconnect_all\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR,
     \fBtnfctl_probe_t *\fR\fIprobe_hndl\fR, \fBvoid *\fR\fIignored\fR);
.fi

.LP
.nf
\fBtnfctl_errcode_t\fR \fBtnfctl_probe_connect\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR,
     \fBtnfctl_probe_t *\fR\fIprobe_hndl\fR, \fBconst char *\fR\fIlib_base_name\fR,
     \fBconst char *\fR\fIfunc_name\fR);
.fi

.SH DESCRIPTION
.sp
.LP
\fBtnfctl_probe_state_get()\fR returns the state of the probe specified by
\fIprobe_hndl\fR in the process or kernel specified by \fIhndl\fR. The user
will pass these in to an apply iterator. The caller must also allocate
\fIstate\fR and pass in a pointer to it.  The semantics of the individual
members of \fIstate\fR are:
.sp
.ne 2
.na
\fB\fBid\fR\fR
.ad
.RS 26n
The unique integer assigned to this probe. This number does not change over the
lifetime of this probe. A \fIprobe_hndl\fR can be obtained by using the calls
\fBtnfctl_apply()\fR, \fBtanfctl_apply_ids()\fR, or
\fBtnfctl_register_funcs()\fR.
.RE

.sp
.ne 2
.na
\fB\fBattr_string\fR\fR
.ad
.RS 26n
A string that consists of  \fIattribute\fR \fIvalue\fR pairs separated by
semicolons.  For the syntax of this string, see the  syntax of the
\fBdetail\fR argument of the \fBTNF_PROBE\fR(3TNF) macro. The attributes
\fIname\fR, \fIslots\fR, \fIkeys\fR, \fBfile\fR, and \fBline\fR are defined for
every probe. Additional user-defined attributes can be added by using the
\fIdetail\fR argument of the \fBTNF_PROBE\fR(3TNF) macro.  An example of
\fIattr_string\fR follows:
.sp
.in +2
.nf
"name pageout;slots vnode pages_pageout ;
keys vm pageio io;file vm.c;line 25;"
.fi
.in -2

.RE

.sp
.ne 2
.na
\fB\fBenabled\fR\fR
.ad
.RS 26n
\fBB_TRUE\fR if the probe is enabled, or  \fBB_FALSE\fR if the probe is
disabled. Probes are disabled by default. Use \fBtnfctl_probe_enable()\fR or
\fBtnfctl_probe_disable()\fR to change this state.
.RE

.sp
.ne 2
.na
\fB\fBtraced\fR\fR
.ad
.RS 26n
\fBB_TRUE\fR if the probe is traced, or \fBB_FALSE\fR if the probe is not
traced. Probes in user processes are traced by default.  Kernel probes are
untraced by default.  Use \fBtnfctl_probe_trace()\fR or
\fBtnfctl_probe_untrace()\fR to change this state.
.RE

.sp
.ne 2
.na
\fB\fBnew_probe\fR\fR
.ad
.RS 26n
\fBB_TRUE\fR if this is a new probe brought in since the last change in
libraries. See  \fBdlopen\fR(3C) or \fBdlclose\fR(3C). Otherwise, the value of
\fBnew_probe\fR will be \fBB_FALSE\fR. This field is not  meaningful for kernel
probe control.
.RE

.sp
.ne 2
.na
\fB\fBobj_name\fR\fR
.ad
.RS 26n
The name of the shared object or executable in which the probe is  located.
This string can be freed, so the client should make a copy of the string if it
needs to be saved for use by other  \fBlibtnfctl\fR interfaces.  In kernel
mode, this string is always  \fINULL.\fR
.RE

.sp
.ne 2
.na
\fB\fBfunc_names\fR\fR
.ad
.RS 26n
A null-terminated array of pointers to strings that contain the names of
functions connected to this probe.  Whenever an enabled probe is encountered at
runtime, these functions are executed. This array also will be freed by the
library when the state of the probe changes.  Use \fBtnfctl_probe_connect()\fR
or \fBtnfctl_probe_disconnect_all()\fR to change this state.
.RE

.sp
.ne 2
.na
\fB\fBfunc_addrs\fR\fR
.ad
.RS 26n
A null-terminated array of pointers to addresses of functions in the target
image connected to this probe.  This array also will be freed by the library
when the state of the probe changes.
.RE

.sp
.ne 2
.na
\fB\fBclient_registered_data\fR\fR
.ad
.RS 26n
Data that was registered by the client for this probe by the creator function
in \fBtnfctl_register_funcs\fR(3TNF).
.RE

.sp
.LP
\fBtnfctl_probe_enable(\|),\fR \fBtnfctl_probe_disable(\|),\fR
\fBtnfctl_probe_trace(\|),\fR \fBtnfctl_probe_untrace(\|),\fR and
\fBtnfctl_probe_disconnect_all()\fR ignore the last argument. This  convenient
feature permits these functions to be used in the \fIprobe_op\fR field of
\fBtnfctl_probe_apply\fR(3TNF) and \fBtnfctl_probe_apply_ids\fR(3TNF).
\fBtnfctl_probe_enable()\fR enables the probe specified by \fIprobe_hndl\fR.
This is the master switch on a probe.  A probe does not perform any action
until it is enabled.
.sp
.LP
\fBtnfctl_probe_disable()\fR disables the probe specified by \fIprobe_hndl\fR.
.sp
.LP
\fBtnfctl_probe_trace()\fR turns on tracing for the probe specified by
\fIprobe_hndl\fR. Probes emit a trace record only if the probe is traced.
.sp
.LP
\fBtnfctl_probe_untrace()\fR turns off tracing for the probe specified by
\fIprobe_hndl\fR. This is useful if you want to connect probe functions to a
probe without tracing it.
.sp
.LP
\fBtnfctl_probe_connect()\fR connects the function \fIfunc_name\fR which exists
in the library  \fIlib_base_name\fR, to the probe specified by
\fIprobe_hndl\fR. \fBtnfctl_probe_connect()\fR returns an error code if used on
a kernel tnfctl handle. \fIlib_base_name\fR is the base name (not a path) of
the library.  If it is  \fINULL,\fR and multiple functions in the target
process match \fIfunc_name\fR, one of the matching functions is chosen
arbitrarily. A probe function is a function that is in the target's address
space and is written to a certain specification.  The specification is  not
currently published.
.sp
.LP
\fBtnf_probe_debug()\fR is one function exported by \fBlibtnfprobe.so.1\fR and
is the debug function that \fBprex\fR(1) uses.  When the debug function is
executed, it prints out the probe arguments and the value of the
\fBsunw%debug\fR attribute of the probe to  \fBstderr\fR.
.sp
.LP
\fBtnfctl_probe_disconnect_all()\fR disconnects all probe functions from the
probe specified by \fIprobe_hndl\fR.
.sp
.LP
Note that no  \fBlibtnfctl\fR call returns a probe handle
(\fBtnfctl_probe_t\fR), yet each of the routines described here takes a
\fIprobe_hndl\fR as an argument. These routines may be used by passing them to
one of the \fBtnfctl_probe_apply\fR(3TNF) iterators as the "op" argument.
Alternatively, probe handles may be obtained and saved by a user's "op"
function, and they can be passed later as the \fIprobe_hndl\fR argument when
using any of the functions described here.
.SH RETURN VALUES
.sp
.LP
\fBtnfctl_probe_state_get(\|),\fR \fBtnfctl_probe_enable(\|),\fR
\fBtnfctl_probe_disable(\|),\fR \fBtnfctl_probe_trace(\|),\fR
\fBtnfctl_probe_untrace(\|),\fR \fBtnfctl_probe_disconnect_all()\fR and
\fBtnfctl_probe_connect()\fR return \fBTNFCTL_ERR_NONE\fR upon success.
.SH ERRORS
.sp
.LP
The following error codes apply to  \fBtnfctl_probe_state_get()\fR:
.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_INVALIDPROBE\fR\fR
.ad
.RS 27n
\fIprobe_hndl\fR is no longer valid. The library that the probe was in could
have been dynamically closed by \fBdlclose\fR(3C).
.RE

.sp
.LP
The following error codes apply to  \fBtnfctl_probe_enable()\fR,
\fBtnfctl_probe_disable()\fR, \fBtnfctl_probe_trace()\fR,
\fBtnfctl_probe_untrace()\fR, and \fBtnfctl_probe_disconnect_all()\fR
.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_INVALIDPROBE\fR\fR
.ad
.RS 27n
\fIprobe_hndl\fR is no longer valid. The library that the probe was in could
have been dynamically closed by \fBdlclose\fR(3C).
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_BUFBROKEN\fR\fR
.ad
.RS 27n
Cannot do probe operations because tracing is broken in the target.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_NOBUF\fR\fR
.ad
.RS 27n
Cannot do probe operations until a buffer is allocated. See
\fBtnfctl_buffer_alloc\fR(3TNF). This error code  does not apply to kernel
probe control.
.RE

.sp
.LP
The following error codes apply to  \fBtnfctl_probe_connect()\fR:
.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_INVALIDPROBE\fR\fR
.ad
.RS 27n
\fIprobe_hndl\fR is no longer valid. The library that the probe was in could
have been dynamically closed by \fBdlclose\fR(3C).
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_BADARG\fR\fR
.ad
.RS 27n
The handle is a kernel handle, or  \fIfunc_name\fR could not be found.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_BUFBROKEN\fR\fR
.ad
.RS 27n
Cannot do probe operations because tracing is broken in the target.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_NOBUF\fR\fR
.ad
.RS 27n
Cannot do probe operations until a buffer is allocated. See
\fBtnfctl_buffer_alloc\fR(3TNF).
.RE

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

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

.SH SEE ALSO
.sp
.LP
\fBprex\fR(1), \fBTNF_PROBE\fR(3TNF), \fBlibtnfctl\fR(3TNF),
\fBtnfctl_check_libs\fR(3TNF), \fBtnfctl_continue\fR(3TNF),
\fBtnfctl_probe_apply\fR(3TNF), \fBtnfctl_probe_apply_ids\fR(3TNF),
\fBtracing\fR(3TNF), \fBtnf_kernel_probes\fR(4), \fBattributes\fR(5)