tracefs_function_filter(3) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | FLAGS | RETURN VALUE | ERRORS | EXAMPLE | FILES | SEE ALSO | AUTHOR | REPORTING BUGS | LICENSE | RESOURCES | COPYING | NOTES | COLOPHON

LIBTRACEFS(3)               libtracefs Manual              LIBTRACEFS(3)

NAME         top

       tracefs_function_filter, tracefs_function_notrace,
       tracefs_filter_functions - Functions to modify the the function
       trace filters

SYNOPSIS         top

       #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         top

       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). 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) following the rules of
       regex(3), 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         top

       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         top

       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         top

       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         top

           #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         top

           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         top

       libtracefs(3), libtraceevent(3), trace-cmd(1)

AUTHOR         top

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

REPORTING BUGS         top

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

LICENSE         top

       libtracefs is Free Software licensed under the GNU LGPL 2.1

RESOURCES         top

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

COPYING         top

       Copyright (C) 2020 VMware, Inc. Free use of this software is
       granted under the terms of the GNU Public License (GPL).

NOTES         top

        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

COLOPHON         top

       This page is part of the libtracefs (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
       2024-06-14.  (At that time, the date of the most recent commit
       that was found in the repository was 2024-05-17.)  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 is not part of the original
       manual page), send a mail to man-pages@man7.org

libtracefs 1.7.0               12/22/2023                  LIBTRACEFS(3)