--- name: "tracefs_function_filter" section: "3" platform: "linux" package: "libtracefs" version: "1.8.4-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/tracefs_function_filter" --- # tracefs\_function\_filter(3) Functions to modify the the function trace filters ## NAME tracefs\_function\_filter, tracefs\_function\_notrace, tracefs\_filter\_functions - Functions to modify the the function trace filters ## SYNOPSIS ``` #include 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 **tracefs\_function\_filter** and **tracefs\_function\_notrace** can be used to limit the Linux kernel functions that would be traced by the function and function-graph tracers. The **tracefs\_function\_filter** defines a list of functions that can be traced. The **tracefs\_function\_notrace** defines a list of functions that will not be traced. If a function is in both lists, it will not be traced. They take an *instance* , that 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*, to limit the filtering on a specific module (or NULL to filter on all functions), *flags* which holds control knobs on how the filters will be handled (see **FLAGS**) section below. The **tracefs\_filter\_functions** returns a list of functions that can be filtered on via the *filter* and *module* that are supplied. If both *filter* and *module* are NULL then, all available functions that can be filtered is returned. On success, *list* must be freed with **tracefs\_list\_free()**(3). The *filter* may be either a straight match of a function, a glob or [regex(3)](/regex/3.md). A glob is where *\** matches zero or more characters, *?* will match zero or one character, and *.* only matches a period. 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)](/regex/3.md) following the rules of [regex(3)](/regex/3.md), and *.* is not a period, but will match any one character. To force a regular expression, either prefix *filter* with a *^* or append it with a *$* as the *filter* does complete matches of the functions anyway. 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*. 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. **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. **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. **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. 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. ## 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. 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. 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. ## 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. ## EXAMPLE ``` #include #include #include #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)](/libtracefs/3.md), [**libtraceevent**(3)](/libtraceevent/3.md), [**trace-cmd**(1)](/trace-cmd/1.md) ## AUTHOR ``` Steven Rostedt Tzvetomir Stoyanov sameeruddin shaik ``` ## REPORTING BUGS Report bugs to \<**linux-trace-devel@vger.kernel.org**\[4\]\> ## LICENSE libtracefs is Free Software licensed under the GNU LGPL 2.1 ## RESOURCES **https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/** ## COPYING Copyright (C) 2020 VMware, Inc. 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\. tz.stoyanov@gmail.com mailto:tz.stoyanov@gmail.com - 3\. sameeruddin.shaik8@gmail.com mailto:sameeruddin.shaik8@gmail.com - 4\. linux-trace-devel@vger.kernel.org mailto:linux-trace-devel@vger.kernel.org