--- name: "tracefs_filter_pid_function" section: "3" platform: "linux" package: "libtracefs" version: "1.8.4-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/tracefs_filter_pid_function" --- # tracefs\_filter\_pid\_function(3) Add and remove PID filtering for functions and events ## 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 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)](/tracefs_option_enable/3.md)), 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 #include #include #include 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)](/libtracefs/3.md), [**libtraceevent**(3)](/libtraceevent/3.md), [**trace-cmd**(1)](/trace-cmd/1.md), [**tracefs\_hist\_alloc**(3)](/tracefs_hist_alloc/3.md), [**tracefs\_hist\_alloc\_2d**(3)](/tracefs_hist_alloc_2d/3.md), [**tracefs\_hist\_alloc\_nd**(3)](/tracefs_hist_alloc_nd/3.md), [**tracefs\_hist\_free**(3)](/tracefs_hist_free/3.md), [**tracefs\_hist\_add\_key**(3)](/tracefs_hist_add_key/3.md), [**tracefs\_hist\_add\_value**(3)](/tracefs_hist_add_value/3.md), [**tracefs\_hist\_add\_name**(3)](/tracefs_hist_add_name/3.md), [**tracefs\_hist\_start**(3)](/tracefs_hist_start/3.md), **tracefs\_hist\_destory**(3), [**tracefs\_hist\_add\_sort\_key**(3)](/tracefs_hist_add_sort_key/3.md), [**tracefs\_hist\_sort\_key\_direction**(3)](/tracefs_hist_sort_key_direction/3.md) ## AUTHOR ``` Steven Rostedt ``` ## 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