LIBTRACEFS(3)

📦
version 1.8.4 · 13 versions
, in arch rolling

💅 LIBTRACEFS(3) — bestie's guide to the libtracefs manual (section 3, we're fancy)

okay so this is the libtracefs manual page for all the little helper functions that help you work with tracing instances. if you've ever been like "what is even happening with my tracefs instances rn", this is the page. stay with me, it's giving useful.

✨ NAME ✨

tracefs_instance_get_name, tracefs_instance_get_trace_dir, tracefs_instances_walk, tracefs_instance_exists, tracefs_instance_get_buffer_size, tracefs_instance_set_buffer_size, tracefs_instance_get_buffer_percent, tracefs_instance_set_buffer_percent — helper functions for working with tracing instances 🎀

🌸 SYNOPSIS 🌸

#include <tracefs.h>

const char *tracefs_instance_get_name(struct tracefs_instance *instance);
const char *tracefs_instance_get_trace_dir(struct tracefs_instance *instance);
int tracefs_instances_walk(int (*callback)(const char *, void *), void *context);
bool tracefs_instance_exists(const char *name);
size_t tracefs_instance_get_buffer_size(struct tracefs_instance *instance, int cpu);
int tracefs_instance_set_buffer_size(struct tracefs_instance *instance, size_t size, int cpu);
int tracefs_instance_get_buffer_percent(struct tracefs_instance *instance);
int tracefs_instance_set_buffer_percent(struct tracefs_instance *instance, int val);

🦋 DESCRIPTION 🦋

so these are all helper functions for working with trace instances. literally the whole vibe. let's go one by one 💖

tracefs_instance_get_name() returns the name of the instance you hand it. plot twist tho: the top instance has no name, so for that one it returns NULL. no cap.

tracefs_instance_get_trace_dir() returns the tracing directory — y'know, the place where that instance is configured. that's it, that's the function. icon behavior.

tracefs_instances_walk() walks through all configured tracing instances in the system and calls callback for each one. the context argument gets passed to the callback, along with the instance name. if your callback returns non-zero, the iteration stops — like, we're done here bestie. ⚠️ note: the callback is not called for the top top instance.

tracefs_instance_exists() checks if an instance with the given name actually exists in the system. vibe check for instances fr fr.

tracefs_instace_get_buffer_size() — yes that's how it's spelled up in here 🙈 (same function, tracefs_instance_get_buffer_size) — returns the size of the ring buffer. if cpu is negative, it returns the total size of all the per CPU ring buffers; otherwise it returns the size of the per CPU ring buffer for cpu.

tracefs_instance_set_buffer_size() sets the size of the ring buffer. if cpu is negative, then it sets all the per CPU ring buffers to size — and heads up, the total size is the number of CPUs * size 🧮. if cpu is specified, then it only sets the size of that one per CPU ring buffer.

tracefs_instance_set_buffer_percent() sets the buffer percent value of the tracing ring buffer for instance, or the top level buffer if instance is NULL. and what does buffer percent even do? okay so it decides when readers on tracefs_cpu_read(3), tracefs_cpu_buffered_read(3), tracefs_cpu_write(3) and tracefs_cpu_pipe(3) will block when O_NONBLOCK is not set. the value of val must be between 0 and 100, where:

  • 0 — block until there's any data in the ring buffer
  • 1 — block until 1% of the ring buffer sub-buffers are filled
  • 50 — block until 50% of the ring buffer sub-buffers are filled
  • 100 — block until the entire ring buffer is filled
note: any number from 0 to 100 can be used — it's the percentage of the ring buffer that must be filled before a blocked reader gets notified that there's data to be retrieved. slay. 💅

tracefs_instance_get_buffer_percent() retrieves the current buffer percent setting of the tracing ring buffer for instance, or the top level buffer if instance is NULL. matching set, we love symmetry 🫶

👑 RETURN VALUE 👑

tracefs_instance_get_name() returns a string, or NULL in case of the top instance. the returned string must not be freed ⚠️

tracefs_instance_get_trace_dir() returns a string, or NULL in case of an error. the returned string must not be freed ⚠️

tracefs_instances_walk() returns 0 if all instances were iterated, 1 if the iteration was stopped by the callback, or -1 in case of an error.

tracefs_instance_exists() returns true if an instance with the given name exists in the system, or false otherwise.

tracefs_instance_get_buffer_size() returns the size of the ring buffer depending on the cpu value passed in, or -1 on error.

tracefs_instance_set_buffer_size() returns zero on success and -1 on error.

🌈 EXAMPLE 🌈

#include <tracefs.h>

struct tracefs_instance *inst;
....
char *name = tracefs_instance_get_name(inst);
        if(name) {
                /* Got name of the instance */
        }
char *dir = tracefs_instance_get_trace_dir(inst);
        if(dir) {
                /* Got tracing directory of the instance */
        }
...
static int instance_walk(char *name, void *context)
{
        /* Got instance with name */
        return 0;
}
...
        if (tracefs_instances_walk(instance_walk, NULL) < 0) {
                /* Error walking through the instances */
        }
...
        if (tracefs_instance_exists("foo")) {
                /* There is instance with name foo in the system */
        } else {
                /* There is no instance with name foo in the system */
        }

🍓 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)

💜 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]> — please actually report them, kthx 🙏

⭐ 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) 2020 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

k bye bestie!! 💖✨🦋 this was libtracefs 1.8.4, dated 10/21/2026 — go forth and walk those instances, you've got this 👑🌸

📦 where this page comes from