LIBTRACEFS(3)

📦
version 1.8.4 · 13 versions
, in arch rolling

👑 LIBTRACEFS(3) — the libtracefs manual, bestie edition ✨

okay so this is the page for the libtracefs manual, and it's literally all about managing trace instances. stay with me, it's gonna slay 💅

🌸 NAME 🌸

tracefs_instance_create, tracefs_instance_destroy, tracefs_instance_alloc, tracefs_instance_free, tracefs_instance_is_new, tracefs_instances, tracefs_instance_clear, tracefs_instance_reset — Manage trace instances. that's the whole vibe 🎀

✨ SYNOPSIS ✨

#include <tracefs.h>

struct tracefs_instance *tracefs_instance_create(const char *name);
int tracefs_instance_destroy(struct tracefs_instance *instance);
struct tracefs_instance *tracefs_instance_alloc(const char *tracing_dir, const char *name);
void tracefs_instance_free(struct tracefs_instance *instance);
bool tracefs_instance_is_new(struct tracefs_instance *instance);
char **tracefs_instances(const char *regex);
void tracefs_instance_clear(struct tracefs_instance *instance);
void tracefs_instance_reset(struct tracefs_instance *instance);

🦋 DESCRIPTION 🦋

so this whole little family of functions is your group chat for managing trace instances. and what even is a trace instance? periodt, let me explain: it's a sub buffer used by the Linux tracing system. give it a unique name, and the events you enable inside it do not touch the main tracing system, and they don't touch other instances either — and the flip side is true too, the events enabled in the main tracing system or in other instances don't affect your instance. fully separate vibes, no crossover, iykyk 🌈

  • tracefs_instance_create() — this one allocates and initializes a new tracefs_instance structure and hands it right back to you 🫶. if the instance with name doesn't exist in the system yet, it gets created. the name can be NULL, and then the new tracefs_instance structure is initialized for the top instance. ⚠️ but note — the top instance cannot be created in the system, so if it doesn't exist, that's just how it is, no cap.
  • tracefs_instance_destroy() — removes the instance from the system, but does not free the structure. you still gotta call tracefs_instance_free() on instance. don't leave your girl hanging with a leak 😭
  • tracefs_instance_alloc() — allocates a new tracefs_instance structure for an instance that already exists. if the instance doesn't exist in the system, this function just fails, that's it, that's the tweet 💀. the tracing_dir parameter points to the system trace directory, and it can be NULL, in which case the default system trace directory is used. this parameter is genuinely iconic for allocating instances to trace directories that were copied from another machine 🧚. name is the name of the instance, or NULL for the top instance in the given tracing_dir.
  • tracefs_instance_free() — frees the tracefs_instance structure, without removing the trace instance from the system. bye structure, instance stays living its best life ✨
  • tracefs_instance_is_new() — checks if the given instance was newly created by tracefs_instance_create(), or whether it was already chilling in the system before that. the vibe check of functions, honestly 👑
  • tracefs_instances() — returns a list of instances that exist in the system which match the regular expression regex. if regex is NULL, then it matches all the instances that exist. the returned list must be freed with tracefs_list_free(3). 📌 and note — if no instances are found, an empty list is returned, and that empty list also needs to be freed with tracefs_list_free(3). free your empties, bestie, fr fr.
  • tracefs_instance_clear() — clears the ring buffer of the given instance, or the top level ring buffer if instance is NULL. fresh start energy 🍓
  • tracefs_instance_reset() — resets the given instance to its default state. factory settings, main character reborn 💜

🔥 RETURN VALUE 🔥

  • tracefs_instance_create() and tracefs_instance_alloc() return a pointer to a newly allocated tracefs_instance structure. it must be freed with tracefs_instance_free(). non-negotiable 🫶
  • tracefs_instance_destroy() returns 0 if it succeeds in removing the instance, otherwise it returns -1 if the instance does not exist or if it fails to remove it.
  • tracefs_instance_is_new() returns true if the tracefs_instance_create() that allocated instance also created the trace instance in the system, or false if the trace instance already existed in the system when instance was allocated by tracefs_instance_create() or tracefs_instance_alloc().
  • tracefs_instances() returns a list of instance names that exist on the system. the list must be freed with tracefs_list_free(3). an empty list is returned if no instance exists that matches regex, and this needs to be freed with tracefs_list_free(3) as well. NULL is returned on error 😭
  • tracefs_instance_clear() returns 0 if it successfully cleared the ring buffer, or -1 on error.

💖 EXAMPLE 💖

#include <tracefs.h>

struct tracefs_instance *inst = tracefs_instance_create("foo");
        if (!inst) {
                /* Error creating a new trace instance */
                ...
        }

        ...

        if (tracefs_instance_is_new(inst))
                tracefs_instance_destroy(inst);
        tracefs_instance_free(inst);
...

struct tracefs_instance *inst = tracefs_instance_alloc(NULL, "bar");
        if (!inst) {
                /* Error allocating 'bar' trace instance */
                ...
        }

        ...
        tracefs_instance_reset(inst);
        tracefs_instance_free(inst);

see how it's done? create it, check if it's new, destroy it if so, then free it. then alloc an existing one, reset it, free it. chef's kiss, no notes 👩‍🍳💋

🎀 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. add it, or your build will simply not go off 💅

⭐ SEE ALSO ⭐

libtracefs(3), libtraceevent(3), trace-cmd(1)

go read those too, the whole friend group is worth knowing 🫶

🌟 AUTHOR 🌟

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

icons, both of them 👑

🙈 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 🌈

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

and that's the page, bestie 🦋 this was libtracefs 1.8.4, dated 10/21/2026, and yes it's still called LIBTRACEFS(3) — mwah, go manage some instances, you've got this 💖✨

📦 where this page comes from