# tracefs_function_filter

## NAME



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


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



           **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



           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 <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.
    


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


* * *