summaryrefslogtreecommitdiff
path: root/usr/src/man/man3tnf/tnfctl_probe_state_get.3tnf
blob: 37fd3c448021ea45f7f2e38f0619a2c6fdc628fe (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
'\" 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)