1LIBTRACEEVENT(3) libtraceevent Manual LIBTRACEEVENT(3)
2
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
13 #include <event-parse.h>
14 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
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 The tep_filter_alloc() function creates a new event filter. The tep
35 argument is the trace event parser context.
36 The tep_filter_free() function frees an event filter and all resources
38 that it had used.
39 The tep_filter_reset() function removes all rules from an event filter
41 and resets it.
42 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 The tep_event_filtered() function checks if the event with event_id has
47 filter.
48 The tep_filter_remove_event() function removes a filter for an event
50 with event_id.
51 The tep_filter_match() function tests if a record matches given filter.
53 The tep_filter_copy() function copies a source filter into a dest
55 filter.
56 The tep_filter_compare() function compares two filers - filter1 and
58 filter2.
59 The tep_filter_make_string() function constructs a string, displaying
61 the filter contents for given event_id.
62 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
68 The tep_filter_alloc() function returns a pointer to the newly created
69 event filter, or NULL in case of an error.
70 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 The tep_event_filtered() function returns 1 if the filter is found for
76 given event, or 0 otherwise.
77 The tep_filter_remove_event() function returns 1 if the vent was
79 removed, or 0 if the event was not found.
80 The tep_filter_match() function returns tep_errno, according to the
82 result:
83 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 or any other tep_errno, if an error occurred during the test.
90 The tep_filter_copy() function returns 0 on success or -1 if not all
92 rules were copied.
93 The tep_filter_compare() function returns 1 if the two filters hold the
95 same content, or 0 if they do not.
96 The tep_filter_make_string() function returns a string, which must be
98 freed with free(), or NULL in case of an error.
99 The tep_filter_strerror() function returns 0 if message was filled
101 successfully, or -1 in case of an error.
102
104 #include <event-parse.h>
105 ...
106 struct tep_handle *tep = tep_alloc();
107 ...
108 char errstr[200];
109 int ret;
110 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 event = tep_find_event_by_record(tep, record);
132 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 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 if (tep_filter_remove_event(filter, event->id) == 1) {
161 /* The event was removed from the filter */
162 }
163 }
164 ...
166 tep_filter_reset(filter);
167 ...
168 tep_filter_free(filter);
169 tep_filter_free(filter1);
170 ...
171
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
179 libtraceevent(3), trace-cmd(1)
180
182 Steven Rostedt <rostedt@goodmis.org[1]>, author of libtraceevent.
183 Tzvetomir Stoyanov <tz.stoyanov@gmail.com[2]>, author of this man page.
184
186 Report bugs to <linux-trace-devel@vger.kernel.org[3]>
187
189 libtraceevent is Free Software licensed under the GNU LGPL 2.1
190
192 https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/
193
195 1. rostedt@goodmis.org
196 mailto:rostedt@goodmis.org
197 2. tz.stoyanov@gmail.com
199 mailto:tz.stoyanov@gmail.com
200 3. linux-trace-devel@vger.kernel.org
202 mailto:linux-trace-devel@vger.kernel.org
203libtraceevent 1.5.3 04/15/2022 LIBTRACEEVENT(3)