1tnfctl_probe_state_get(3TNF) TNF Library Functionstnfctl_probe_state_get(3TNF)
2
3
4

NAME

6       tnfctl_probe_state_get,    tnfctl_probe_enable,   tnfctl_probe_disable,
7       tnfctl_probe_trace,     tnfctl_probe_untrace,     tnfctl_probe_connect,
8       tnfctl_probe_disconnect_all  -  interfaces  to  query and to change the
9       state of a probe
10

SYNOPSIS

12       cc [ flag ... ] file ... -ltnfctl [ library ... ]
13       #include <tnf/tnfctl.h>
14
15       tnfctl_errcode_t tnfctl_probe_state_get(tnfctl_handle_t *hndl,
16            tnfctl_probe_t *probe_hndl, tnfctl_probe_state_t *state);
17
18
19       tnfctl_errcode_t tnfctl_probe_enable(tnfctl_handle_t *hndl,
20            tnfctl_probe_t *probe_hndl, void *ignored);
21
22
23       tnfctl_errcode_t tnfctl_probe_disable(tnfctl_handle_t *hndl,
24            tnfctl_probe_t *probe_hndl, void *ignored);
25
26
27       tnfctl_errcode_t tnfctl_probe_trace(tnfctl_handle_t *hndl,
28            tnfctl_probe_t *probe_hndl, void *ignored);
29
30
31       tnfctl_errcode_t tnfctl_probe_untrace(tnfctl_handle_t *hndl,
32            tnfctl_probe_t *probe_hndl, void *ignored);
33
34
35       tnfctl_errcode_t tnfctl_probe_disconnect_all(tnfctl_handle_t *hndl,
36            tnfctl_probe_t *probe_hndl, void *ignored);
37
38
39       tnfctl_errcode_t tnfctl_probe_connect(tnfctl_handle_t *hndl,
40            tnfctl_probe_t *probe_hndl, const char *lib_base_name,
41            const char *func_name);
42
43

DESCRIPTION

45       tnfctl_probe_state_get() returns the state of the  probe  specified  by
46       probe_hndl  in  the  process or kernel specified by hndl. The user will
47       pass these in to an apply iterator. The caller must also allocate state
48       and  pass  in a pointer to it.  The semantics of the individual members
49       of state are:
50
51       id                        The unique integer assigned  to  this  probe.
52                                 This number does not change over the lifetime
53                                 of this probe. A probe_hndl can  be  obtained
54                                 by   using  the  calls  tnfctl_apply(),  tan‐
55                                 fctl_apply_ids(), or tnfctl_register_funcs().
56
57
58       attr_string               A string that consists  of   attribute  value
59                                 pairs  separated by semicolons.  For the syn‐
60                                 tax of this string, see the   syntax  of  the
61                                 detail argument of the TNF_PROBE(3TNF) macro.
62                                 The attributes   name, slots, keys, file, and
63                                 line  are defined for every probe. Additional
64                                 user-defined attributes can be added by using
65                                 the   detail  argument of the TNF_PROBE(3TNF)
66                                 macro.  An example of attr_string follows:
67
68                                   "name pageout;slots vnode pages_pageout ;
69                                   keys vm pageio io;file vm.c;line 25;"
70
71
72
73       enabled                   B_TRUE if the probe is enabled,  or   B_FALSE
74                                 if the probe is disabled. Probes are disabled
75                                 by  default.  Use  tnfctl_probe_enable()   or
76                                 tnfctl_probe_disable() to change this state.
77
78
79       traced                    B_TRUE  if the probe is traced, or B_FALSE if
80                                 the probe is not traced. Probes in user  pro‐
81                                 cesses  are traced by default.  Kernel probes
82                                 are     untraced     by     default.      Use
83                                 tnfctl_probe_trace()                       or
84                                 tnfctl_probe_untrace() to change this state.
85
86
87       new_probe                 B_TRUE if this is  a  new  probe  brought  in
88                                 since  the  last  change  in  libraries.  See
89                                 dlopen(3C)  or  dlclose(3C).  Otherwise,  the
90                                 value  of   new_probe  will  be B_FALSE. This
91                                 field is not   meaningful  for  kernel  probe
92                                 control.
93
94
95       obj_name                  The  name  of the shared object or executable
96                                 in which the probe is  located.  This  string
97                                 can  be  freed,  so  the client should make a
98                                 copy of the string if it needs  to  be  saved
99                                 for  use  by other  libtnfctl interfaces.  In
100                                 kernel mode, this string is always  NULL.
101
102
103       func_names                A  null-terminated  array  of   pointers   to
104                                 strings  that  contain the names of functions
105                                 connected to this probe.  Whenever an enabled
106                                 probe  is encountered at runtime, these func‐
107                                 tions are executed. This array also  will  be
108                                 freed  by  the  library when the state of the
109                                 probe changes.  Use tnfctl_probe_connect() or
110                                 tnfctl_probe_disconnect_all()  to change this
111                                 state.
112
113
114       func_addrs                A  null-terminated  array  of   pointers   to
115                                 addresses  of  functions  in the target image
116                                 connected to this  probe.   This  array  also
117                                 will  be  freed by the library when the state
118                                 of the probe changes.
119
120
121       client_registered_data    Data that was registered by  the  client  for
122                                 this   probe   by  the  creator  function  in
123                                 tnfctl_register_funcs(3TNF).
124
125
126
127       tnfctl_probe_enable(),  tnfctl_probe_disable(),   tnfctl_probe_trace(),
128       tnfctl_probe_untrace(),  and  tnfctl_probe_disconnect_all()  ignore the
129       last argument. This  convenient feature permits these functions  to  be
130       used   in   the   probe_op   field   of   tnfctl_probe_apply(3TNF)  and
131       tnfctl_probe_apply_ids(3TNF). tnfctl_probe_enable() enables  the  probe
132       specified by probe_hndl. This is the master switch on a probe.  A probe
133       does not perform any action until it is enabled.
134
135
136       tnfctl_probe_disable() disables the probe specified by probe_hndl.
137
138
139       tnfctl_probe_trace() turns  on  tracing  for  the  probe  specified  by
140       probe_hndl. Probes emit a trace record only if the probe is traced.
141
142
143       tnfctl_probe_untrace()  turns  off  tracing  for the probe specified by
144       probe_hndl. This is useful if you want to connect probe functions to  a
145       probe without tracing it.
146
147
148       tnfctl_probe_connect()  connects the function func_name which exists in
149       the library  lib_base_name,  to  the  probe  specified  by  probe_hndl.
150       tnfctl_probe_connect() returns an error code if used on a kernel tnfctl
151       handle. lib_base_name is the base name (not a path) of the library.  If
152       it  is   NULL,  and  multiple  functions  in  the  target process match
153       func_name, one of the matching functions is chosen arbitrarily. A probe
154       function  is  a  function  that is in the target's address space and is
155       written to a certain specification.  The  specification  is   not  cur‐
156       rently published.
157
158
159       tnf_probe_debug()  is  one function exported by libtnfprobe.so.1 and is
160       the debug function that prex(1) uses.  When the debug function is  exe‐
161       cuted,  it  prints  out  the  probe  arguments  and  the  value  of the
162       sunw%debug attribute of the probe to  stderr.
163
164
165       tnfctl_probe_disconnect_all() disconnects all probe functions from  the
166       probe specified by probe_hndl.
167
168
169       Note  that  no  libtnfctl call returns a probe handle (tnfctl_probe_t),
170       yet each of the routines described here takes a probe_hndl as an  argu‐
171       ment.  These  routines  may  be  used  by  passing  them  to one of the
172       tnfctl_probe_apply(3TNF) iterators as the "op" argument. Alternatively,
173       probe  handles may be obtained and saved by a user's "op" function, and
174       they can be passed later as the probe_hndl argument when using  any  of
175       the functions described here.
176

RETURN VALUES

178       tnfctl_probe_state_get(),    tnfctl_probe_enable(),   tnfctl_probe_dis‐
179       able(), tnfctl_probe_trace(), tnfctl_probe_untrace(), tnfctl_probe_dis‐
180       connect_all()  and  tnfctl_probe_connect()  return TNFCTL_ERR_NONE upon
181       success.
182

ERRORS

184       The following error codes apply to  tnfctl_probe_state_get():
185
186       TNFCTL_ERR_INVALIDPROBE    probe_hndl is no longer valid.  The  library
187                                  that the probe was in could have been dynam‐
188                                  ically closed by dlclose(3C).
189
190
191
192       The   following   error   codes   apply   to     tnfctl_probe_enable(),
193       tnfctl_probe_disable(),  tnfctl_probe_trace(),  tnfctl_probe_untrace(),
194       and tnfctl_probe_disconnect_all()
195
196       TNFCTL_ERR_INVALIDPROBE    probe_hndl is no longer valid.  The  library
197                                  that the probe was in could have been dynam‐
198                                  ically closed by dlclose(3C).
199
200
201       TNFCTL_ERR_BUFBROKEN       Cannot do probe operations  because  tracing
202                                  is broken in the target.
203
204
205       TNFCTL_ERR_NOBUF           Cannot do probe operations until a buffer is
206                                  allocated.  See   tnfctl_buffer_alloc(3TNF).
207                                  This  error  code   does not apply to kernel
208                                  probe control.
209
210
211
212       The following error codes apply to  tnfctl_probe_connect():
213
214       TNFCTL_ERR_INVALIDPROBE    probe_hndl is no longer valid.  The  library
215                                  that the probe was in could have been dynam‐
216                                  ically closed by dlclose(3C).
217
218
219       TNFCTL_ERR_BADARG          The handle is a kernel handle, or  func_name
220                                  could not be found.
221
222
223       TNFCTL_ERR_BUFBROKEN       Cannot  do  probe operations because tracing
224                                  is broken in the target.
225
226
227       TNFCTL_ERR_NOBUF           Cannot do probe operations until a buffer is
228                                  allocated. See tnfctl_buffer_alloc(3TNF).
229
230

ATTRIBUTES

232       See attributes(5) for description of the following attributes:
233
234
235
236
237       ┌─────────────────────────────┬─────────────────────────────┐
238       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
239       ├─────────────────────────────┼─────────────────────────────┤
240       │Availability                 │SUNWtnfc                     │
241       ├─────────────────────────────┼─────────────────────────────┤
242       │MT Level                     │MT-Safe                      │
243       └─────────────────────────────┴─────────────────────────────┘
244

SEE ALSO

246       prex(1),   TNF_PROBE(3TNF),  libtnfctl(3TNF),  tnfctl_check_libs(3TNF),
247       tnfctl_continue(3TNF),                        tnfctl_probe_apply(3TNF),
248       tnfctl_probe_apply_ids(3TNF),    tracing(3TNF),   tnf_kernel_probes(4),
249       attributes(5)
250
251
252
253SunOS 5.11                        1 Mar 2004      tnfctl_probe_state_get(3TNF)
Impressum