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

   1 '\" te
   2 .\"  Copyright (c) 1996 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_TRACE_STATE_SET 3TNF "Mar 4, 1997"
   7 .SH NAME
   8 tnfctl_trace_state_set, tnfctl_filter_state_set, tnfctl_filter_list_get,
   9 tnfctl_filter_list_add, tnfctl_filter_list_delete \- control kernel tracing and
  10 process filtering
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ]
  15 #include <tnf/tnfctl.h>
  16
  17 \fBtnfctl_errcode_t\fR \fBtnfctl_trace_state_set\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR,
  18      \fBboolean_t\fR \fItrace_state\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBtnfctl_errcode_t\fR \fBtnfctl_filter_state_set\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR,
  24      \fBboolean_t\fR \fIfilter_state\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBtnfctl_errcode_t\fR \fBtnfctl_filter_list_get\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR,
  30      \fBpid_t **\fR\fIpid_list\fR,\ \fBint *\fR\fIpid_count\fR);
  31 .fi
  32
  33 .LP
  34 .nf
  35 \fBtnfctl_errcode_t\fR \fBtnfctl_filter_list_add\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR,
  36      \fBpid_t\fR \fIpid_to_add\fR);
  37 .fi
  38
  39 .LP
  40 .nf
  41 \fBtnfctl_errcode_t\fR \fBtnfctl_filter_list_delete\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR,
  42      \fBpid_t\fR \fIpid_to_delete\fR);
  43 .fi
  44
  45 .SH DESCRIPTION
  46 .sp
  47 .LP
  48 The interfaces to control kernel tracing and process filtering are used only
  49 with kernel handles, handles created by \fBtnfctl_kernel_open\fR(3TNF). These
  50 interfaces are used to change the tracing and filter  states for kernel
  51 tracing.
  52 .sp
  53 .LP
  54 \fBtnfctl_trace_state_set()\fR sets the kernel global tracing state to "on" if
  55 \fItrace_state\fR is \fBB_TRUE,\fR or to "off" if \fItrace_state\fR is
  56 \fBB_FALSE.\fR For the kernel,  \fItrace_state\fR is off by default.Probes that
  57 are enabled will  not write out data unless this state is on. Use
  58 \fBtnfctl_trace_attrs_get\fR(3TNF) to retrieve the current tracing state.
  59 .sp
  60 .LP
  61 \fBtnfctl_filter_state_set()\fR sets the kernel process filtering state to "on"
  62 if \fIfilter_state\fR is \fBB_TRUE,\fR or to "off" if \fIfilter_state\fR is
  63 \fBB_FALSE.\fR \fIfilter_state\fR is off by default.  If it is on, only probe
  64 points encountered  by processes in the process filter set by
  65 \fBtnfctl_filter_list_add()\fR will generate trace points.  Use
  66 \fBtnfctl_trace_attrs_get\fR(3TNF) to retrieve the current process filtering
  67 state.
  68 .sp
  69 .LP
  70 \fBtnfctl_filter_list_get()\fR returns the process filter list as an array in
  71 \fIpid_list\fR. The count of elements in the process filter list is returned in
  72 \fIpid_count\fR. The caller should use \fBfree\fR(3C) to free memory allocated
  73 for the array \fIpid_list\fR.
  74 .sp
  75 .LP
  76 \fBtnfctl_filter_list_add()\fR adds  \fIpid_to_add\fR to the process filter
  77 list.  The process filter list is maintained even when the process filtering
  78 state is off, but it has no effect unless the process filtering state is on.
  79 .sp
  80 .LP
  81 \fBtnfctl_filter_list_delete()\fR deletes \fIpid_to_delete\fR from the process
  82 filter list.  It returns an error if the process does  not exist or is not in
  83 the filter list.
  84 .SH RETURN VALUES
  85 .sp
  86 .LP
  87 The interfaces \fBtnfctl_trace_state_set()\fR, \fBtnfctl_filter_state_set()\fR,
  88 \fBtnfctl_filter_list_add()\fR, \fBtnfctl_filter_list_delete()\fR, and
  89 \fBtnfctl_filter_list_get()\fR return \fBTNFCTL_ERR_NONE\fR upon success.
  90 .SH ERRORS
  91 .sp
  92 .LP
  93 The following error codes apply to \fBtnfctl_trace_state_set\fR:
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBTNFCTL_ERR_BADARG\fR\fR
  98 .ad
  99 .RS 24n
 100 The handle is not a kernel handle.
 101 .RE
 102
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fBTNFCTL_ERR_NOBUF\fR\fR
 107 .ad
 108 .RS 24n
 109 Cannot turn on tracing without a buffer being allocated.
 110 .RE
 111
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fBTNFCTL_ERR_BUFBROKEN\fR\fR
 116 .ad
 117 .RS 24n
 118 Tracing is broken in the target.
 119 .RE
 120
 121 .sp
 122 .ne 2
 123 .na
 124 \fB\fBTNFCTL_ERR_INTERNAL\fR\fR
 125 .ad
 126 .RS 24n
 127 An internal error occurred.
 128 .RE
 129
 130 .sp
 131 .LP
 132 The following error codes apply to \fBtnfctl_filter_state_set\fR:
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fBTNFCTL_ERR_BADARG\fR\fR
 137 .ad
 138 .RS 23n
 139 The handle is not a kernel handle.
 140 .RE
 141
 142 .sp
 143 .ne 2
 144 .na
 145 \fB\fBTNFCTL_ERR_INTERNAL\fR\fR
 146 .ad
 147 .RS 23n
 148 An internal error occurred.
 149 .RE
 150
 151 .sp
 152 .LP
 153 The following error codes apply to \fBtnfctl_filter_list_add\fR:
 154 .sp
 155 .ne 2
 156 .na
 157 \fB\fBTNFCTL_ERR_BADARG\fR\fR
 158 .ad
 159 .RS 24n
 160 The handle is not a kernel handle.
 161 .RE
 162
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fBTNFCTL_ERR_NOPROCESS\fR\fR
 167 .ad
 168 .RS 24n
 169 No such process exists.
 170 .RE
 171
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR
 176 .ad
 177 .RS 24n
 178 A memory allocation failure occurred.
 179 .RE
 180
 181 .sp
 182 .ne 2
 183 .na
 184 \fB\fBTNFCTL_ERR_INTERNAL\fR\fR
 185 .ad
 186 .RS 24n
 187 An internal error occurred.
 188 .RE
 189
 190 .sp
 191 .LP
 192 The following error codes apply to \fBtnfctl_filter_list_delete\fR:
 193 .sp
 194 .ne 2
 195 .na
 196 \fB\fBTNFCTL_ERR_BADARG\fR\fR
 197 .ad
 198 .RS 24n
 199 The handle is not a kernel handle.
 200 .RE
 201
 202 .sp
 203 .ne 2
 204 .na
 205 \fB\fBTNFCTL_ERR_NOPROCESS\fR\fR
 206 .ad
 207 .RS 24n
 208 No such process exists.
 209 .RE
 210
 211 .sp
 212 .ne 2
 213 .na
 214 \fB\fBTNFCTL_ERR_INTERNAL\fR\fR
 215 .ad
 216 .RS 24n
 217 An internal error occurred.
 218 .RE
 219
 220 .sp
 221 .LP
 222 The following error codes apply to  \fBtnfctl_filter_list_get\fR:
 223 .sp
 224 .ne 2
 225 .na
 226 \fB\fBTNFCTL_ERR_BADARG\fR\fR
 227 .ad
 228 .RS 24n
 229 The handle is not a kernel handle.
 230 .RE
 231
 232 .sp
 233 .ne 2
 234 .na
 235 \fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR
 236 .ad
 237 .RS 24n
 238 A memory allocation failure occurred.
 239 .RE
 240
 241 .sp
 242 .ne 2
 243 .na
 244 \fB\fBTNFCTL_ERR_INTERNAL\fR\fR
 245 .ad
 246 .RS 24n
 247 An internal error occurred.
 248 .RE
 249
 250 .SH ATTRIBUTES
 251 .sp
 252 .LP
 253 See \fBattributes\fR(5) for descriptions of the following attributes:
 254 .sp
 255
 256 .sp
 257 .TS
 258 box;
 259 c | c
 260 l | l .
 261 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 262 _
 263 MT Level        MT-Safe
 264 .TE
 265
 266 .SH SEE ALSO
 267 .sp
 268 .LP
 269 \fBprex\fR(1), \fBTNF_PROBE\fR(3TNF), \fBfree\fR(3C), \fBlibtnfctl\fR(3TNF),
 270 \fBtnfctl_kernel_open\fR(3TNF), \fBtnfctl_trace_attrs_get\fR(3TNF),
 271 \fBtracing\fR(3TNF), \fBtnf_kernel_probes\fR(4), \fBattributes\fR(5)