tnfctl_filter_state_set(3tnf)

1tnfctl_trace_state_set(3TNF) TNF Library Functionstnfctl_trace_state_set(3TNF)
2
3
4

NAME

6       tnfctl_trace_state_set,       tnfctl_filter_state_set,      tnfctl_fil‐
7       ter_list_get, tnfctl_filter_list_add, tnfctl_filter_list_delete -  con‐
8       trol kernel tracing and process filtering
9

SYNOPSIS

11       cc [ flag ... ] file ... -ltnfctl [ library ... ]
12       #include <tnf/tnfctl.h>
13
14       tnfctl_errcode_t tnfctl_trace_state_set(tnfctl_handle_t *hndl,
15            boolean_t trace_state);
16
17
18       tnfctl_errcode_t tnfctl_filter_state_set(tnfctl_handle_t *hndl,
19            boolean_t filter_state);
20
21
22       tnfctl_errcode_t tnfctl_filter_list_get(tnfctl_handle_t *hndl,
23            pid_t **pid_list, int *pid_count);
24
25
26       tnfctl_errcode_t tnfctl_filter_list_add(tnfctl_handle_t *hndl,
27            pid_t pid_to_add);
28
29
30       tnfctl_errcode_t tnfctl_filter_list_delete(tnfctl_handle_t *hndl,
31            pid_t pid_to_delete);
32
33

DESCRIPTION

35       The interfaces to control kernel tracing and process filtering are used
36       only with kernel handles, handles created by  tnfctl_kernel_open(3TNF).
37       These  interfaces are used to change the tracing and filter  states for
38       kernel tracing.
39
40
41       tnfctl_trace_state_set() sets the kernel global tracing state  to  "on"
42       if  trace_state  is  B_TRUE, or to "off" if trace_state is B_FALSE. For
43       the kernel,  trace_state is off by default.Probes that are enabled will
44       not    write    out    data    unless    this    state   is   on.   Use
45       tnfctl_trace_attrs_get(3TNF) to retrieve the current tracing state.
46
47
48       tnfctl_filter_state_set() sets the kernel process  filtering  state  to
49       "on" if filter_state is B_TRUE, or to "off" if filter_state is B_FALSE.
50       filter_state is off by default.  If it is on, only probe points encoun‐
51       tered    by   processes  in  the  process  filter  set  by  tnfctl_fil‐
52       ter_list_add()     will      generate      trace      points.       Use
53       tnfctl_trace_attrs_get(3TNF)  to retrieve the current process filtering
54       state.
55
56
57       tnfctl_filter_list_get() returns the process filter list as an array in
58       pid_list.  The count of elements in the process filter list is returned
59       in pid_count. The caller should use free(3C) to free  memory  allocated
60       for the array pid_list.
61
62
63       tnfctl_filter_list_add()  adds   pid_to_add to the process filter list.
64       The process filter list is maintained even when the  process  filtering
65       state  is  off, but it has no effect unless the process filtering state
66       is on.
67
68
69       tnfctl_filter_list_delete() deletes pid_to_delete from the process fil‐
70       ter list.  It returns an error if the process does  not exist or is not
71       in the filter list.
72

RETURN VALUES

74       The  interfaces  tnfctl_trace_state_set(),   tnfctl_filter_state_set(),
75       tnfctl_filter_list_add(), tnfctl_filter_list_delete(), and  tnfctl_fil‐
76       ter_list_get() return TNFCTL_ERR_NONE upon success.
77

ERRORS

79       The following error codes apply to tnfctl_trace_state_set:
80
81       TNFCTL_ERR_BADARG       The handle is not a kernel handle.
82
83
84       TNFCTL_ERR_NOBUF        Cannot turn on tracing without a  buffer  being
85                               allocated.
86
87
88       TNFCTL_ERR_BUFBROKEN    Tracing is broken in the target.
89
90
91       TNFCTL_ERR_INTERNAL     An internal error occurred.
92
93
94
95       The following error codes apply to tnfctl_filter_state_set:
96
97       TNFCTL_ERR_BADARG      The handle is not a kernel handle.
98
99
100       TNFCTL_ERR_INTERNAL    An internal error occurred.
101
102
103
104       The following error codes apply to tnfctl_filter_list_add:
105
106       TNFCTL_ERR_BADARG       The handle is not a kernel handle.
107
108
109       TNFCTL_ERR_NOPROCESS    No such process exists.
110
111
112       TNFCTL_ERR_ALLOCFAIL    A memory allocation failure occurred.
113
114
115       TNFCTL_ERR_INTERNAL     An internal error occurred.
116
117
118
119       The following error codes apply to tnfctl_filter_list_delete:
120
121       TNFCTL_ERR_BADARG       The handle is not a kernel handle.
122
123
124       TNFCTL_ERR_NOPROCESS    No such process exists.
125
126
127       TNFCTL_ERR_INTERNAL     An internal error occurred.
128
129
130
131       The following error codes apply to  tnfctl_filter_list_get:
132
133       TNFCTL_ERR_BADARG       The handle is not a kernel handle.
134
135
136       TNFCTL_ERR_ALLOCFAIL    A memory allocation failure occurred.
137
138
139       TNFCTL_ERR_INTERNAL     An internal error occurred.
140
141

ATTRIBUTES

143       See attributes(5) for descriptions of the following attributes:
144
145
146
147
148       ┌─────────────────────────────┬─────────────────────────────┐
149       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
150       ├─────────────────────────────┼─────────────────────────────┤
151       │Availability                 │SUNWtnfc                     │
152       ├─────────────────────────────┼─────────────────────────────┤
153       │MT Level                     │MT-Safe                      │
154       └─────────────────────────────┴─────────────────────────────┘
155

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

ATTRIBUTES

SEE ALSO