'\" 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_apply 3TNF "1 Mar 2004" "SunOS 5.11" "TNF Library Functions"
.SH NAME
tnfctl_probe_apply, tnfctl_probe_apply_ids \- iterate over probes
.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_apply\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR,
     \fBtnfctl_probe_op_t\fR \fIprobe_op\fR, \fBvoid *\fR\fIclientdata\fR);
.fi

.LP
.nf
\fBtnfctl_errcode_t\fR \fBtnfctl_probe_apply_ids\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR,
     \fBulong_t\fR \fIprobe_count\fR, \fBulong_t *\fR\fIprobe_ids\fR,
     \fBtnfctl_probe_op_t\fR \fIprobe_op\fR, \fBvoid *\fR\fIclientdata\fR);
.fi

.SH DESCRIPTION
.sp
.LP
\fBtnfctl_probe_apply()\fR is used to iterate over the probes controlled by
\fIhndl.\fR For every probe, the \fIprobe_op\fR function is called:
.sp
.in +2
.nf
typedef tnfctl_errcode_t (*tnfctl_probe_op_t)(
	tnfctl_handle_t *hndl,
	tnfctl_probe_t *probe_hndl,
	void *clientdata);
.fi
.in -2

.sp
.LP
Several predefined functions are available for use as  \fIprobe_op\fR. These
functions are described in \fBtnfctl_probe_state_get\fR(3TNF).
.sp
.LP
The \fIclientdata\fR supplied in \fBtnfctl_probe_apply()\fR is passed in as the
last argument of \fIprobe_op\fR. The \fIprobe_hndl\fR in the probe operation
function can be used to query or change the state of  the probe.  See
\fBtnfctl_probe_state_get\fR(3TNF). The  \fIprobe_op\fR function should return
\fBTNFCTL_ERR_NONE\fR upon success.  It can also return an error code,  which
will cause \fBtnfctl_probe_apply()\fR to stop processing the rest of the probes
and return with the same error code. Note that there are five (5) error codes
reserved  that the client can use for its own semantics. See  \fBERRORS\fR.
.sp
.LP
The lifetime of \fIprobe_hndl\fR is the same as the lifetime of \fIhndl\fR. It
is good until \fIhndl\fR is closed by \fBtnfctl_close\fR(3TNF). Do not confuse
a \fIprobe_hndl\fR with \fIhndl\fR. The \fIprobe_hndl\fR refers to a particular
probe, while \fIhndl\fR refers to a process or the kernel. If \fIprobe_hndl\fR
is used in another \fBlibtnfctl\fR(3TNF) interface, and it references a probe
in a library that has been  dynamically closed (see \fBdlclose\fR(3C)), then
the error code \fBTNFCTL_ERR_INVALIDPROBE\fR will be returned by that
interface.
.sp
.LP
\fBtnfctl_probe_apply_ids()\fR is very similar to \fBtnfctl_probe_apply()\fR.
The difference is that \fIprobe_op\fR is called only for probes that match a
probe id specified in the array of integers referenced by \fIprobe_ids\fR. The
number of probe ids in the array should be specified in \fIprobe_count\fR. Use
\fBtnfctl_probe_state_get()\fR to get the  \fIprobe_id\fR that corresponds to
the \fIprobe_handl\fR.
.SH RETURN VALUES
.sp
.LP
\fBtnfctl_probe_apply()\fR and \fBtnfctl_probe_apply_ids()\fR return
\fBTNFCTL_ERR_NONE\fR upon success.
.SH ERRORS
.sp
.LP
The following errors apply to both \fBtnfctl_probe_apply()\fR and
\fBtnfctl_probe_apply_ids()\fR:
.sp
.ne 2
.mk
.na
\fB\fBTNFCTL_ERR_INTERNAL\fR\fR
.ad
.RS 23n
.rt  
An internal error occurred.
.RE

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

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

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

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

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

.sp
.LP
\fBtnfctl_probe_apply()\fR and  \fBtnfctl_probe_apply_ids()\fR also return any
error returned by the callback function \fIprobe_op\fR.
.sp
.LP
The following errors apply only to  \fBtnfctl_probe_apply_ids()\fR:
.sp
.ne 2
.mk
.na
\fB\fBTNFCTL_ERR_INVALIDPROBE\fR\fR
.ad
.RS 27n
.rt  
The probe handle is no longer valid.  For example, the probe is in a  library
that has been closed by \fBdlclose\fR(3C).
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fREnabling Probes
.sp
.LP
To enable all probes:

.sp
.in +2
.nf
tnfctl_probe_apply(hndl, tnfctl_probe_enable, NULL);
.fi
.in -2

.LP
\fBExample 2 \fRDisabling Probes
.sp
.LP
To disable the probes that match a certain pattern in the probe attribute
string:

.sp
.in +2
.nf
/* To disable all probes that contain the string "vm" */
tnfctl_probe_apply(hndl, select_disable, "vm");
static tnfctl_errcode_t
select_disable(tnfctl_handle_t *hndl, tnfctl_probe_t *probe_hndl,
void *client_data)
{
     char *pattern = client_data;
     tnfctl_probe_state_t probe_state;
     tnfctl_probe_state_get(hndl, probe_hndl, &probe_state);
     if (strstr(probe_state.attr_string, pattern)) {
          tnfctl_probe_disable(hndl, probe_hndl, NULL);
     }
}
.fi
.in -2

.sp
.LP
Note that these examples do not have any error handling code.

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

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
MT-LevelMT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBprex\fR(1), \fBTNF_PROBE\fR(3TNF), \fBdlclose\fR(3C), \fBdlopen\fR(3C),
\fBlibtnfctl\fR(3TNF), \fBtnfctl_close\fR(3TNF),
\fBtnfctl_probe_state_get\fR(3TNF), \fBtracing\fR(3TNF),
\fBtnf_kernel_probes\fR(4), \fBattributes\fR(5)
.sp
.LP
\fILinker and Libraries Guide\fR