'\" t
.\"     Title: libtracefs
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 01/13/2024
.\"    Manual: libtracefs Manual
.\"    Source: libtracefs 1.8.0
.\"  Language: English
.\"
.TH "LIBTRACEFS" "3" "01/13/2024" "libtracefs 1\&.8\&.0" "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_filter_pid_function, tracefs_filter_pid_events, tracefs_filter_pid_function_clear, tracefs_filter_pid_events_clear \- Add and remove PID filtering for functions and events
.SH "SYNOPSIS"
.sp
.nf
\fB#include <tracefs\&.h>\fR

int \fBtracefs_filter_pid_function\fR(struct tracefs_instance *\fIinstance,\fR int \fIpid\fR,
                                bool \fIreset\fR, bool \fInotrace\fR);
int \fBtracefs_filter_pid_function_clear\fR(struct tracefs_instance *\fIinstance\fR, bool \fInotrace\fR);
int \fBtracefs_filter_pid_events\fR(struct tracefs_instance *\fIinstance\fR, int \fIpid\fR,
                             bool \fIreset\fR, bool \fInotrace\fR);
int \fBtracefs_filter_pid_events_clear\fR(struct tracefs_instance *\fIinstance\fR, bool \fInotrace\fR);
.fi
.SH "DESCRIPTION"
.sp
Both events and functions can be filtered by PID, but they are done separately\&. PID filtering for functions affect the function and function_graph tracer, where as PID filtering for events affect all events such as \fIsched_switch\fR and \fIsched_waking\fR\&. If the \fBTRACEFS_OPTION_FUNCTION_FORK\fR is enabled (see \fBtracefs_option_enable\fR(3)), any PID that is set as part of the function PID filtering will automatically have its children added when they are spawned, as well as the PID removed when they exit\&. If the \fBTRACEFS_OPTION_EVENT_FORK\fR is set, the same is true for event PID filtering\&. This also includes the \fInotrace\fR option where the child threads and processes of PIDs that are labled as notrace will also not be traced\&.
.sp
The \fBtracefs_filter_pid_function()\fR affects function PID filtering and \fBtracefs_filter_pid_events()\fR affects the PID event filtering\&. For both functions, they add a \fIpid\fR to be filtered in the given \fIinstance\fR\&. If \fIreset\fR is true, then any PIDs already being filtered will be removed, otherwise the \fIpid\fR is simply added to the filtering\&. If \fInotrace\fR is true, then the PID is added to the list of PIDs that are not to be traced\&. Note, that \fIreset\fR only affects the list associated with \fInotrace\fR\&. That is, if both \fIreset\fR and \fInotrace\fR are true, then it will not affect PIDs that are to be traced\&. Same is if \fIreset\fR is true and \fInotrace\fR is false, it will not affect PIDs that are not to be traced\&.
.sp
The \fBtracefs_filter_pid_function_clear()\fR affects function PID filtering and \fBtracefs_filter_pid_events_clear()\fR affects the PID event filtering\&. For both functions it will clear all the PIDs that are being filtered for the given filter\&. If \fInotrace\fR is true it clears all the PIDs that are not to be traced otherwise if it is false, it clears all the PIDs that are to be traced\&.
.SH "RETURN VALUE"
.sp
All the functions return 0 on success and \-1 on error\&.
.SH "EXAMPLE"
.sp
.if n \{\
.RS 4
.\}
.nf
#include <stdlib\&.h>
#include <stdio\&.h>
#include <ctype\&.h>
#include <tracefs\&.h>

static void usage(char **argv)
{
        fprintf(stderr, "usage: %s [\-e|\-f][\-c|\-n] pid [pid \&.\&.\&.]\en", argv[0]);
        fprintf(stderr, "   \-e enable event filter\en");
        fprintf(stderr, "   \-f enable function filter\en");
        fprintf(stderr, "     (default is both, function and event)\en");
        fprintf(stderr, "   \-c clear the filter\en");
        fprintf(stderr, "   \-n notrace filter\en");
        exit(\-1);
}

int main (int argc, char **argv)
{
        bool events = false;
        bool funcs = false;
        bool neg = false;
        bool clear = false;
        bool reset = true;
        int i;

        for (i = 1; i < argc && argv[i][0] == \*(Aq\-\*(Aq; i++) {
                char *arg = argv[i];
                int c;
                for (c = 1; arg[c]; c++) {
                        switch (arg[c]) {
                        case \*(Aqe\*(Aq: events = true; break;
                        case \*(Aqf\*(Aq: funcs = true; break;
                        case \*(Aqn\*(Aq: neg = true; break;
                        case \*(Aqc\*(Aq: clear = true; break;
                        default:
                                usage(argv);
                        }
                }
                if (c == 1)
                        usage(argv);
        }

        if (i == argc && !clear)
                usage(argv);

        if (!events && !funcs) {
                events = true;
                funcs = true;
        }

        if (clear) {
                if (events)
                        tracefs_filter_pid_events_clear(NULL, neg);
                if (funcs)
                        tracefs_filter_pid_function_clear(NULL, neg);
                exit(0);
        }

        for (; i < argc; i++) {
                int pid = atoi(argv[i]);

                if (events)
                        tracefs_filter_pid_events(NULL, pid, reset, neg);
                if (funcs)
                        tracefs_filter_pid_function(NULL, pid, reset, neg);

                reset = false;
        }

        exit(0);
}
.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), \fBtracefs_hist_alloc\fR(3), \fBtracefs_hist_alloc_2d\fR(3), \fBtracefs_hist_alloc_nd\fR(3), \fBtracefs_hist_free\fR(3), \fBtracefs_hist_add_key\fR(3), \fBtracefs_hist_add_value\fR(3), \fBtracefs_hist_add_name\fR(3), \fBtracefs_hist_start\fR(3), \fBtracefs_hist_destory\fR(3), \fBtracefs_hist_add_sort_key\fR(3), \fBtracefs_hist_sort_key_direction\fR(3)
.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>
.fi
.if n \{\
.RE
.\}
.SH "REPORTING BUGS"
.sp
Report bugs to <\m[blue]\fBlinux\-trace\-devel@vger\&.kernel\&.org\fR\m[]\&\s-2\u[2]\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) 2023 Google, LLC\&. 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
linux-trace-devel@vger.kernel.org
.RS 4
\%mailto:linux-trace-devel@vger.kernel.org
.RE