LIBTRACEFS(3)

📦
version 1.8.4 · 11 versions
, in arch rolling

💖 libtracefs(3): opening trace_pipe_raw for reading 💖

okay so bestie, welcome to the libtracefs manual — specifically the little corner where we open raw trace_pipe_raw data and read it. it’s giving low-level trace-file energy, and honestly? iconic. 💅

✨ NAME ✨

tracefs_cpu_open, tracefs_cpu_close, tracefs_cpu_alloc_fd, tracefs_cpu_free_fd, tracefs_cpu_snapshot_open — opening trace_pipe_raw data for reading. 💖

📜 SYNOPSIS 📜

#include <tracefs.h>

struct tracefs_cpu *tracefs_cpu_open(struct tracefs_instance *instance,
                                     int cpu, bool nonblock);
void tracefs_cpu_close(struct tracefs_cpu *tcpu);

struct tracefs_cpu *tracefs_cpu_alloc_fd(int fd, int subbuf_size, bool nonblock);
void tracefs_cpu_free_fd(struct tracefs_cpu *tcpu);

struct tracefs_cpu *tracefs_cpu_snapshot_open(struct tracefs_instance *instance,
                                             int cpu, bool nonblock);

🌸 DESCRIPTION 🌸

okay so this whole API set opens the raw data from the trace_pipe_raw files in the tracefs file system so you can read them with the tracefs_cpu_read(3) functions. no cap, that’s the vibe. ✨

tracefs_cpu_open() creates a descriptor that can read the tracefs trace_pipe_raw file for a given cpu in a given instance. If instance is NULL, then the toplevel trace_pipe_raw file is used. 🫶

tracefs_cpu_close() closes all the file descriptors associated to the trace_pipe_raw opened by tracefs_cpu_open(). bye bye, fds 💅

tracefs_cpu_alloc_fd() will create a tracefs_cpu descriptor from an existing file descriptor fd. This is useful when connecting to a socket or pipe where the other end is feeding raw tracing data in the same format as the trace_pipe_raw file would (like in guest to host tracing). The caller is responsible for determining the subbuf_size that will be used to break up the sub-buffers being read by the file descriptor. The nonblock is treated the same as the same parameter in tracefs_cpu_open(). 🦋

tracefs_cpu_free_fd() is used to free the descriptor returned by tracefs_cpu_alloc_fd(). It does all the clean up that tracefs_cpu_close() performs. tracefs_cpu_close() could also be used to free up the descriptor created by tracefs_cpu_alloc_fd(), but it will also close the file descriptor passed in.

🚨 bestie warning: tracefs_cpu_free_fd() should not be used on the descriptor returned by tracefs_cpu_open(), because it will not close the file descriptor created by it.

tracefs_cpu_snapshot_open() is similar to tracefs_cpu_open() except that it opens the snapshot buffer (see tracefs_snapshot_snap(3)). The snapshot buffer does not have a writer to it; it is only created by a snapshot action that swaps the current ring buffer with the snapshot buffer. The nonblock, when false, acts a little differently here too. Reads are not affected by the "buffer_percent" file. If the snapshot buffer is empty, it will block until a new snapshot happens. 🌈

🎀 RETURN VALUE 🎀

The tracefs_cpu_open() and *tracefs_cpu_snapshot_open() both return a struct tracefs_cpu descriptor that can be used by the other functions or NULL on error. 💖

The tracefs_cpu_alloc_fd() returns a struct tracefs_cpu descriptor that can be used by the tracefs_cpu_read(3) related functions, where the descriptor will be reading the passed in fd file descriptor. ✨

🌟 EXAMPLE 🌟

See tracefs_cpu_read(3) for an example. that’s the one, bestie — go look 👀

🗂️ 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), libtraceevent(3), trace-cmd(1) — go read those too, fr fr.

👑 AUTHOR 👑

Steven Rostedt <rostedt@goodmis.org[1]> — iconic author behavior. 💜

🐛 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) 2022 Google, 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. linux-trace-devel@vger.kernel.org mailto:linux-trace-devel@vger.kernel.org

okay that’s literally the whole page, bestie — this one’s libtracefs 1.8.4, dated 10/21/2026. mwah, stay curious and keep those file descriptors close 💖✨🦋

📦 where this page comes from