HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |SYNOPSIS |DESCRIPTION |RETURN VALUE |EXAMPLE |FILES |SEE ALSO |AUTHOR |REPORTING BUGS |LICENSE |RESOURCES |NOTES |COLOPHON | |
LIBTRACEEVENT(3) libtraceevent ManualLIBTRACEEVENT(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); voidtep_filter_free(struct tep_event_filter *filter); voidtep_filter_reset(struct tep_event_filter *filter); enum tep_errnotep_filter_add_filter_str(struct tep_event_filter *filter, const char *filter_str); inttep_event_filtered(struct tep_event_filter *filter, intevent_id); inttep_filter_remove_event(struct tep_event_filter *filter, intevent_id); enum tep_errnotep_filter_match(struct tep_event_filter *filter, struct tep_record *record); inttep_filter_copy(struct tep_event_filter *dest, struct tep_event_filter *source); inttep_filter_compare(struct tep_event_filter *filter1, struct tep_event_filter *filter2); char *tep_filter_make_string(struct tep_event_filter *filter, intevent_id); inttep_filter_strerror(struct tep_event_filter *filter, enum tep_errnoerr, char *buf, size_tbuflen);
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. Thetep_filter_alloc()function creates a new event filter. Thetep argument is the trace event parser context. Thetep_filter_free()function frees an event filter and all resources that it had used. Thetep_filter_reset()function removes all rules from an event filter and resets it. Thetep_filter_add_filter_str()function adds a new rule to thefilter. Thefilter_str argument is the filter string, that contains the rule. Thetep_event_filtered()function checks if the event withevent_id hasfilter. Thetep_filter_remove_event()function removes afilter for an event withevent_id. Thetep_filter_match()function tests if arecord matches givenfilter. Thetep_filter_copy()function copies asource filter into adest filter. Thetep_filter_compare()function compares two filers -filter1 andfilter2. Thetep_filter_make_string()function constructs a string, displaying thefilter contents for givenevent_id. Thetep_filter_strerror()function copies thefilter error buffer into the givenbuf with the sizebuflen. If the error buffer is empty, in thebuf is copied a string, describing the errorerr.
Thetep_filter_alloc()function returns a pointer to the newly created event filter, or NULL in case of an error. Thetep_filter_add_filter_str()function returns 0 if the rule was successfully added or a negative error code. Usetep_filter_strerror()to see actual error message in case of an error. Thetep_event_filtered()function returns 1 if the filter is found for given event, or 0 otherwise. Thetep_filter_remove_event()function returns 1 if the vent was removed, or 0 if the event was not found. Thetep_filter_match()function returnstep_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 othertep_errno, if an error occurred during the test. Thetep_filter_copy()function returns 0 on success or -1 if not all rules were copied. Thetep_filter_compare()function returns 1 if the two filters hold the same content, or 0 if they do not. Thetep_filter_make_string()function returns a string, which must be freed with free(), or NULL in case of an error. Thetep_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 oflibtraceevent.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 thelibtraceevent (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 isnot part of the original manual page), send a mail to man-pages@man7.orglibtraceevent 1.7.3 09/24/2023LIBTRACEEVENT(3)HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |