1LIBTRACEEVENT(3)             libtraceevent Manual             LIBTRACEEVENT(3)
2
3
4

NAME

6       tep_filter_alloc, tep_filter_free, tep_filter_reset,
7       tep_filter_make_string, tep_filter_copy, tep_filter_compare,
8       tep_filter_match, tep_event_filtered, tep_filter_remove_event,
9       tep_filter_strerror, tep_filter_add_filter_str - Event filter related
10       APIs.
11

SYNOPSIS

13       #include <event-parse.h>
14
15       struct tep_event_filter *tep_filter_alloc(struct tep_handle *tep);
16       void tep_filter_free(struct tep_event_filter *filter);
17       void tep_filter_reset(struct tep_event_filter *filter);
18       enum tep_errno tep_filter_add_filter_str(struct tep_event_filter *filter, const char *filter_str);
19       int tep_event_filtered(struct tep_event_filter *filter, int event_id);
20       int tep_filter_remove_event(struct tep_event_filter *filter, int event_id);
21       enum tep_errno tep_filter_match(struct tep_event_filter *filter, struct tep_record *record);
22       int tep_filter_copy(struct tep_event_filter *dest, struct tep_event_filter *source);
23       int tep_filter_compare(struct tep_event_filter *filter1, struct tep_event_filter *filter2);
24       char *tep_filter_make_string(struct tep_event_filter *filter, int event_id);
25       int tep_filter_strerror(struct tep_event_filter *filter, enum tep_errno err, char *buf, size_t buflen);
26

DESCRIPTION

28       Filters can be attached to traced events. They can be used to filter
29       out various events when outputting them. Each event can be filtered
30       based on its parameters, described in the event’s format file. This set
31       of functions can be used to create, delete, modify and attach event
32       filters.
33
34       The tep_filter_alloc() function creates a new event filter. The tep
35       argument is the trace event parser context.
36
37       The tep_filter_free() function frees an event filter and all resources
38       that it had used.
39
40       The tep_filter_reset() function removes all rules from an event filter
41       and resets it.
42
43       The tep_filter_add_filter_str() function adds a new rule to the filter.
44       The filter_str argument is the filter string, that contains the rule.
45
46       The tep_event_filtered() function checks if the event with event_id has
47       filter.
48
49       The tep_filter_remove_event() function removes a filter for an event
50       with event_id.
51
52       The tep_filter_match() function tests if a record matches given filter.
53
54       The tep_filter_copy() function copies a source filter into a dest
55       filter.
56
57       The tep_filter_compare() function compares two filers - filter1 and
58       filter2.
59
60       The tep_filter_make_string() function constructs a string, displaying
61       the filter contents for given event_id.
62
63       The tep_filter_strerror() function copies the filter error buffer into
64       the given buf with the size buflen. If the error buffer is empty, in
65       the buf is copied a string, describing the error err.
66

RETURN VALUE

68       The tep_filter_alloc() function returns a pointer to the newly created
69       event filter, or NULL in case of an error.
70
71       The tep_filter_add_filter_str() function returns 0 if the rule was
72       successfully added or a negative error code. Use tep_filter_strerror()
73       to see actual error message in case of an error.
74
75       The tep_event_filtered() function returns 1 if the filter is found for
76       given event, or 0 otherwise.
77
78       The tep_filter_remove_event() function returns 1 if the vent was
79       removed, or 0 if the event was not found.
80
81       The tep_filter_match() function returns tep_errno, according to the
82       result:
83
84           TEP_ERRNO__FILTER_MATCH        - filter found for event, the record matches.
85           TEP_ERRNO__FILTER_MISS         - filter found for event, the record does not match.
86           TEP_ERRNO__FILTER_NOT_FOUND    - no filter found for record’s event.
87           TEP_ERRNO__NO_FILTER           - no rules in the filter.
88
89       or any other tep_errno, if an error occurred during the test.
90
91       The tep_filter_copy() function returns 0 on success or -1 if not all
92       rules were copied.
93
94       The tep_filter_compare() function returns 1 if the two filters hold the
95       same content, or 0 if they do not.
96
97       The tep_filter_make_string() function returns a string, which must be
98       freed with free(), or NULL in case of an error.
99
100       The tep_filter_strerror() function returns 0 if message was filled
101       successfully, or -1 in case of an error.
102

EXAMPLE

104           #include <event-parse.h>
105           ...
106           struct tep_handle *tep = tep_alloc();
107           ...
108           char errstr[200];
109           int ret;
110
111           struct tep_event_filter *filter = tep_filter_alloc(tep);
112           struct tep_event_filter *filter1 = tep_filter_alloc(tep);
113           ret = tep_filter_add_filter_str(filter, "sched/sched_wakeup:target_cpu==1");
114           if(ret < 0) {
115                   tep_filter_strerror(filter, ret, errstr, sizeof(errstr));
116                   /* Failed to add a new rule to the filter, the error string is in errstr */
117           }
118           if (tep_filter_copy(filter1, filter) != 0) {
119                   /* Failed to copy filter in filter1 */
120           }
121           ...
122           if (tep_filter_compare(filter, filter1) != 1) {
123                   /* Both filters are different */
124           }
125           ...
126           void process_record(struct tep_handle *tep, struct tep_record *record)
127           {
128                   struct tep_event *event;
129                   char *fstring;
130
131                   event = tep_find_event_by_record(tep, record);
132
133                   if (tep_event_filtered(filter, event->id) == 1) {
134                           /* The event has filter */
135                           fstring = tep_filter_make_string(filter, event->id);
136                           if (fstring != NULL) {
137                                   /* The filter for the event is in fstring */
138                                   free(fstring);
139                           }
140                   }
141
142                   switch (tep_filter_match(filter, record)) {
143                   case TEP_ERRNO__FILTER_MATCH:
144                           /* The filter matches the record */
145                           break;
146                   case TEP_ERRNO__FILTER_MISS:
147                           /* The filter does not match the record */
148                           break;
149                   case TEP_ERRNO__FILTER_NOT_FOUND:
150                           /* No filter found for record's event */
151                           break;
152                   case TEP_ERRNO__NO_FILTER:
153                           /* There are no rules in the filter */
154                           break
155                   default:
156                           /* An error occurred during the test */
157                           break;
158                   }
159
160                   if (tep_filter_remove_event(filter, event->id) == 1) {
161                           /* The event was removed from the filter */
162                   }
163           }
164
165           ...
166           tep_filter_reset(filter);
167           ...
168           tep_filter_free(filter);
169           tep_filter_free(filter1);
170           ...
171

FILES

173           event-parse.h
174                   Header file to include in order to have access to the library APIs.
175           -ltraceevent
176                   Linker switch to add when building a program that uses the library.
177

SEE ALSO

179       libtraceevent(3), trace-cmd(1)
180

AUTHOR

182           Steven Rostedt <rostedt@goodmis.org[1]>, author of libtraceevent.
183           Tzvetomir Stoyanov <tz.stoyanov@gmail.com[2]>, author of this man page.
184

REPORTING BUGS

186       Report bugs to <linux-trace-devel@vger.kernel.org[3]>
187

LICENSE

189       libtraceevent is Free Software licensed under the GNU LGPL 2.1
190

RESOURCES

192       https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/
193

NOTES

195        1. rostedt@goodmis.org
196           mailto:rostedt@goodmis.org
197
198        2. tz.stoyanov@gmail.com
199           mailto:tz.stoyanov@gmail.com
200
201        3. linux-trace-devel@vger.kernel.org
202           mailto:linux-trace-devel@vger.kernel.org
203
204
205
206libtraceevent 1.1.1               02/08/2021                  LIBTRACEEVENT(3)
Impressum