[RFC PATCH 4/4] Documentation/ftrace: Document function comm filters
From: <hidden>
Date: 2026-08-30 11:13:18
Also in:
linux-doc, lkml
Subsystem:
documentation, function hooks (ftrace), the rest, tracing · Maintainers:
Jonathan Corbet, Steven Rostedt, Masami Hiramatsu, Linus Torvalds
From: Shengming Hu <redacted> Document set_ftrace_comm and set_ftrace_notrace_comm, including their write and O_TRUNC behavior, accepted comm names, interaction with PID filters, and when a task is rechecked after its comm changes. Signed-off-by: Shengming Hu <redacted> --- Documentation/trace/ftrace.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+)
diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst
index 7261f25f8b4b..a96fc436ec16 100644
--- a/Documentation/trace/ftrace.rst
+++ b/Documentation/trace/ftrace.rst@@ -313,6 +313,37 @@ of ftrace. Here is a list of some of the key files: If a PID is in both this file and "set_ftrace_pid", then this file takes precedence, and the thread will not be traced. + set_ftrace_comm: + + Have the function and function_graph tracers trace only threads whose + task comm is listed in this file. Names are matched exactly and must + contain between 1 and TASK_COMM_LEN - 1 bytes. + + Each write adds one name. A single trailing newline is ignored, while + embedded newlines are rejected. A zero-length write or a write containing + only a newline adds no entry. Duplicate entries have no effect. + + Opening the file with O_TRUNC clears the filter. Otherwise, writes add + names to the existing filter. From a shell, use >> to add a name without + clearing the filter. Reading an empty filter prints `no comm`. + + If both set_ftrace_pid and set_ftrace_comm contain entries, a thread must + match both filters to be traced. + + set_ftrace_notrace_comm: + + Have the function and function_graph tracers ignore threads whose task + comm is listed in this file. Matching and file operations have the same + semantics as set_ftrace_comm. + + A match in either set_ftrace_notrace_pid or set_ftrace_notrace_comm + excludes the thread and takes precedence over all include filters. + + Function-tracer task filters are evaluated when a task is scheduled in, + and the result is cached per CPU. Changing a filter refreshes the result + for currently running tasks. If a running task changes its comm, it is + rechecked the next time it is scheduled in. + set_event_pid: Have the events only trace a task with a PID listed in this file.
--
2.25.1