LIBTRACEEVENT(3)

✨ NAME ✨

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 — bestie, these are the Event filter related APIs 💅

Okay so this whole page lives in the libtraceevent manual, and it's basically the filter girlies' group chat 🎀

---

🌸 SYNOPSIS 🌸

#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);

---

💅 DESCRIPTION 💅

So like, filters can be attached to traced events. The whole point? Filtering out various events when you're outputting them 🦋 Each event can be filtered based on its parameters, which are described in the event's format file. This little squad of functions lets you create, delete, modify, and attach event filters. Slay.

• tep_filter_alloc() — creates a brand new event filter, no cap. The tep argument is the trace event parser context. She's the main character here.
• tep_filter_free() — frees an event filter and literally all the resources it had used. Everything. Gone. Bye 💀
• tep_filter_reset() — removes all rules from an event filter and resets it. Clean slate energy ✨
• tep_filter_add_filter_str() — adds a new rule to the filter. The filter_str argument is the filter string, and that's the thing holding the actual rule.
• tep_event_filtered() — checks if the event with event_id has a filter. Just a lil vibe check.
• tep_filter_remove_event() — removes a filter for an event with event_id. Not me deleting it 🙈
• tep_filter_match() — tests if a record matches the given filter. The moment of truth fr fr.
• tep_filter_copy() — copies a source filter into a dest filter. Twin making 🫶
• tep_filter_compare() — compares two filters, filter1 and filter2. Are they the same girl or not 👀
• tep_filter_make_string() — constructs a string displaying the filter contents for the given event_id. Receipts.
• tep_filter_strerror() — copies the filter error buffer into the given buf with the size buflen. And if the error buffer is empty, then what gets copied into buf is a string describing the error err. Lowkey thoughtful 💜

---

🎀 RETURN VALUE 🎀

• tep_filter_alloc() — hands you a pointer to the freshly created event filter, or NULL if something went wrong 😭
• tep_filter_add_filter_str() — returns 0 if the rule was successfully added, or a negative error code. Use tep_filter_strerror() to see the actual error message when it goes bad. It's giving "read the error, bestie".
• tep_event_filtered() — returns 1 if the filter is found for the given event, or 0 otherwise.
• tep_filter_remove_event() — returns 1 if the event was removed, or 0 if the event was not found.
• tep_filter_match() — returns a tep_errno, according to the result:
  • TEP_ERRNO__FILTER_MATCH — filter found for event, the record matches. Iconic.
  • TEP_ERRNO__FILTER_MISS — filter found for event, the record does not match. Not the vibe.
  • TEP_ERRNO__FILTER_NOT_FOUND — no filter found for record's event.
  • TEP_ERRNO__NO_FILTER — no rules in the filter. Empty filter, empty brain, still valid.

…or any other tep_errno, if an error occurred during the test.

• tep_filter_copy() — returns 0 on success, or -1 if not all rules were copied. Partial copy = partial heartbreak.
• tep_filter_compare() — returns 1 if the two filters hold the same content, or 0 if they do not.
• tep_filter_make_string() — returns a string, which must be freed with free(), or NULL in case of an error. (Free your strings, bestie, the allocator is watching 💀)
• tep_filter_strerror() — returns 0 if the message was filled successfully, or -1 in case of an error.

---

🔥 EXAMPLE 🔥

#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);
...

---

🍓 FILES 🍓

• event-parse.h
  • Header file to include in order to have access to the library APIs. Yes, you gotta #include her first 🎀
• -ltraceevent
  • Linker switch to add when building a program that uses the library. Don't forget it or the linker WILL be dramatic 😤

---

🌈 SEE ALSO 🌈

libtraceevent(3), trace-cmd(1)

iykyk 🦋

---

👑 AUTHOR 👑

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

Legends, honestly 🫶

---

🫶 REPORTING BUGS 🫶

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

---

💜 LICENSE 💜

libtraceevent is Free Software licensed under the GNU LGPL 2.1. Periodt. 💅

---

⭐ RESOURCES ⭐

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

---

🙈 NOTES 🙈

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

---

and that's the whole page, bestie ✨ this was libtraceevent 1.9.0, dated 06/15/2026 — go filter some events, you absolute icon 💖🎀🦋💅