1libtracefs(3) 2============= 3 4NAME 5---- 6tracefs_function_filter, tracefs_function_notrace, tracefs_filter_functions 7- Functions to modify the the function trace filters 8 9SYNOPSIS 10-------- 11[verse] 12-- 13*#include <tracefs.h>* 14 15int *tracefs_function_filter*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_filter_, const char pass:[*]_module_, int _flags_); 16int *tracefs_function_notrace*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_filter_, const char pass:[*]_module_, int _flags_); 17int *tracefs_filter_functions*(const char pass:[*]_filter_, const char pass:[*]_module_, char pass:[*]pass:[*]pass:[*]_list_); 18-- 19 20DESCRIPTION 21----------- 22*tracefs_function_filter* and *tracefs_function_notrace* can be used to limit the 23Linux kernel functions that would be traced by the function and function-graph tracers. 24The *tracefs_function_filter* defines a list of functions that can be traced. 25The *tracefs_function_notrace* defines a list of functions that will not be traced. 26If a function is in both lists, it will not be traced. 27 28They take an _instance_ , that can be NULL for the top level tracing, 29_filter_, a string that represents a filter that should 30be applied to define what functions are to be traced, 31_module_, to limit the filtering on a specific module (or NULL to filter on all functions), 32_flags_ which holds control knobs on how the filters will be handled (see *FLAGS*) 33section below. 34 35The *tracefs_filter_functions* returns a list of functions that can be filtered on 36via the _filter_ and _module_ that are supplied. If both _filter_ and _module_ are 37NULL then, all available functions that can be filtered is returned. 38On success, _list_ must be freed with *tracefs_list_free()*(3). 39 40The _filter_ may be either a straight match of a 41function, a glob or regex(3). A glob is where 'pass:[*]' matches zero or more 42characters, '?' will match zero or one character, and '.' only matches a 43period. If the _filter_ is determined to be a regex (where it contains 44anything other than alpha numeric characters, or '.', 'pass:[*]', '?') the _filter_ 45will be processed as a regex(3) following the rules of regex(3), and '.' is 46not a period, but will match any one character. To force a regular 47expression, either prefix _filter_ with a '^' or append it with a '$' as 48the _filter_ does complete matches of the functions anyway. 49 50If _module_ is set and _filter_ is NULL, this will imply the same as _filter_ being 51equal to "pass:[*]". Which will enable all functions for a given _module_. Otherwise 52the _filter_ may be NULL if a previous call to *tracefs_function_filter()* with 53the same _instance_ had *TRACEFS_FL_CONTINUE* set and this call does not. This is 54useful to simply commit the previous filters. It may also be NULL 55if *TRACEFS_FL_RESET* is set and the previous call did not have the same _instance_ 56and *TRACEFS_FL_CONTINUE* set. This is useful to just clear the filter. 57 58FLAGS 59----- 60 61The _flags_ parameter may have the following set, or be zero. 62 63*TRACEFS_FL_RESET* : 64If _flags_ contains *TRACEFS_FL_RESET*, then it will clear the filters that 65are currently set before applying _filter_. Otherwise, _filter_ is added to 66the current set of filters already enabled. If this flag is set and the 67previous call to tracefs_function_filter() had the same _instance_ and the 68*TRACEFS_FL_CONTINUE* flag was set, then the function will fail with a 69return of -1 and errno set to EBUSY. 70 71*TRACEFS_FL_CONTINUE* : 72If _flags_ contains *TRACEFS_FL_CONTINUE*, then _filter_ will not take 73effect after a successful call to tracefs_function_filter(). This allows for 74multiple calls to tracefs_function_filter() to update the filter function 75and then a single call (one without the *TRACEFS_FL_CONTINUE* flag set) to 76commit all the filters. 77It can be called multiple times to add more filters. A call without this 78flag set will commit the changes before returning (if the _filter_ passed in 79successfully matched). A tracefs_function_filter() call after one that had 80the *TRACEFS_FL_CONTINUE* flag set for the same instance will fail if 81*TRACEFS_FL_RESET* flag is set, as the reset flag is only applicable for the 82first filter to be added before committing. 83 84*TRACEFS_FL_FUTURE* : 85If _flags_ contains *TRACEFS_FL_FUTURE* and _module_ holds a string of a module, 86then if the module is not loaded it will attemp to write the filter with the module 87in the filter file. Starting in Linux v4.13 module functions could be added to the 88filter before they are loaded. The filter will be cached, and when the module is 89loaded, the filter will be set before the module executes, allowing to trace 90init functions of a module. This will only work if the _filter_ is not a 91regular expression. 92 93RETURN VALUE 94------------ 95 96For *tracefs_function_filter()* and *tracefs_function_notrace()* a 97return of 0 means success. If the there is an error but the filtering was not 98started, then 1 is returned. If filtering was started but an error occurs, 99then -1 is returned. The state of the filtering may be in an unknown state. 100 101If *TRACEFS_FL_CONTINUE* was set, and 0 or -1 was returned, then another call 102to *tracefs_function_filter()* must be done without *TRACEFS_FL_CONTINUE* set 103in order to commit (and close) the filtering. 104 105For *tracefs_filter_functions()*, a return of 0 means success, and the _list_ 106parameter is filled with a list of function names that matched _filter_ and 107_module_. _list_ is a string array, where the last string pointer in the 108array is NULL. The _list_ must be freed with *tracefs_list_free()*. 109On failure, a negative is returned, and _list_ is ignored. 110 111ERRORS 112------ 113 114*tracefs_function_filter*() can fail with the following errors: 115 116*EINVAL* The filter is invalid or did not match any functions. 117 118*EBUSY* The previous call of *tracefs_function_filter*() was called 119with the same instance and *TRACEFS_FL_CONTINUE* set and the current call 120had *TRACEFS_FL_RESET* set. 121 122Other errors may also happen caused by internal system calls. 123 124EXAMPLE 125------- 126[source,c] 127-- 128#include <stdio.h> 129#include <errno.h> 130#include <tracefs.h> 131 132#define INST "dummy" 133 134static const char *filters[] = { "run_init_process", "try_to_run_init_process", "dummy1", NULL }; 135 136int main(int argc, char *argv[]) 137{ 138 struct tracefs_instance *inst = tracefs_instance_create(INST); 139 char **func_list; 140 int ret; 141 int i; 142 143 if (!inst) { 144 /* Error creating new trace instance */ 145 } 146 147 if (tracefs_filter_functions("*lock*", NULL, &func_list) < 0) { 148 printf("Failed to read filter functions\n"); 149 goto out; 150 } 151 printf("Ignoring the following functions:\n"); 152 for (i = 0; func_list[i]; i++) 153 printf(" %s\n", func_list[i]); 154 tracefs_list_free(func_list); 155 156 /* Do not trace any function with the word "lock" in it */ 157 ret = tracefs_function_notrace(inst, "*lock*", NULL, TRACEFS_FL_RESET); 158 if (ret) { 159 printf("Failed to set the notrace filter\n"); 160 goto out; 161 } 162 163 /* First reset the filter */ 164 ret = tracefs_function_filter(inst, NULL, NULL, 165 TRACEFS_FL_RESET | TRACEFS_FL_CONTINUE); 166 if (ret) { 167 printf("Failed to reset the filter\n"); 168 /* Make sure it is closed, -1 means filter was started */ 169 if (ret < 0) 170 tracefs_function_filter(inst, NULL, NULL, 0); 171 } 172 173 for (i = 0; filters[i]; i++) { 174 ret = tracefs_function_filter(inst, filters[i], NULL, 175 TRACEFS_FL_CONTINUE); 176 177 if (ret) { 178 if (errno == EINVAL) 179 printf("Filter %s did not match\n", filters[i]); 180 else 181 printf("Failed writing %s\n", filters[i]); 182 } 183 } 184 185 ret = tracefs_function_filter(inst, "*", "ext4", 0); 186 if (ret) { 187 printf("Failed to set filters for ext4\n"); 188 /* Force the function to commit previous filters */ 189 tracefs_function_filter(inst, NULL, NULL, 0); 190 } 191 192 out: 193 tracefs_instance_destroy(inst); 194 return ret; 195} 196-- 197 198FILES 199----- 200[verse] 201-- 202*tracefs.h* 203 Header file to include in order to have access to the library APIs. 204*-ltracefs* 205 Linker switch to add when building a program that uses the library. 206-- 207 208SEE ALSO 209-------- 210*libtracefs*(3), 211*libtraceevent*(3), 212*trace-cmd*(1) 213 214AUTHOR 215------ 216[verse] 217-- 218*Steven Rostedt* <rostedt@goodmis.org> 219*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com> 220*sameeruddin shaik* <sameeruddin.shaik8@gmail.com> 221-- 222REPORTING BUGS 223-------------- 224Report bugs to <linux-trace-devel@vger.kernel.org> 225 226LICENSE 227------- 228libtracefs is Free Software licensed under the GNU LGPL 2.1 229 230RESOURCES 231--------- 232https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ 233 234COPYING 235------- 236Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under 237the terms of the GNU Public License (GPL). 238