|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | EXAMPLE | FILES | SEE ALSO | AUTHOR | REPORTING BUGS | LICENSE | RESOURCES | NOTES | COLOPHON |
|
|
|
LIBTRACEEVENT(3) libtraceevent Manual LIBTRACEEVENT(3)
tep_filter_alloc, tep_filter_free, tep_filter_reset,
tep_filter_make_string, tep_filter_copy, tep_filter_compare,
tep_filter_match, tep_event_filtered, tep_filter_remove_event,
tep_filter_strerror, tep_filter_add_filter_str - Event filter
related APIs.
#include <event-parse.h>
struct tep_event_filter *tep_filter_alloc(struct tep_handle *tep);
void tep_filter_free(struct tep_event_filter *filter);
void tep_filter_reset(struct tep_event_filter *filter);
enum tep_errno tep_filter_add_filter_str(struct tep_event_filter *filter, const char *filter_str);
int tep_event_filtered(struct tep_event_filter *filter, int event_id);
int tep_filter_remove_event(struct tep_event_filter *filter, int event_id);
enum tep_errno tep_filter_match(struct tep_event_filter *filter, struct tep_record *record);
int tep_filter_copy(struct tep_event_filter *dest, struct tep_event_filter *source);
int tep_filter_compare(struct tep_event_filter *filter1, struct tep_event_filter *filter2);
char *tep_filter_make_string(struct tep_event_filter *filter, int event_id);
int tep_filter_strerror(struct tep_event_filter *filter, enum tep_errno err, char *buf, size_t buflen);
Filters can be attached to traced events. They can be used to
filter out various events when outputting them. Each event can be
filtered based on its parameters, described in the event’s format
file. This set of functions can be used to create, delete, modify
and attach event filters.
The tep_filter_alloc() function creates a new event filter. The
tep argument is the trace event parser context.
The tep_filter_free() function frees an event filter and all
resources that it had used.
The tep_filter_reset() function removes all rules from an event
filter and resets it.
The tep_filter_add_filter_str() function adds a new rule to the
filter. The filter_str argument is the filter string, that
contains the rule.
The tep_event_filtered() function checks if the event with
event_id has filter.
The tep_filter_remove_event() function removes a filter for an
event with event_id.
The tep_filter_match() function tests if a record matches given
filter.
The tep_filter_copy() function copies a source filter into a dest
filter.
The tep_filter_compare() function compares two filers - filter1
and filter2.
The tep_filter_make_string() function constructs a string,
displaying the filter contents for given event_id.
The tep_filter_strerror() function copies the filter error buffer
into the given buf with the size buflen. If the error buffer is
empty, in the buf is copied a string, describing the error err.
The tep_filter_alloc() function returns a pointer to the newly
created event filter, or NULL in case of an error.
The tep_filter_add_filter_str() function returns 0 if the rule was
successfully added or a negative error code. Use
tep_filter_strerror() to see actual error message in case of an
error.
The tep_event_filtered() function returns 1 if the filter is found
for given event, or 0 otherwise.
The tep_filter_remove_event() function returns 1 if the vent was
removed, or 0 if the event was not found.
The tep_filter_match() function returns tep_errno, according to
the result:
TEP_ERRNO__FILTER_MATCH - filter found for event, the record matches.
TEP_ERRNO__FILTER_MISS - filter found for event, the record does not match.
TEP_ERRNO__FILTER_NOT_FOUND - no filter found for record’s event.
TEP_ERRNO__NO_FILTER - no rules in the filter.
or any other tep_errno, if an error occurred during the test.
The tep_filter_copy() function returns 0 on success or -1 if not
all rules were copied.
The tep_filter_compare() function returns 1 if the two filters
hold the same content, or 0 if they do not.
The tep_filter_make_string() function returns a string, which must
be freed with free(), or NULL in case of an error.
The tep_filter_strerror() function returns 0 if message was filled
successfully, or -1 in case of an error.
#include <event-parse.h>
...
struct tep_handle *tep = tep_alloc();
...
char errstr[200];
int ret;
struct tep_event_filter *filter = tep_filter_alloc(tep);
struct tep_event_filter *filter1 = tep_filter_alloc(tep);
ret = tep_filter_add_filter_str(filter, "sched/sched_wakeup:target_cpu==1");
if(ret < 0) {
tep_filter_strerror(filter, ret, errstr, sizeof(errstr));
/* Failed to add a new rule to the filter, the error string is in errstr */
}
if (tep_filter_copy(filter1, filter) != 0) {
/* Failed to copy filter in filter1 */
}
...
if (tep_filter_compare(filter, filter1) != 1) {
/* Both filters are different */
}
...
void process_record(struct tep_handle *tep, struct tep_record *record)
{
struct tep_event *event;
char *fstring;
event = tep_find_event_by_record(tep, record);
if (tep_event_filtered(filter, event->id) == 1) {
/* The event has filter */
fstring = tep_filter_make_string(filter, event->id);
if (fstring != NULL) {
/* The filter for the event is in fstring */
free(fstring);
}
}
switch (tep_filter_match(filter, record)) {
case TEP_ERRNO__FILTER_MATCH:
/* The filter matches the record */
break;
case TEP_ERRNO__FILTER_MISS:
/* The filter does not match the record */
break;
case TEP_ERRNO__FILTER_NOT_FOUND:
/* No filter found for record's event */
break;
case TEP_ERRNO__NO_FILTER:
/* There are no rules in the filter */
break
default:
/* An error occurred during the test */
break;
}
if (tep_filter_remove_event(filter, event->id) == 1) {
/* The event was removed from the filter */
}
}
...
tep_filter_reset(filter);
...
tep_filter_free(filter);
tep_filter_free(filter1);
...
event-parse.h
Header file to include in order to have access to the library APIs.
-ltraceevent
Linker switch to add when building a program that uses the library.
libtraceevent(3), trace-cmd(1)
Steven Rostedt <rostedt@goodmis.org[1]>, author of libtraceevent.
Tzvetomir Stoyanov <tz.stoyanov@gmail.com[2]>, author of this man page.
Report bugs to <linux-trace-devel@vger.kernel.org[3]>
libtraceevent is Free Software licensed under the GNU LGPL 2.1
https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/
1. rostedt@goodmis.org
mailto:rostedt@goodmis.org
2. tz.stoyanov@gmail.com
mailto:tz.stoyanov@gmail.com
3. linux-trace-devel@vger.kernel.org
mailto:linux-trace-devel@vger.kernel.org
This page is part of the libtraceevent (Linux kernel trace event
library) project. Information about the project can be found at
⟨https://www.trace-cmd.org/⟩. If you have a bug report for this
manual page, see ⟨https://www.trace-cmd.org/⟩. This page was
obtained from the project's upstream Git repository
⟨https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git⟩
on 2025-08-11. (At that time, the date of the most recent commit
that was found in the repository was 2025-05-30.) If you discover
any rendering problems in this HTML version of the page, or you
believe there is a better or more up-to-date source for the page,
or you have corrections or improvements to the information in this
COLOPHON (which is not part of the original manual page), send a
mail to man-pages@man7.org
libtraceevent 1.7.3 09/24/2023 LIBTRACEEVENT(3)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|