LIBTRACEFS(3)

📦

version 1.8.4 · 13 versions

✨ LIBTRACEFS 💅 — the one where we mess with function trace filters 🎀

ok so bestie, this is the libtracefs page, and today's main characters are the function filter functions. yes, we're filtering which kernel functions get traced. it's giving "control freak but make it syscalls" ✨

🌸 NAME 🌸

tracefs_function_filter, tracefs_function_notrace, tracefs_filter_functions — literally the functions that let you modify the… the function trace filters 💖 (yes the original page says "the the", we're keeping the vibe, no cap)

🦋 SYNOPSIS 🦋

#include <tracefs.h>

int tracefs_function_filter(struct tracefs_instance *instance, const char *filter, const char *module, int flags);
int tracefs_function_notrace(struct tracefs_instance *instance, const char *filter, const char *module, int flags);
int tracefs_filter_functions(const char *filter, const char *module, char ***list);

💜 DESCRIPTION 💜

so tracefs_function_filter and tracefs_function_notrace are the girlies that limit which Linux kernel functions actually get traced by the function and function-graph tracers. iconic behavior honestly.

tracefs_function_filter defines the list of functions that can be traced 👑
tracefs_function_notrace defines the list of functions that will not be traced 🙅‍♀️
and if a function is in both lists? it will not be traced. that's it, that's the rule, bestie. periodt. 💀

They take these args:

instance — the instance, and it can be NULL for the top level tracing 🌈
filter — a string that represents a filter that should be applied to define what functions are to be traced
module — limits the filtering to a specific module (or NULL to filter on all functions)
flags — holds the control knobs on how the filters will be handled (see the FLAGS section below, iykyk)

Then there's tracefs_filter_functions 🧚 — it returns a list of functions that can be filtered on via the filter and module you supply. If both filter and module are NULL, then all available functions that can be filtered get returned. On success, list must be freed with tracefs_list_free()(3). don't forget, she's your responsibility now 🫶

🍓 what even is a filter tho

The filter may be either:

a straight match of a function 🎯
a glob ✨
or a regex(3) 🔥

A glob is where * matches zero or more characters, ? will match zero or one character, and . only matches a period. Simple. Clean. Gorgeous. 💅

If the filter is determined to be a regex (where it contains anything other than alpha numeric characters, or ., *, ?) the filter will be processed as a regex(3) following the rules of regex(3), and . is not a period, but will match any one character. plot twist!! 😭

To force a regular expression, either prefix filter with ^ or append it with $ as the filter does complete matches of the functions anyway.

🎀 the NULL filter lore

If module is set and filter is NULL, this will imply the same as filter being equal to "*". Which will enable all functions for a given module. slay.

Otherwise the filter may be NULL if a previous call to tracefs_function_filter() with the same instance had TRACEFS_FL_CONTINUE set and this call does not. This is useful to simply commit the previous filters ✅

It may also be NULL if TRACEFS_FL_RESET is set and the previous call did not have the same instance and TRACEFS_FL_CONTINUE set. This is useful to just clear the filter 🧼

⭐ FLAGS ⭐

The flags parameter may have the following set, or be zero. (zero is a valid vibe, ngl.)

TRACEFS_FL_RESET — If flags contains TRACEFS_FL_RESET, then it will clear the filters that are currently set before applying filter. Otherwise, filter is added to the current set of filters already enabled. If this flag is set and the previous call to tracefs_function_filter() had the same instance and the TRACEFS_FL_CONTINUE flag was set, then the function will fail with a return of -1 and errno set to EBUSY. 🚨 drama!
TRACEFS_FL_CONTINUE — If flags contains TRACEFS_FL_CONTINUE, then filter will not take effect after a successful call to tracefs_function_filter(). This allows for multiple calls to tracefs_function_filter() to update the filter function and then a single call (one without the TRACEFS_FL_CONTINUE flag set) to commit all the filters. It can be called multiple times to add more filters. A call without this flag set will commit the changes before returning (if the filter passed in successfully matched). A tracefs_function_filter() call after one that had the TRACEFS_FL_CONTINUE flag set for the same instance will fail if TRACEFS_FL_RESET flag is set, as the reset flag is only applicable for the first filter to be added before committing. 💅 it's a whole committed relationship situation
TRACEFS_FL_FUTURE — If flags contains TRACEFS_FL_FUTURE and module holds a string of a module, then if the module is not loaded it will attemp to write the filter with the module in the filter file. (yes, "attemp", we're quoting the ancestors 😭) Starting in Linux v4.13 module functions could be added to the filter before they are loaded. The filter will be cached, and when the module is loaded, the filter will be set before the module executes, allowing to trace init functions of a module. This will only work if the filter is not a regular expression. 🧚‍♀️ manifesting the module into existence fr fr

🔥 RETURN VALUE 🔥

For tracefs_function_filter() and tracefs_function_notrace() a return of 0 means success ✅

If the there is an error but the filtering was not started, then 1 is returned. If filtering was started but an error occurs, then -1 is returned. The state of the filtering may be in an unknown state. 😭 yeah. scary. we don't love that but we respect it.

If TRACEFS_FL_CONTINUE was set, and 0 or -1 was returned, then another call to tracefs_function_filter() must be done without TRACEFS_FL_CONTINUE set in order to commit (and close) the filtering. don't leave her hanging 🫶

For tracefs_filter_functions(), a return of 0 means success, and the list parameter is filled with a list of function names that matched filter and module. list is a string array, where the last string pointer in the array is NULL. The list must be freed with tracefs_list_free(). On failure, a negative is returned, and list is ignored. bye bestie 💀

💀 ERRORS 💀

tracefs_function_filter() can fail with the following errors:

EINVAL — The filter is invalid or did not match any functions. 💔
EBUSY — The previous call of tracefs_function_filter() was called with the same instance and TRACEFS_FL_CONTINUE set and the current call had TRACEFS_FL_RESET set. 🚨

Other errors may also happen caused by internal system calls. (the classic "it's not you it's the syscalls" 😭)

🦄 EXAMPLE 🦄

ok this is the whole thing, verbatim, go off king:

#include <stdio.h>
#include <errno.h>
#include <tracefs.h>

#define INST "dummy"

static const char *filters[] = { "run_init_process", "try_to_run_init_process", "dummy1", NULL };

int main(int argc, char *argv[])
{
        struct tracefs_instance *inst = tracefs_instance_create(INST);
        char **func_list;
        int ret;
        int i;

        if (!inst) {
                /* Error creating new trace instance */
        }

        if (tracefs_filter_functions("*lock*", NULL, &func_list) < 0) {
                printf("Failed to read filter functions\n");
                goto out;
        }
        printf("Ignoring the following functions:\n");
        for (i = 0; func_list[i]; i++)
                printf("  %s\n", func_list[i]);
        tracefs_list_free(func_list);

        /* Do not trace any function with the word "lock" in it */
        ret = tracefs_function_notrace(inst, "*lock*", NULL, TRACEFS_FL_RESET);
        if (ret) {
                printf("Failed to set the notrace filter\n");
                goto out;
        }

        /* First reset the filter */
        ret = tracefs_function_filter(inst, NULL, NULL,
                                      TRACEFS_FL_RESET | TRACEFS_FL_CONTINUE);
        if (ret) {
                printf("Failed to reset the filter\n");
                /* Make sure it is closed, -1 means filter was started */
                if (ret < 0)
                        tracefs_function_filter(inst, NULL, NULL, 0);
        }

        for (i = 0; filters[i]; i++) {
                ret = tracefs_function_filter(inst, filters[i], NULL,
                                              TRACEFS_FL_CONTINUE);

                if (ret) {
                        if (errno == EINVAL)
                                printf("Filter %s did not match\n", filters[i]);
                        else
                                printf("Failed writing %s\n", filters[i]);
                }
        }

        ret = tracefs_function_filter(inst, "*", "ext4", 0);
        if (ret) {
                printf("Failed to set filters for ext4\n");
                /* Force the function to commit previous filters */
                tracefs_function_filter(inst, NULL, NULL, 0);
        }

 out:
        tracefs_instance_destroy(inst);
        return ret;
}

🧚 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) — the whole friend group 🫶

🎀 AUTHOR 🎀

Steven Rostedt <rostedt@goodmis.org[1]>
Tzvetomir Stoyanov <tz.stoyanov@gmail.com[2]>
sameeruddin shaik <sameeruddin.shaik8@gmail.com[3]>

legends, honestly. 🌟

🌈 REPORTING BUGS 🌈

Report bugs to <linux-trace-devel@vger.kernel.org[4]> — they wanna hear from you, bestie 💌

🌸 LICENSE 🌸

libtracefs is Free Software licensed under the GNU LGPL 2.1 📜

🔗 RESOURCES 🔗

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

🍓 COPYING 🍓

🙈 NOTES 🙈

rostedt@goodmis.org mailto:rostedt@goodmis.org
tz.stoyanov@gmail.com mailto:tz.stoyanov@gmail.com
sameeruddin.shaik8@gmail.com mailto:sameeruddin.shaik8@gmail.com
linux-trace-devel@vger.kernel.org mailto:linux-trace-devel@vger.kernel.org

and that's the page!! signing off from libtracefs 1.8.4, dated 10/21/2026 — this was LIBTRACEFS(3), mwah 💋✨ go filter something, ily, bye 🎀

📦 where this page comes from

arch rolling: libtracefs 1.8.4-1 · GPL-2.0-only AND LGPL-2.1-only
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms