LIBTRACEFS(3)

💅 LIBTRACEFS(3) 💅

okay so bestie, this is a page from the libtracefs Manual and it's literally all about PID filtering for functions and events. buckle up 🎀

---

✨ NAME ✨

tracefs_filter_pid_function, tracefs_filter_pid_events, tracefs_filter_pid_function_clear, tracefs_filter_pid_events_clear — the four icons that add and remove PID filtering for functions and events 🦋

---

🌸 SYNOPSIS 🌸

#include <tracefs.h>

int tracefs_filter_pid_function(struct tracefs_instance *instance, int pid,
                                bool reset, bool notrace);
int tracefs_filter_pid_function_clear(struct tracefs_instance *instance, bool notrace);
int tracefs_filter_pid_events(struct tracefs_instance *instance, int pid,
                             bool reset, bool notrace);
int tracefs_filter_pid_events_clear(struct tracefs_instance *instance, bool notrace);

---

💖 DESCRIPTION 💖

so the vibe check here is: both events and functions can be filtered by PID, but they're done separately, no cap. PID filtering for functions affects the function and function_graph tracers, whereas PID filtering for events affects all events, like sched_switch and sched_waking 🫶

if TRACEFS_OPTION_FUNCTION_FORK is enabled (peep tracefs_option_enable(3)), any PID set as part of the function PID filtering will automatically have its children added when they're spawned, and the PID gets removed when they exit. and if TRACEFS_OPTION_EVENT_FORK is set, the same thing is true for event PID filtering. this also includes the notrace option, where the child threads and processes of PIDs that are labeled as notrace will also not be traced 💀

tracefs_filter_pid_function() affects function PID filtering, and tracefs_filter_pid_events() affects the PID event filtering. for both functions, they add a pid to be filtered in the given instance. if reset is true, then any PIDs already being filtered get removed — otherwise the pid is simply added to the filtering. if notrace is true, then the PID is added to the list of PIDs that are not to be traced 👑

⚠️ note note note: reset only affects the list associated with notrace. that is, if both reset and notrace are true, then it will not affect PIDs that are to be traced. same energy if reset is true and notrace is false — it will not affect PIDs that are not to be traced 🙈

tracefs_filter_pid_function_clear() affects function PID filtering, and tracefs_filter_pid_events_clear() affects the PID event filtering. for both functions it will clear all the PIDs being filtered for the given filter. if notrace is true it clears all the PIDs that are not to be traced, otherwise if it's false, it clears all the PIDs that are to be traced ✨

---

🌈 RETURN VALUE 🌈

all the functions return 0 on success and -1 on error. that's it, that's the whole thing 🎀

---

🦋 EXAMPLE 🦋

like, here's a whole little program, it ate fr fr:

#include <stdlib.h>
#include <stdio.h>
#include <ctype.h>
#include <tracefs.h>

static void usage(char **argv)
{
        fprintf(stderr, "usage: %s [-e|-f][-c|-n] pid [pid ...]\n", argv[0]);
        fprintf(stderr, "   -e enable event filter\n");
        fprintf(stderr, "   -f enable function filter\n");
        fprintf(stderr, "     (default is both, function and event)\n");
        fprintf(stderr, "   -c clear the filter\n");
        fprintf(stderr, "   -n notrace filter\n");
        exit(-1);
}

int main (int argc, char **argv)
{
        bool events = false;
        bool funcs = false;
        bool neg = false;
        bool clear = false;
        bool reset = true;
        int i;

        for (i = 1; i < argc && argv[i][0] == '-'; i++) {
                char *arg = argv[i];
                int c;
                for (c = 1; arg[c]; c++) {
                        switch (arg[c]) {
                        case 'e': events = true; break;
                        case 'f': funcs = true; break;
                        case 'n': neg = true; break;
                        case 'c': clear = true; break;
                        default:
                                usage(argv);
                        }
                }
                if (c == 1)
                        usage(argv);
        }

        if (i == argc && !clear)
                usage(argv);

        if (!events && !funcs) {
                events = true;
                funcs = true;
        }

        if (clear) {
                if (events)
                        tracefs_filter_pid_events_clear(NULL, neg);
                if (funcs)
                        tracefs_filter_pid_function_clear(NULL, neg);
                exit(0);
        }

        for (; i < argc; i++) {
                int pid = atoi(argv[i]);

                if (events)
                        tracefs_filter_pid_events(NULL, pid, reset, neg);
                if (funcs)
                        tracefs_filter_pid_function(NULL, pid, reset, neg);

                reset = false;
        }

        exit(0);
}

---

🎀 FILES 🎀

• tracefs.h — header file to include in order to have access to the library APIs.
• -ltracefs — linker switch to add when building a program that uses the library.

---

⭐ SEE ALSO ⭐

libtracefs(3), libtraceevent(3), trace-cmd(1), tracefs_hist_alloc(3), tracefs_hist_alloc_2d(3), tracefs_hist_alloc_nd(3), tracefs_hist_free(3), tracefs_hist_add_key(3), tracefs_hist_add_value(3), tracefs_hist_add_name(3), tracefs_hist_start(3), tracefs_hist_destory(3), tracefs_hist_add_sort_key(3), tracefs_hist_sort_key_direction(3)

(and yes, it's literally spelled tracefs_hist_destory(3) in the original, bestie, we don't fix, we only report 💅)

---

👑 AUTHOR 👑

Steven Rostedt <rostedt@goodmis.org> — the main character, fr fr

---

💀 REPORTING BUGS 💀

report bugs to <linux-trace-devel@vger.kernel.org> — they're nice, promise 🫶

---

🌟 LICENSE 🌟

libtracefs is Free Software licensed under the GNU LGPL 2.1.

---

🍓 RESOURCES 🍓

https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ — go click it, it's giving source code excellence ✨

---

🧚 COPYING 🧚

Copyright (C) 2023 Google, LLC. Free use of this software is granted under the terms of the GNU Public License (GPL).

---

💜 NOTES 💜

1. rostedt@goodmis.org — mailto:rostedt@goodmis.org
2. linux-trace-devel@vger.kernel.org — mailto:linux-trace-devel@vger.kernel.org

---

and that's the whole page! this diva of a doc is libtracefs 1.8.4, dated 10/21/2026, and it's been real, bestie — go forth and filter those PIDs 🌸🦋💖