# tracefs_filter_pid_function

## 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.
    


## 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
    


* * *