tnfctl_probe_apply(3tnf)

1tnfctl_probe_apply(3TNF)     TNF Library Functions    tnfctl_probe_apply(3TNF)
2
3
4

NAME

6       tnfctl_probe_apply, tnfctl_probe_apply_ids - iterate over probes
7

SYNOPSIS

9       cc [ flag ... ] file ... -ltnfctl [ library ... ]
10       #include <tnf/tnfctl.h>
11
12       tnfctl_errcode_t tnfctl_probe_apply(tnfctl_handle_t *hndl,
13            tnfctl_probe_op_t probe_op, void *clientdata);
14
15
16       tnfctl_errcode_t tnfctl_probe_apply_ids(tnfctl_handle_t *hndl,
17            ulong_t probe_count, ulong_t *probe_ids,
18            tnfctl_probe_op_t probe_op, void *clientdata);
19
20

DESCRIPTION

22       tnfctl_probe_apply()  is  used to iterate over the probes controlled by
23       hndl. For every probe, the probe_op function is called:
24
25         typedef tnfctl_errcode_t (*tnfctl_probe_op_t)(
26              tnfctl_handle_t *hndl,
27              tnfctl_probe_t *probe_hndl,
28              void *clientdata);
29
30
31
32       Several predefined functions are available for use as  probe_op.  These
33       functions are described in tnfctl_probe_state_get(3TNF).
34
35
36       The  clientdata  supplied  in  tnfctl_probe_apply() is passed in as the
37       last argument of probe_op. The probe_hndl in the probe operation  func‐
38       tion  can  be  used  to  query  or change the state of  the probe.  See
39       tnfctl_probe_state_get(3TNF).  The   probe_op  function  should  return
40       TNFCTL_ERR_NONE upon success.  It can also return an error code,  which
41       will cause tnfctl_probe_apply() to stop  processing  the  rest  of  the
42       probes  and  return  with the same error code. Note that there are five
43       (5) error codes reserved  that the client can use for  its  own  seman‐
44       tics. See  ERRORS.
45
46
47       The  lifetime  of probe_hndl is the same as the lifetime of hndl. It is
48       good until hndl is closed  by  tnfctl_close(3TNF).  Do  not  confuse  a
49       probe_hndl  with  hndl.  The  probe_hndl  refers to a particular probe,
50       while hndl refers to a process or the kernel. If probe_hndl is used  in
51       another  libtnfctl(3TNF)  interface,  and  it  references  a probe in a
52       library that has been  dynamically closed (see dlclose(3C)),  then  the
53       error code TNFCTL_ERR_INVALIDPROBE will be returned by that interface.
54
55
56       tnfctl_probe_apply_ids()  is  very similar to tnfctl_probe_apply(). The
57       difference is that probe_op is called only  for  probes  that  match  a
58       probe  id  specified  in the array of integers referenced by probe_ids.
59       The  number  of  probe  ids  in  the  array  should  be  specified   in
60       probe_count.  Use   tnfctl_probe_state_get()  to get the  probe_id that
61       corresponds to the probe_handl.
62

RETURN VALUES

64       tnfctl_probe_apply()      and      tnfctl_probe_apply_ids()      return
65       TNFCTL_ERR_NONE upon success.
66

ERRORS

68       The   following   errors   apply   to   both  tnfctl_probe_apply()  and
69       tnfctl_probe_apply_ids():
70
71       TNFCTL_ERR_INTERNAL    An internal error occurred.
72
73
74       TNFCTL_ERR_USR1        Error code reserved for user.
75
76
77       TNFCTL_ERR_USR2        Error code reserved for user.
78
79
80       TNFCTL_ERR_USR3        Error code reserved for user.
81
82
83       TNFCTL_ERR_USR4        Error code reserved for user.
84
85
86       TNFCTL_ERR_USR5        Error code reserved for user.
87
88
89
90       tnfctl_probe_apply()  and   tnfctl_probe_apply_ids()  also  return  any
91       error returned by the callback function probe_op.
92
93
94       The following errors apply only to  tnfctl_probe_apply_ids():
95
96       TNFCTL_ERR_INVALIDPROBE    The  probe  handle  is no longer valid.  For
97                                  example, the probe is in a  library that has
98                                  been closed by dlclose(3C).
99
100

EXAMPLES

102       Example 1 Enabling Probes
103
104
105       To enable all probes:
106
107
108         tnfctl_probe_apply(hndl, tnfctl_probe_enable, NULL);
109
110
111       Example 2 Disabling Probes
112
113
114       To  disable  the  probes  that  match  a  certain  pattern in the probe
115       attribute string:
116
117
118         /* To disable all probes that contain the string "vm" */
119         tnfctl_probe_apply(hndl, select_disable, "vm");
120         static tnfctl_errcode_t
121         select_disable(tnfctl_handle_t *hndl, tnfctl_probe_t *probe_hndl,
122         void *client_data)
123         {
124              char *pattern = client_data;
125              tnfctl_probe_state_t probe_state;
126              tnfctl_probe_state_get(hndl, probe_hndl, &probe_state);
127              if (strstr(probe_state.attr_string, pattern)) {
128                   tnfctl_probe_disable(hndl, probe_hndl, NULL);
129              }
130         }
131
132
133
134       Note that these examples do not have any error handling code.
135
136

ATTRIBUTES

138       See attributes(5) for descriptions of the following attributes:
139
140
141
142
143       ┌─────────────────────────────┬─────────────────────────────┐
144       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
145       ├─────────────────────────────┼─────────────────────────────┤
146       │Availability                 │SUNWtnfc                     │
147       ├─────────────────────────────┼─────────────────────────────┤
148       │MT-Level                     │MT-Safe                      │
149       └─────────────────────────────┴─────────────────────────────┘
150