'\" t
.\"     Title: libtracefs
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 07/25/2024
.\"    Manual: libtracefs Manual
.\"    Source: libtracefs 1.8.1
.\"  Language: English
.\"
.TH "LIBTRACEFS" "3" "07/25/2024" "libtracefs 1\&.8\&.1" "libtracefs Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
tracefs_function_filter, tracefs_function_notrace, tracefs_filter_functions \- Functions to modify the the function trace filters
.SH "SYNOPSIS"
.sp
.nf
\fB#include <tracefs\&.h>\fR

int \fBtracefs_function_filter\fR(struct tracefs_instance *\fIinstance\fR, const char *\fIfilter\fR, const char *\fImodule\fR, int \fIflags\fR);
int \fBtracefs_function_notrace\fR(struct tracefs_instance *\fIinstance\fR, const char *\fIfilter\fR, const char *\fImodule\fR, int \fIflags\fR);
int \fBtracefs_filter_functions\fR(const char *\fIfilter\fR, const char *\fImodule\fR, char ***\fIlist\fR);
.fi
.SH "DESCRIPTION"
.sp
\fBtracefs_function_filter\fR and \fBtracefs_function_notrace\fR can be used to limit the Linux kernel functions that would be traced by the function and function\-graph tracers\&. The \fBtracefs_function_filter\fR defines a list of functions that can be traced\&. The \fBtracefs_function_notrace\fR defines a list of functions that will not be traced\&. If a function is in both lists, it will not be traced\&.
.sp
They take an \fIinstance\fR , that can be NULL for the top level tracing, \fIfilter\fR, a string that represents a filter that should be applied to define what functions are to be traced, \fImodule\fR, to limit the filtering on a specific module (or NULL to filter on all functions), \fIflags\fR which holds control knobs on how the filters will be handled (see \fBFLAGS\fR) section below\&.
.sp
The \fBtracefs_filter_functions\fR returns a list of functions that can be filtered on via the \fIfilter\fR and \fImodule\fR that are supplied\&. If both \fIfilter\fR and \fImodule\fR are NULL then, all available functions that can be filtered is returned\&. On success, \fIlist\fR must be freed with \fBtracefs_list_free()\fR(3)\&.
.sp
The \fIfilter\fR may be either a straight match of a function, a glob or regex(3)\&. A glob is where \fI*\fR matches zero or more characters, \fI?\fR will match zero or one character, and \fI\&.\fR only matches a period\&. If the \fIfilter\fR is determined to be a regex (where it contains anything other than alpha numeric characters, or \fI\&.\fR, \fI*\fR, \fI?\fR) the \fIfilter\fR will be processed as a regex(3) following the rules of regex(3), and \fI\&.\fR is not a period, but will match any one character\&. To force a regular expression, either prefix \fIfilter\fR with a \fI^\fR or append it with a \fI$\fR as the \fIfilter\fR does complete matches of the functions anyway\&.
.sp
If \fImodule\fR is set and \fIfilter\fR is NULL, this will imply the same as \fIfilter\fR being equal to "*"\&. Which will enable all functions for a given \fImodule\fR\&. Otherwise the \fIfilter\fR may be NULL if a previous call to \fBtracefs_function_filter()\fR with the same \fIinstance\fR had \fBTRACEFS_FL_CONTINUE\fR set and this call does not\&. This is useful to simply commit the previous filters\&. It may also be NULL if \fBTRACEFS_FL_RESET\fR is set and the previous call did not have the same \fIinstance\fR and \fBTRACEFS_FL_CONTINUE\fR set\&. This is useful to just clear the filter\&.
.SH "FLAGS"
.sp
The \fIflags\fR parameter may have the following set, or be zero\&.
.sp
\fBTRACEFS_FL_RESET\fR : If \fIflags\fR contains \fBTRACEFS_FL_RESET\fR, then it will clear the filters that are currently set before applying \fIfilter\fR\&. Otherwise, \fIfilter\fR 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 \fIinstance\fR and the \fBTRACEFS_FL_CONTINUE\fR flag was set, then the function will fail with a return of \-1 and errno set to EBUSY\&.
.sp
\fBTRACEFS_FL_CONTINUE\fR : If \fIflags\fR contains \fBTRACEFS_FL_CONTINUE\fR, then \fIfilter\fR 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 \fBTRACEFS_FL_CONTINUE\fR 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 \fIfilter\fR passed in successfully matched)\&. A tracefs_function_filter() call after one that had the \fBTRACEFS_FL_CONTINUE\fR flag set for the same instance will fail if \fBTRACEFS_FL_RESET\fR flag is set, as the reset flag is only applicable for the first filter to be added before committing\&.
.sp
\fBTRACEFS_FL_FUTURE\fR : If \fIflags\fR contains \fBTRACEFS_FL_FUTURE\fR and \fImodule\fR 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 \fIfilter\fR is not a regular expression\&.
.SH "RETURN VALUE"
.sp
For \fBtracefs_function_filter()\fR and \fBtracefs_function_notrace()\fR 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\&.
.sp
If \fBTRACEFS_FL_CONTINUE\fR was set, and 0 or \-1 was returned, then another call to \fBtracefs_function_filter()\fR must be done without \fBTRACEFS_FL_CONTINUE\fR set in order to commit (and close) the filtering\&.
.sp
For \fBtracefs_filter_functions()\fR, a return of 0 means success, and the \fIlist\fR parameter is filled with a list of function names that matched \fIfilter\fR and \fImodule\fR\&. \fIlist\fR is a string array, where the last string pointer in the array is NULL\&. The \fIlist\fR must be freed with \fBtracefs_list_free()\fR\&. On failure, a negative is returned, and \fIlist\fR is ignored\&.
.SH "ERRORS"
.sp
\fBtracefs_function_filter\fR() can fail with the following errors:
.sp
\fBEINVAL\fR The filter is invalid or did not match any functions\&.
.sp
\fBEBUSY\fR The previous call of \fBtracefs_function_filter\fR() was called with the same instance and \fBTRACEFS_FL_CONTINUE\fR set and the current call had \fBTRACEFS_FL_RESET\fR set\&.
.sp
Other errors may also happen caused by internal system calls\&.
.SH "EXAMPLE"
.sp
.if n \{\
.RS 4
.\}
.nf
#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\en");
                goto out;
        }
        printf("Ignoring the following functions:\en");
        for (i = 0; func_list[i]; i++)
                printf("  %s\en", 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\en");
                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\en");
                /* 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\en", filters[i]);
                        else
                                printf("Failed writing %s\en", filters[i]);
                }
        }

        ret = tracefs_function_filter(inst, "*", "ext4", 0);
        if (ret) {
                printf("Failed to set filters for ext4\en");
                /* Force the function to commit previous filters */
                tracefs_function_filter(inst, NULL, NULL, 0);
        }

 out:
        tracefs_instance_destroy(inst);
        return ret;
}
.fi
.if n \{\
.RE
.\}
.SH "FILES"
.sp
.if n \{\
.RS 4
.\}
.nf
\fBtracefs\&.h\fR
        Header file to include in order to have access to the library APIs\&.
\fB\-ltracefs\fR
        Linker switch to add when building a program that uses the library\&.
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
\fBlibtracefs\fR(3), \fBlibtraceevent\fR(3), \fBtrace\-cmd\fR(1)
.SH "AUTHOR"
.sp
.if n \{\
.RS 4
.\}
.nf
\fBSteven Rostedt\fR <\m[blue]\fBrostedt@goodmis\&.org\fR\m[]\&\s-2\u[1]\d\s+2>
\fBTzvetomir Stoyanov\fR <\m[blue]\fBtz\&.stoyanov@gmail\&.com\fR\m[]\&\s-2\u[2]\d\s+2>
\fBsameeruddin shaik\fR <\m[blue]\fBsameeruddin\&.shaik8@gmail\&.com\fR\m[]\&\s-2\u[3]\d\s+2>
.fi
.if n \{\
.RE
.\}
.SH "REPORTING BUGS"
.sp
Report bugs to <\m[blue]\fBlinux\-trace\-devel@vger\&.kernel\&.org\fR\m[]\&\s-2\u[4]\d\s+2>
.SH "LICENSE"
.sp
libtracefs is Free Software licensed under the GNU LGPL 2\&.1
.SH "RESOURCES"
.sp
\m[blue]\fBhttps://git\&.kernel\&.org/pub/scm/libs/libtrace/libtracefs\&.git/\fR\m[]
.SH "COPYING"
.sp
Copyright (C) 2020 VMware, Inc\&. Free use of this software is granted under the terms of the GNU Public License (GPL)\&.
.SH "NOTES"
.IP " 1." 4
rostedt@goodmis.org
.RS 4
\%mailto:rostedt@goodmis.org
.RE
.IP " 2." 4
tz.stoyanov@gmail.com
.RS 4
\%mailto:tz.stoyanov@gmail.com
.RE
.IP " 3." 4
sameeruddin.shaik8@gmail.com
.RS 4
\%mailto:sameeruddin.shaik8@gmail.com
.RE
.IP " 4." 4
linux-trace-devel@vger.kernel.org
.RS 4
\%mailto:linux-trace-devel@vger.kernel.org
.RE