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 |FLAGS |RETURN VALUE |ERRORS |EXAMPLE |FILES |SEE ALSO |AUTHOR |REPORTING BUGS |LICENSE |RESOURCES |COPYING |NOTES |COLOPHON | |
LIBTRACEFS(3) libtracefs ManualLIBTRACEFS(3)tracefs_function_filter, tracefs_function_notrace, tracefs_filter_functions - Functions to modify the the function trace filters
#include <tracefs.h> inttracefs_function_filter(struct tracefs_instance *instance, const char *filter, const char *module, intflags); inttracefs_function_notrace(struct tracefs_instance *instance, const char *filter, const char *module, intflags); inttracefs_filter_functions(const char *filter, const char *module, char ***list);
tracefs_function_filterandtracefs_function_notracecan be used to limit the Linux kernel functions that would be traced by the function and function-graph tracers. Thetracefs_function_filter defines a list of functions that can be traced. Thetracefs_function_notracedefines a list of functions that will not be traced. If a function is in both lists, it will not be traced. They take aninstance , 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 (seeFLAGS) section below. Thetracefs_filter_functionsreturns a list of functions that can be filtered on via thefilter andmodule that are supplied. If bothfilter andmodule are NULL then, all available functions that can be filtered is returned. On success,list must be freed withtracefs_list_free()(3). Thefilter may be either a straight match of a function, a glob or regex(3). A glob is where* matches zero or more characters,? will match zero or one character, and. only matches a period. If thefilter is determined to be a regex (where it contains anything other than alpha numeric characters, or.,*,?) thefilter will be processed as a regex(3) following the rules of regex(3), and. is not a period, but will match any one character. To force a regular expression, either prefixfilter with a^ or append it with a$ as thefilter does complete matches of the functions anyway. Ifmodule is set andfilter is NULL, this will imply the same asfilter being equal to "*". Which will enable all functions for a givenmodule. Otherwise thefilter may be NULL if a previous call totracefs_function_filter()with the sameinstance hadTRACEFS_FL_CONTINUEset and this call does not. This is useful to simply commit the previous filters. It may also be NULL ifTRACEFS_FL_RESETis set and the previous call did not have the sameinstance andTRACEFS_FL_CONTINUEset. This is useful to just clear the filter.
Theflags parameter may have the following set, or be zero.TRACEFS_FL_RESET: Ifflags containsTRACEFS_FL_RESET, then it will clear the filters that are currently set before applyingfilter. 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 sameinstance and theTRACEFS_FL_CONTINUEflag was set, then the function will fail with a return of -1 and errno set to EBUSY.TRACEFS_FL_CONTINUE: Ifflags containsTRACEFS_FL_CONTINUE, thenfilter 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 theTRACEFS_FL_CONTINUEflag 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 thefilter passed in successfully matched). A tracefs_function_filter() call after one that had theTRACEFS_FL_CONTINUEflag set for the same instance will fail ifTRACEFS_FL_RESETflag is set, as the reset flag is only applicable for the first filter to be added before committing.TRACEFS_FL_FUTURE: Ifflags containsTRACEFS_FL_FUTUREandmodule 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 thefilter is not a regular expression.
Fortracefs_function_filter()andtracefs_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. IfTRACEFS_FL_CONTINUEwas set, and 0 or -1 was returned, then another call totracefs_function_filter()must be done withoutTRACEFS_FL_CONTINUEset in order to commit (and close) the filtering. Fortracefs_filter_functions(), a return of 0 means success, and thelist parameter is filled with a list of function names that matchedfilter andmodule.list is a string array, where the last string pointer in the array is NULL. Thelist must be freed withtracefs_list_free(). On failure, a negative is returned, andlist is ignored.
tracefs_function_filter() can fail with the following errors:EINVALThe filter is invalid or did not match any functions.EBUSYThe previous call oftracefs_function_filter() was called with the same instance andTRACEFS_FL_CONTINUEset and the current call hadTRACEFS_FL_RESETset. Other errors may also happen caused by internal system calls.
#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; }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.
libtracefs(3),libtraceevent(3),trace-cmd(1)
Steven Rostedt<rostedt@goodmis.org[1]>Tzvetomir Stoyanov<tz.stoyanov@gmail.com[2]>sameeruddin shaik<sameeruddin.shaik8@gmail.com[3]>
Report bugs to <linux-trace-devel@vger.kernel.org[4]>
libtracefs is Free Software licensed under the GNU LGPL 2.1
https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
Copyright (C) 2020 VMware, Inc. Free use of this software is granted under the terms of the GNU Public License (GPL).
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
This page is part of thelibtracefs (Linux kernel trace file system 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/libtracefs.git⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-06-02.) 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.orglibtracefs 1.7.0 12/22/2023LIBTRACEFS(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. | |