LIBTRACEFS(3)

📦
version 1.8.4 · 13 versions
, in arch rolling

💅 NAME 💅

hey bestie, welcome to LIBTRACEFS(3) — the libtracefs manual page, and it's giving "ftrace options explained by your favorite Unix-obsessed group chat" energy ✨

tracefs_options — ftrace options that can be controlled using the tracefs library 💖

🌸 SYNOPSIS 🌸

#include <tracefs.h>

enum tracefs_option_id {
        TRACEFS_OPTION_INVALID,
        TRACEFS_OPTION_ANNOTATE,
        TRACEFS_OPTION_BIN,
        TRACEFS_OPTION_BLK_CGNAME,
        TRACEFS_OPTION_BLK_CGROUP,
        TRACEFS_OPTION_BLK_CLASSIC,
        TRACEFS_OPTION_BLOCK,
        TRACEFS_OPTION_CONTEXT_INFO,
        TRACEFS_OPTION_DISABLE_ON_FREE,
        TRACEFS_OPTION_DISPLAY_GRAPH,
        TRACEFS_OPTION_EVENT_FORK,
        TRACEFS_OPTION_FGRAPH_ABSTIME,
        TRACEFS_OPTION_FGRAPH_CPU,
        TRACEFS_OPTION_FGRAPH_DURATION,
        TRACEFS_OPTION_FGRAPH_IRQS,
        TRACEFS_OPTION_FGRAPH_OVERHEAD,
        TRACEFS_OPTION_FGRAPH_OVERRUN,
        TRACEFS_OPTION_FGRAPH_PROC,
        TRACEFS_OPTION_FGRAPH_TAIL,
        TRACEFS_OPTION_FUNC_STACKTRACE,
        TRACEFS_OPTION_FUNCTION_FORK,
        TRACEFS_OPTION_FUNCTION_TRACE,
        TRACEFS_OPTION_GRAPH_TIME,
        TRACEFS_OPTION_HEX,
        TRACEFS_OPTION_IRQ_INFO,
        TRACEFS_OPTION_LATENCY_FORMAT,
        TRACEFS_OPTION_MARKERS,
        TRACEFS_OPTION_OVERWRITE,
        TRACEFS_OPTION_PAUSE_ON_TRACE,
        TRACEFS_OPTION_PRINTK_MSG_ONLY,
        TRACEFS_OPTION_PRINT_PARENT,
        TRACEFS_OPTION_RAW,
        TRACEFS_OPTION_RECORD_CMD,
        TRACEFS_OPTION_RECORD_TGID,
        TRACEFS_OPTION_SLEEP_TIME,
        TRACEFS_OPTION_STACKTRACE,
        TRACEFS_OPTION_SYM_ADDR,
        TRACEFS_OPTION_SYM_OFFSET,
        TRACEFS_OPTION_SYM_USEROBJ,
        TRACEFS_OPTION_TRACE_PRINTK,
        TRACEFS_OPTION_USERSTACKTRACE,
        TRACEFS_OPTION_VERBOSE,
};

🦋 DESCRIPTION 🦋

okay so this enum is basically the whole roster of ftrace options that can be manipulated using the tracefs library 👑

want the deep lore on any specific option? it lives in Documentation/trace/ftrace.rst from the Linux kernel tree, in the trace_options section. no cap 📚

heads up, bestie: some ftrace options cannot be manipulated by this library, because they're intended for internal, debug purposes. these options control the tracers or the trace output. every option has two states — on and off — and the default state is different for each of them 💅

🌈 Common options for all tracers 🌈

  • TRACEFS_OPTION_INVALID — not a valid ftrace option; it's used by the API to indicate an error.
  • TRACEFS_OPTION_ANNOTATE — display when a new CPU buffer started.
  • TRACEFS_OPTION_BIN — display the formats in raw binary.
  • TRACEFS_OPTION_CONTEXT_INFO — show only the event data. hides the comm, PID, timestamp, CPU, and other useful data.
  • TRACEFS_OPTION_BLOCK — when set, reading trace_pipe will not block when polled.
  • TRACEFS_OPTION_DISABLE_ON_FREE — when the free_buffer is closed, tracing will stop.
  • TRACEFS_OPTION_DISPLAY_GRAPH — when set, the latency tracers will use function graph tracing instead of function tracing.
  • TRACEFS_OPTION_EVENT_FORK — when set, tasks with PIDs listed in set_event_pid will have the PIDs of their children added to set_event_pid when those tasks fork.
  • TRACEFS_OPTION_FUNCTION_FORK — when set, tasks with PIDs listed in set_ftrace_pid will have the PIDs of their children added to set_ftrace_pid when those tasks fork.
  • TRACEFS_OPTION_FUNCTION_TRACE — when enabled, the latency tracers will trace functions.
  • TRACEFS_OPTION_HEX — display numbers in a hexadecimal format.
  • TRACEFS_OPTION_IRQ_INFO — display the interrupt, preempt count, need resched data.
  • TRACEFS_OPTION_LATENCY_FORMAT — display additional information about the latency.
  • TRACEFS_OPTION_MARKERS — when set, the trace_marker is enabled — writable (only by root).
  • TRACEFS_OPTION_OVERWRITE — controls what happens when the trace buffer is full. if set, the oldest events are discarded and overwritten. if disabled, then the newest events are discarded.
  • TRACEFS_OPTION_PAUSE_ON_TRACE — when set, opening the trace file for read will pause writing to the ring buffer. when the file is closed, tracing will be enabled again.
  • TRACEFS_OPTION_PRINTK_MSG_ONLY — when set, trace_printk()s will only show the format and not their parameters.
  • TRACEFS_OPTION_PRINT_PARENT — on function traces, display the calling (parent) function as well as the function being traced.
  • TRACEFS_OPTION_RAW — display raw numbers.
  • TRACEFS_OPTION_RECORD_CMD — save a mapping with a pid and corresponding command.
  • TRACEFS_OPTION_RECORD_TGID — save a mapping with a pid and corresponding Thread Group IDs.
  • TRACEFS_OPTION_STACKTRACE — record a stack trace after any trace event.
  • TRACEFS_OPTION_SYM_ADDR — display the function address as well as the function name.
  • TRACEFS_OPTION_SYM_OFFSET — display not only the function name, but also the offset in the function.
  • TRACEFS_OPTION_SYM_USEROBJ — when TRACEFS_OPTION_USERSTACKTRACE is set, look up which object the address belongs to, and print the object and a relative address.
  • TRACEFS_OPTION_TRACE_PRINTK — disable trace_printk() from writing into the buffer.
  • TRACEFS_OPTION_USERSTACKTRACE — records a stack trace of the current user space thread after each trace event.
  • TRACEFS_OPTION_VERBOSE — when TRACEFS_OPTION_LATENCY_FORMAT is enabled, print more detailed information.

🧚 Options, specific to function tracer 🧚

  • TRACEFS_OPTION_FUNC_STACKTRACE — record a stack trace after every function.

🎀 Options, specific to function_graph tracer 🎀

  • TRACEFS_OPTION_FGRAPH_ABSTIME — display the timestamp at each line.
  • TRACEFS_OPTION_FGRAPH_CPU — display the CPU number of the CPU where the trace occurred.
  • TRACEFS_OPTION_FGRAPH_DURATION — display the duration of the amount of time at the end of each function, in microseconds.
  • TRACEFS_OPTION_FGRAPH_IRQS — trace functions that happen inside an interrupt.
  • TRACEFS_OPTION_FGRAPH_OVERHEAD — display a marker if a function takes longer than a certain amount of time.
  • TRACEFS_OPTION_FGRAPH_OVERRUN — display "overrun" of the call graph, in the case of functions missed due to big callstack.
  • TRACEFS_OPTION_FGRAPH_PROC — display the command of each process at every line.
  • TRACEFS_OPTION_FGRAPH_TAIL — display the function name on its return.
  • TRACEFS_OPTION_SLEEP_TIME — account time the task has been scheduled out as part of the function call.
  • TRACEFS_OPTION_GRAPH_TIME — display the time to call nested functions, if function profiler is enabled.

🍓 Options, specific to blk tracer 🍓

  • TRACEFS_OPTION_BLK_CGNAME — listed here under the blk tracer options; the source gives no extra description for this one.
  • TRACEFS_OPTION_BLK_CGROUP — also listed here under the blk tracer options; no extra description in the source either.
  • TRACEFS_OPTION_BLK_CLASSIC — display a more minimalistic output.

🌟 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 👀

🫶 AUTHOR 🫶

  • Steven Rostedt — rostedt@goodmis.org [1]
  • Tzvetomir Stoyanov — tz.stoyanov@gmail.com [2]

🐛 REPORTING BUGS 🐛

report bugs to linux-trace-devel@vger.kernel.org [3] 💌

📜 LICENSE 📜

libtracefs is Free Software licensed under the GNU LGPL 2.1.

🔗 RESOURCES 🔗

💖 COPYING 💖

Copyright (C) 2021 VMware, Inc. 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. tz.stoyanov@gmail.com — mailto:tz.stoyanov@gmail.com
  3. linux-trace-devel@vger.kernel.org — mailto:linux-trace-devel@vger.kernel.org

okay that's the whole page, bestie — xoxo, your libtracefs hype girl 💖 this was libtracefs 1.8.4, dated 10/21/2026. periodt 🦋

📦 where this page comes from