jammy (3) tracefs_function_filter.3.gz
NAME
tracefs_function_filter - Function to limit kernel functions that are traced tracefs_function_notrace -
Function to filter kernel functions that not to be traced
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);
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 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
Returns 0 on 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.
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); int ret; int i; if (!inst) { /* Error creating new trace instance */ } /* 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), libtraceevent(3), trace-cmd(1)
AUTHOR
Steven Rostedt <rostedt@goodmis.org[1]> Tzvetomir Stoyanov <tz.stoyanov@gmail.com[2]> sameeruddin shaik <sameeruddin.shaik8@gmail.com[3]>
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