LIBTRACEFS(3)

📦
version 1.8.4 · 13 versions
, in arch rolling

💅 LIBTRACEFS(3) — bestie's guide to the libtracefs manual page ✨

okay so this whole page is out of the libtracefs manual (yeah, the libtracefs Manual one, iykyk) and it's literally all about poking at files and directories inside tracing instances 🦋 like... the humble little building blocks of everything. no cap.

🌸 NAME 🌸

tracefs_file_exists, tracefs_dir_exists, tracefs_instance_get_file, tracefs_instance_get_dir — working with files and directories in tracing instances, that's the whole vibe 💖

✨ SYNOPSIS ✨

#include <tracefs.h>

bool tracefs_file_exists(struct tracefs_instance *instance, char *name);
bool tracefs_dir_exists(struct tracefs_instance *instance, char *name);
char *tracefs_instance_get_file(struct tracefs_instance *instance, const char *file);
char *tracefs_instance_get_dir(struct tracefs_instance *instance);

look at her. iconic signatures. no notes 👑

🎀 DESCRIPTION 🎀

so this whole little family of APIs is for working with trace files in all trace instances, periodt. every single one of these takes an instance argument, and here's the tea: you can pass NULL and it'll act on the top level instance 🫶 otherwise it acts on an instance you made with tracefs_insance_create(3).

  • tracefs_file_exists() — checks if a file with name exists in instance 🍓
  • tracefs_dir_exists() — checks if a directory with name exists in instance 💜
  • tracefs_instance_get_file() — returns the full path of the file with the given name in instance. but bestie, heads up: it does not check if the file actually exists in the instance 🙈 it just gives you the path, main character energy
  • tracefs_instance_get_dir() — returns the full path of the directory with the given name in instance. and same warning, fr fr: it does not check if the directory exists in the instance 😭

🌈 RETURN VALUE 🌈

tracefs_file_exists() and tracefs_dir_exists() return true if the file / directory exists in the given instance, or false if it does not 💀 simple as.

tracefs_instance_get_file() and tracefs_instance_get_dir() return a string, or NULL in case of an error 😭 and you MUST free the returned string with tracefs_put_tracing_file() — don't leave her hanging, that's so rude 💅

🔥 EXAMPLE 🔥

here's the whole thing, verbatim, because we do not gatekeep 💖

#include <tracefs.h>

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

        if (tracefs_file_exists(inst,"trace_clock")) {
                /* The instance foo supports trace clock */
                char *path, *clock;
                int size;

                path =  = tracefs_instance_get_file(inst, "trace_clock")
                if (!path) {
                        /* Error getting the path to trace_clock file in instance foo */
                        ...
                }
                ...
                tracefs_put_tracing_file(path);

                clock = tracefs_instance_file_read(inst, "trace_clock", &size);
                if (!clock) {
                        /* Failed to read trace_clock file in instance foo */
                        ...
                }
                ...
                free(clock);

                if (tracefs_instance_file_write(inst, "trace_clock", "global") != strlen("global")) {
                        /* Failed to set gloabl trace clock in instance foo */
                        ...
                }
        } else {
                /* The instance foo does not support trace clock */
        }

        if (tracefs_dir_exists(inst,"options")) {
                /* The instance foo supports trace options */
                char *path = tracefs_instance_get_file(inst, "options");
                if (!path) {
                        /* Error getting the path to options directory in instance foo */
                        ...
                }

                tracefs_put_tracing_file(path);
        } else {
                /* The instance foo does not support trace options */
        }

        ...

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

        long long int res;
        if (tracefs_instance_file_read_number(NULL, "tracing_on", &res) == 0) {
                if (res == 0) {
                        /* tracing is disabled in the top instance */
                } else if (res == 1) {
                        /* tracing is enabled in the top instance */
                } else {
                        /* Unknown tracing state of the top instance */
                }
        } else {
                /* Failed to read integer from tracing_on file */
        }

        ...

        int fd;
        fd = tracefs_instance_file_open(NULL, "tracing_on", O_WRONLY);
        if (fd >= 0) {
                /* Got file descriptor to the tracing_on file from the top instance for writing */
                ...
                close(fd);
        }

(and yeah, path = = and "gloabl" are in there exactly like that, we're preserving the lore 🫡 don't come for me, I just work here 💀)

🧚 FILES 🧚

  • tracefs.h — the header file to include so you actually get access to the library APIs 🎀
  • -ltracefs — the linker switch you add when building a program that uses the library 🔗

🦋 SEE ALSO 🦋

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

go read those too, bestie, the crossover episode is real 👑

⭐ AUTHOR ⭐

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

absolute legends, tbh 🌟

💀 REPORTING BUGS 💀

Report bugs to <linux-trace-devel@vger.kernel.org[3]> — they genuinely want to hear it, no cap 🙏

🌸 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

okay and that's the whole page!! 🫶 it's libtracefs 1.8.4, dated 10/21/2026 — put that in your calendar bestie, mwah 💅✨

📦 where this page comes from