hi steve, On 25/03/21 3:10 am, Steven Rostedt wrote:
In future, when the changes were made, i will change this man page accordingly.Hi Sameer! On Thu, 25 Mar 2021 22:01:30 +0530 Sameeruddin shaik <sameeruddin.shaik8@xxxxxxxxx> wrote:Added documentation for the below API: tracefs_function_filter() Signed-off-by: Sameeruddin shaik <sameeruddin.shaik8@xxxxxxxxx> diff --git a/Documentation/libtracefs-function-filter.txt b/Documentation/libtracefs-function-filter.txt new file mode 100644 index 0000000..08eece7 --- /dev/null +++ b/Documentation/libtracefs-function-filter.txt @@ -0,0 +1,116 @@ +libtracefs(3) +============= + +NAME +---- +tracefs_function_filter - Function to write to set_ftrace_filter +file of specific instance or top tracing instanceSince we are abstracting out tracefs, I'd like to avoid the implementation details, and keep it more about its functionality. - Function to limit kernel functions that are traced+ +SYNOPSIS +-------- +[verse] +-- +*#include <tracefs.h>* + +int tracefs_function_filter(struct tracefs_instance *instance, const char **filters, const char *module, bool reset, const char ***errs); +-- + +DESCRIPTION +----------- +This Function can be used to write to set_ftrace_file in the trace +filesystem, which will limit the trace to only those functions, +which were written in the file.To avoid stating the implementation: "This function can be used to limit the Linux kernel functions that is traced by the function and function-graph tracers."+ +It will take take _instance_argument, that can be NULL for the +top level tracing, _filters_, which is nothing but the array of theNo need to say "nothing" "which is an array of strings that represent a list of filters that should be applied to define what functions are to be traced. The array must end with a NULL pointer."+strings to write into the set_ftrace_filter file ,_module_ , name of the +module to be traced, _reset_, to reset or append the filters to file"_reset_ if set will clear the current set of filters and then apply the filter list, otherwise the list of filters are added to the current set of filters."+ and _errs_ which is again an array of failed filters, which can be NULL"and _errs_ is a pointer an array of strings, which will be allocated if any of filters fail to any available function. If _errs_ is NULL, it will be ignored."+ if failed filters are not of concern, and returns 0 on successful write, + 1 or -x (where x is an integer) on error.I mentioned in a previous email that I think we need to change the return value, but for now this is fine.
+ +RETURN VALUE +------------ +tracefs_function_filter will return 0 on successful write to file, if thereJust need to say ".. return 0 on success."+is error, it will return 1 for general errors or negative number -x(x denotes +number of failed filters), if there are any failed filters.Again, I think the error return may be changed, so we can leave this for now.+ +In case of negative return value, errs have to be checked and must be freed +using the free() + +EXAMPLE +------- +[source,c] +-- +#include <tracefs.h> + +#define INST "dummy" + +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); + const char **errs = NULL; + bool reset = 1; + int ret; + int i = 0; + + if (!inst) { + /* Error creating new trace instance*/ + } + + ret = tracefs_function_filter(inst, filters, NULL, reset, &errs); + + if (ret < 0 && errs) { + while (errs[i]) + printf("%s\n", errs[i++]); + } + + tracefs_instance_free(inst); + tracefs_instance_destroy(inst); + free(errs); + return 0;This looks fine. Thanks! -- Steve+} +-- + +FILES +----- +[verse] +-- +*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 +------ +[verse] +-- +*Steven Rostedt* <rostedt@xxxxxxxxxxx> +*Tzvetomir Stoyanov* <tz.stoyanov@xxxxxxxxx> +*sameeruddin shaik* <sameeruddin.shaik8@xxxxxxxxx> +-- +REPORTING BUGS +-------------- +Report bugs to <linux-trace-devel@xxxxxxxxxxxxxxx> + +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).
|