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

SYNOPSIS

       #include <tracefs.h>

       int tracefs_filter_pid_function(struct tracefs_instance *instance, int pid,
                                       bool reset, bool notrace);
       int tracefs_filter_pid_function_clear(struct tracefs_instance *instance, bool notrace);
       int tracefs_filter_pid_events(struct tracefs_instance *instance, int pid,
                                    bool reset, bool notrace);
       int tracefs_filter_pid_events_clear(struct tracefs_instance *instance, bool notrace);

DESCRIPTION

       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 sched_switch and sched_waking. If the
       TRACEFS_OPTION_FUNCTION_FORK is enabled (see tracefs_option_enable(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
       TRACEFS_OPTION_EVENT_FORK is set, the same is true for event PID filtering. This also
       includes the notrace option where the child threads and processes of PIDs that are labled
       as notrace will also not be traced.

       The tracefs_filter_pid_function() affects function PID filtering and
       tracefs_filter_pid_events() affects the PID event filtering. For both functions, they add
       a pid to be filtered in the given instance. If reset is true, then any PIDs already being
       filtered will be removed, otherwise the pid is simply added to the filtering. If notrace
       is true, then the PID is added to the list of PIDs that are not to be traced. Note, that
       reset only affects the list associated with notrace. That is, if both reset and notrace
       are true, then it will not affect PIDs that are to be traced. Same is if reset is true and
       notrace is false, it will not affect PIDs that are not to be traced.

       The tracefs_filter_pid_function_clear() affects function PID filtering and
       tracefs_filter_pid_events_clear() affects the PID event filtering. For both functions it
       will clear all the PIDs that are being filtered for the given filter. If notrace 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.

RETURN VALUE

       All the functions return 0 on success and -1 on error.

EXAMPLE

           #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 ...]\n", argv[0]);
                   fprintf(stderr, "   -e enable event filter\n");
                   fprintf(stderr, "   -f enable function filter\n");
                   fprintf(stderr, "     (default is both, function and event)\n");
                   fprintf(stderr, "   -c clear the filter\n");
                   fprintf(stderr, "   -n notrace filter\n");
                   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] == '-'; i++) {
                           char *arg = argv[i];
                           int c;
                           for (c = 1; arg[c]; c++) {
                                   switch (arg[c]) {
                                   case 'e': events = true; break;
                                   case 'f': funcs = true; break;
                                   case 'n': neg = true; break;
                                   case 'c': 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);
           }

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), tracefs_hist_alloc(3),
       tracefs_hist_alloc_2d(3), tracefs_hist_alloc_nd(3), tracefs_hist_free(3),
       tracefs_hist_add_key(3), tracefs_hist_add_value(3), tracefs_hist_add_name(3),
       tracefs_hist_start(3), tracefs_hist_destory(3), tracefs_hist_add_sort_key(3),
       tracefs_hist_sort_key_direction(3)

AUTHOR

           Steven Rostedt <rostedt@goodmis.org[1]>

REPORTING BUGS

       Report bugs to <linux-trace-devel@vger.kernel.org[2]>

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) 2023 Google, LLC. 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. linux-trace-devel@vger.kernel.org
           mailto:linux-trace-devel@vger.kernel.org