1libtracefs(3) 2============= 3 4NAME 5---- 6tracefs_filter_pid_function, tracefs_filter_pid_events, tracefs_filter_pid_function_clear, tracefs_filter_pid_events_clear - 7Add and remove PID filtering for functions and events 8 9SYNOPSIS 10-------- 11[verse] 12-- 13*#include <tracefs.h>* 14 15int *tracefs_filter_pid_function*(struct tracefs_instance pass:[*]_instance,_ int _pid_, 16 bool _reset_, bool _notrace_); 17int *tracefs_filter_pid_function_clear*(struct tracefs_instance pass:[*]_instance_, bool _notrace_); 18int *tracefs_filter_pid_events*(struct tracefs_instance pass:[*]_instance_, int _pid_, 19 bool _reset_, bool _notrace_); 20int *tracefs_filter_pid_events_clear*(struct tracefs_instance pass:[*]_instance_, bool _notrace_); 21-- 22 23DESCRIPTION 24----------- 25Both events and functions can be filtered by PID, but they are done separately. 26PID filtering for functions affect the function and function_graph tracer, where 27as PID filtering for events affect all events such as _sched_switch_ and _sched_waking_. 28If the *TRACEFS_OPTION_FUNCTION_FORK* is enabled (see *tracefs_option_enable*(3)), 29any PID that is set as part of the function PID filtering will automatically 30have its children added when they are spawned, as well as the PID removed when 31they exit. If the *TRACEFS_OPTION_EVENT_FORK* is set, the same is true for 32event PID filtering. This also includes the _notrace_ option where the child 33threads and processes of PIDs that are labled as notrace will also not be 34traced. 35 36The *tracefs_filter_pid_function()* affects function PID filtering and *tracefs_filter_pid_events()* 37affects the PID event filtering. For both functions, they add a _pid_ to be filtered in the given _instance_. 38If _reset_ is true, then any PIDs already being filtered will be removed, otherwise 39the _pid_ is simply added to the filtering. If _notrace_ is true, then the PID 40is added to the list of PIDs that are not to be traced. Note, that _reset_ only affects 41the list associated with _notrace_. That is, if both _reset_ and _notrace_ are true, 42then it will not affect PIDs that are to be traced. Same is if _reset_ is true and _notrace_ 43is false, it will not affect PIDs that are not to be traced. 44 45The *tracefs_filter_pid_function_clear()* affects function PID filtering and 46*tracefs_filter_pid_events_clear()* affects the PID event filtering. For both 47functions it will clear all the PIDs that are being filtered for the given 48filter. If _notrace_ is true it clears all the PIDs that are not to be traced 49otherwise if it is false, it clears all the PIDs that are to be traced. 50 51RETURN VALUE 52------------ 53All the functions return 0 on success and -1 on error. 54 55EXAMPLE 56------- 57[source,c] 58-- 59#include <stdlib.h> 60#include <stdio.h> 61#include <ctype.h> 62#include <tracefs.h> 63 64static void usage(char **argv) 65{ 66 fprintf(stderr, "usage: %s [-e|-f][-c|-n] pid [pid ...]\n", argv[0]); 67 fprintf(stderr, " -e enable event filter\n"); 68 fprintf(stderr, " -f enable function filter\n"); 69 fprintf(stderr, " (default is both, function and event)\n"); 70 fprintf(stderr, " -c clear the filter\n"); 71 fprintf(stderr, " -n notrace filter\n"); 72 exit(-1); 73} 74 75int main (int argc, char **argv) 76{ 77 bool events = false; 78 bool funcs = false; 79 bool neg = false; 80 bool clear = false; 81 bool reset = true; 82 int i; 83 84 for (i = 1; i < argc && argv[i][0] == '-'; i++) { 85 char *arg = argv[i]; 86 int c; 87 for (c = 1; arg[c]; c++) { 88 switch (arg[c]) { 89 case 'e': events = true; break; 90 case 'f': funcs = true; break; 91 case 'n': neg = true; break; 92 case 'c': clear = true; break; 93 default: 94 usage(argv); 95 } 96 } 97 if (c == 1) 98 usage(argv); 99 } 100 101 if (i == argc && !clear) 102 usage(argv); 103 104 if (!events && !funcs) { 105 events = true; 106 funcs = true; 107 } 108 109 if (clear) { 110 if (events) 111 tracefs_filter_pid_events_clear(NULL, neg); 112 if (funcs) 113 tracefs_filter_pid_function_clear(NULL, neg); 114 exit(0); 115 } 116 117 for (; i < argc; i++) { 118 int pid = atoi(argv[i]); 119 120 if (events) 121 tracefs_filter_pid_events(NULL, pid, reset, neg); 122 if (funcs) 123 tracefs_filter_pid_function(NULL, pid, reset, neg); 124 125 reset = false; 126 } 127 128 exit(0); 129} 130 131-- 132 133FILES 134----- 135[verse] 136-- 137*tracefs.h* 138 Header file to include in order to have access to the library APIs. 139*-ltracefs* 140 Linker switch to add when building a program that uses the library. 141-- 142 143SEE ALSO 144-------- 145*libtracefs*(3), 146*libtraceevent*(3), 147*trace-cmd*(1), 148*tracefs_hist_alloc*(3), 149*tracefs_hist_alloc_2d*(3), 150*tracefs_hist_alloc_nd*(3), 151*tracefs_hist_free*(3), 152*tracefs_hist_add_key*(3), 153*tracefs_hist_add_value*(3), 154*tracefs_hist_add_name*(3), 155*tracefs_hist_start*(3), 156*tracefs_hist_destory*(3), 157*tracefs_hist_add_sort_key*(3), 158*tracefs_hist_sort_key_direction*(3) 159 160AUTHOR 161------ 162[verse] 163-- 164*Steven Rostedt* <rostedt@goodmis.org> 165-- 166REPORTING BUGS 167-------------- 168Report bugs to <linux-trace-devel@vger.kernel.org> 169 170LICENSE 171------- 172libtracefs is Free Software licensed under the GNU LGPL 2.1 173 174RESOURCES 175--------- 176https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ 177 178COPYING 179------- 180Copyright \(C) 2023 Google, LLC. Free use of this software is granted under 181the terms of the GNU Public License (GPL). 182