usr/src/man/man3tnf/tnfctl_probe_apply.3tnf

   1 '\" te
   2 .\"  Copyright (c) 2004 Sun Microsystems, Inc.  All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH TNFCTL_PROBE_APPLY 3TNF "Mar 1, 2004"
   7 .SH NAME
   8 tnfctl_probe_apply, tnfctl_probe_apply_ids \- iterate over probes
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ]
  13 #include <tnf/tnfctl.h>
  14
  15 \fBtnfctl_errcode_t\fR \fBtnfctl_probe_apply\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR,
  16      \fBtnfctl_probe_op_t\fR \fIprobe_op\fR, \fBvoid *\fR\fIclientdata\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBtnfctl_errcode_t\fR \fBtnfctl_probe_apply_ids\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR,
  22      \fBulong_t\fR \fIprobe_count\fR, \fBulong_t *\fR\fIprobe_ids\fR,
  23      \fBtnfctl_probe_op_t\fR \fIprobe_op\fR, \fBvoid *\fR\fIclientdata\fR);
  24 .fi
  25
  26 .SH DESCRIPTION
  27 .sp
  28 .LP
  29 \fBtnfctl_probe_apply()\fR is used to iterate over the probes controlled by
  30 \fIhndl.\fR For every probe, the \fIprobe_op\fR function is called:
  31 .sp
  32 .in +2
  33 .nf
  34 typedef tnfctl_errcode_t (*tnfctl_probe_op_t)(
  35         tnfctl_handle_t *hndl,
  36         tnfctl_probe_t *probe_hndl,
  37         void *clientdata);
  38 .fi
  39 .in -2
  40
  41 .sp
  42 .LP
  43 Several predefined functions are available for use as  \fIprobe_op\fR. These
  44 functions are described in \fBtnfctl_probe_state_get\fR(3TNF).
  45 .sp
  46 .LP
  47 The \fIclientdata\fR supplied in \fBtnfctl_probe_apply()\fR is passed in as the
  48 last argument of \fIprobe_op\fR. The \fIprobe_hndl\fR in the probe operation
  49 function can be used to query or change the state of  the probe.  See
  50 \fBtnfctl_probe_state_get\fR(3TNF). The  \fIprobe_op\fR function should return
  51 \fBTNFCTL_ERR_NONE\fR upon success.  It can also return an error code,  which
  52 will cause \fBtnfctl_probe_apply()\fR to stop processing the rest of the probes
  53 and return with the same error code. Note that there are five (5) error codes
  54 reserved  that the client can use for its own semantics. See  \fBERRORS\fR.
  55 .sp
  56 .LP
  57 The lifetime of \fIprobe_hndl\fR is the same as the lifetime of \fIhndl\fR. It
  58 is good until \fIhndl\fR is closed by \fBtnfctl_close\fR(3TNF). Do not confuse
  59 a \fIprobe_hndl\fR with \fIhndl\fR. The \fIprobe_hndl\fR refers to a particular
  60 probe, while \fIhndl\fR refers to a process or the kernel. If \fIprobe_hndl\fR
  61 is used in another \fBlibtnfctl\fR(3TNF) interface, and it references a probe
  62 in a library that has been  dynamically closed (see \fBdlclose\fR(3C)), then
  63 the error code \fBTNFCTL_ERR_INVALIDPROBE\fR will be returned by that
  64 interface.
  65 .sp
  66 .LP
  67 \fBtnfctl_probe_apply_ids()\fR is very similar to \fBtnfctl_probe_apply()\fR.
  68 The difference is that \fIprobe_op\fR is called only for probes that match a
  69 probe id specified in the array of integers referenced by \fIprobe_ids\fR. The
  70 number of probe ids in the array should be specified in \fIprobe_count\fR. Use
  71 \fBtnfctl_probe_state_get()\fR to get the  \fIprobe_id\fR that corresponds to
  72 the \fIprobe_handl\fR.
  73 .SH RETURN VALUES
  74 .sp
  75 .LP
  76 \fBtnfctl_probe_apply()\fR and \fBtnfctl_probe_apply_ids()\fR return
  77 \fBTNFCTL_ERR_NONE\fR upon success.
  78 .SH ERRORS
  79 .sp
  80 .LP
  81 The following errors apply to both \fBtnfctl_probe_apply()\fR and
  82 \fBtnfctl_probe_apply_ids()\fR:
  83 .sp
  84 .ne 2
  85 .na
  86 \fB\fBTNFCTL_ERR_INTERNAL\fR\fR
  87 .ad
  88 .RS 23n
  89 An internal error occurred.
  90 .RE
  91
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fBTNFCTL_ERR_USR1\fR\fR
  96 .ad
  97 .RS 23n
  98 Error code reserved for user.
  99 .RE
 100
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fBTNFCTL_ERR_USR2\fR\fR
 105 .ad
 106 .RS 23n
 107 Error code reserved for user.
 108 .RE
 109
 110 .sp
 111 .ne 2
 112 .na
 113 \fB\fBTNFCTL_ERR_USR3\fR\fR
 114 .ad
 115 .RS 23n
 116 Error code reserved for user.
 117 .RE
 118
 119 .sp
 120 .ne 2
 121 .na
 122 \fB\fBTNFCTL_ERR_USR4\fR\fR
 123 .ad
 124 .RS 23n
 125 Error code reserved for user.
 126 .RE
 127
 128 .sp
 129 .ne 2
 130 .na
 131 \fB\fBTNFCTL_ERR_USR5\fR\fR
 132 .ad
 133 .RS 23n
 134 Error code reserved for user.
 135 .RE
 136
 137 .sp
 138 .LP
 139 \fBtnfctl_probe_apply()\fR and  \fBtnfctl_probe_apply_ids()\fR also return any
 140 error returned by the callback function \fIprobe_op\fR.
 141 .sp
 142 .LP
 143 The following errors apply only to  \fBtnfctl_probe_apply_ids()\fR:
 144 .sp
 145 .ne 2
 146 .na
 147 \fB\fBTNFCTL_ERR_INVALIDPROBE\fR\fR
 148 .ad
 149 .RS 27n
 150 The probe handle is no longer valid.  For example, the probe is in a  library
 151 that has been closed by \fBdlclose\fR(3C).
 152 .RE
 153
 154 .SH EXAMPLES
 155 .LP
 156 \fBExample 1 \fREnabling Probes
 157 .sp
 158 .LP
 159 To enable all probes:
 160
 161 .sp
 162 .in +2
 163 .nf
 164 tnfctl_probe_apply(hndl, tnfctl_probe_enable, NULL);
 165 .fi
 166 .in -2
 167
 168 .LP
 169 \fBExample 2 \fRDisabling Probes
 170 .sp
 171 .LP
 172 To disable the probes that match a certain pattern in the probe attribute
 173 string:
 174
 175 .sp
 176 .in +2
 177 .nf
 178 /* To disable all probes that contain the string "vm" */
 179 tnfctl_probe_apply(hndl, select_disable, "vm");
 180 static tnfctl_errcode_t
 181 select_disable(tnfctl_handle_t *hndl, tnfctl_probe_t *probe_hndl,
 182 void *client_data)
 183 {
 184      char *pattern = client_data;
 185      tnfctl_probe_state_t probe_state;
 186      tnfctl_probe_state_get(hndl, probe_hndl, &probe_state);
 187      if (strstr(probe_state.attr_string, pattern)) {
 188           tnfctl_probe_disable(hndl, probe_hndl, NULL);
 189      }
 190 }
 191 .fi
 192 .in -2
 193
 194 .sp
 195 .LP
 196 Note that these examples do not have any error handling code.
 197
 198 .SH ATTRIBUTES
 199 .sp
 200 .LP
 201 See \fBattributes\fR(5) for descriptions of the following attributes:
 202 .sp
 203
 204 .sp
 205 .TS
 206 box;
 207 c | c
 208 l | l .
 209 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 210 _
 211 MT-Level        MT-Safe
 212 .TE
 213
 214 .SH SEE ALSO
 215 .sp
 216 .LP
 217 \fBprex\fR(1), \fBTNF_PROBE\fR(3TNF), \fBdlclose\fR(3C), \fBdlopen\fR(3C),
 218 \fBlibtnfctl\fR(3TNF), \fBtnfctl_close\fR(3TNF),
 219 \fBtnfctl_probe_state_get\fR(3TNF), \fBtracing\fR(3TNF),
 220 \fBtnf_kernel_probes\fR(4), \fBattributes\fR(5)
 221 .sp
 222 .LP
 223 \fILinker and Libraries Guide\fR