LIBTRACEFS(3)

📦

version 1.8.4 · 13 versions

💅 LIBTRACEFS(3) — the libtracefs manual, bestie edition 🎀

okay so this is the libtracefs manual page, and today we're learning how to poke at files inside tracing instances. it's giving "backstage pass to the kernel" energy and honestly? iconic. let's get into it. ✨

🌸 NAME 🌸

tracefs_instance_file_open, tracefs_instance_file_write, tracefs_instance_file_write_number, tracefs_instance_file_append, tracefs_instance_file_clear, tracefs_instance_file_read, tracefs_instance_file_read_number — literally all the ways to work with files in tracing instances 💖

⭐ SYNOPSIS ⭐

#include <tracefs.h>

int tracefs_instance_file_open(struct tracefs_instance *instance, const char *file, int mode);
int tracefs_instance_file_write(struct tracefs_instance *instance, const char *file, const char *str);
int tracefs_instance_file_write_number(struct tracefs_instance *instance, const char *file, size_t val);
int tracefs_instance_file_append(struct tracefs_instance *instance, const char *file, const char *str);
int tracefs_instance_file_clear(struct tracefs_instance *instance, const char *file);
char *tracefs_instance_file_read(struct tracefs_instance *instance, const char *file, int *psize);
int tracefs_instance_file_read_number(struct tracefs_instance *instance, const char *file, long long int *res);

🦋 DESCRIPTION 🦋

so this whole little family of APIs? they're for working with trace files across all the trace instances. every single one of them takes an instance argument, and bestie, that argument can be NULL to act on the top level instance. otherwise it acts on an instance you made with tracefs_insance_create(3). 💫

tracefs_instance_file_open() — opens a trace file from the given instance and hands you back a file descriptor to it. you get to specify the file access mode (peep open(3) for the deets). and if you pass -1 as the mode, it just defaults to O_RDWR. easy. 🫶
tracefs_instance_file_write() — writes a string str into a file from the given instance, without the terminating NULL character. lowkey important: when it opens the file, it tries to truncate the size to zero, which clears all the previously existing settings. so yeah, it's a fresh-start kinda function. 🔥
tracefs_instance_file_write_number() — converts val into a string and then writes it to the given file. it's a helper that does the number→string conversion and then calls tracefs_instance_file_write(). teamwork, fr fr. 💜
tracefs_instance_file_append() — writes a string str into a file from the given instance, without the terminating NULL character. sounds like tracefs_instance_file_write(), right? the difference is it does not clear the existing content. so the new settings get appended onto whatever was already there (if anything). ✨
tracefs_instance_file_clear() — tries to truncate the size of the file to zero, which clears all previously existing settings. but heads up 🫣: if the file has content that doesn't get cleared this way, this will have no effect at all.
tracefs_instance_file_read() — reads the content of a file from the given instance. simple as that. 📖
tracefs_instance_file_read_number() — reads the content of a file from the given instance and converts it into a long long integer, which gets stored in res. math but make it cute. 🧮

👑 RETURN VALUE 👑

tracefs_instance_file_open() — returns a file descriptor to the opened file. you must close it with close(3). if something goes wrong, you get -1. 😭
tracefs_instance_file_write() — returns the number of written bytes, or -1 if there's an error.
tracefs_instance_file_write_number() — returns 0 on success and -1 on error.
tracefs_instance_file_append() — returns the number of written bytes, or -1 in case of an error.
tracefs_instance_file_clear() — returns 0 on success, or -1 in case of an error.
tracefs_instance_file_read() — returns a pointer to a NULL terminated string, read from the file, or NULL in case of an error. and pookie, the returned string has to be freed with free(). don't forget. 🎀
tracefs_instance_file_read_number() — returns 0 if a valid integer is read from the file and stored in res, or -1 in case of an error.

🌈 EXAMPLE 🌈

okay here's the whole vibe in code — copying it exactly because code is sacred 🫶:

#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);
        }

🎀 FILES 🎀

tracefs.h — the header file you include so you can actually access the library APIs. bestie you need this one.
-ltracefs — the linker switch you add when building a program that uses the library. don't skip it 💅

go read those too, iykyk. 📚

💖 AUTHOR 💖

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

🙈 REPORTING BUGS 🙈

found a bug? report it to <linux-trace-devel@vger.kernel.org[3]> — they wanna know, no cap.

💀 LICENSE 💀

libtracefs is Free Software licensed under the GNU LGPL 2.1. slay.

🌟 RESOURCES 🌟

https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/

that's the link, go be nosy. 🧚

🍓 COPYING 🍓

⭐ NOTES ⭐

rostedt@goodmis.org mailto:rostedt@goodmis.org
tz.stoyanov@gmail.com mailto:tz.stoyanov@gmail.com
linux-trace-devel@vger.kernel.org mailto:linux-trace-devel@vger.kernel.org

okay that's the whole page, you ate that 💅✨ this was libtracefs version 1.8.4, dated 10/21/2026 — go forth and trace some files, bestie, you got this 🫶🎀🦋

📦 where this page comes from

arch rolling: libtracefs 1.8.4-1 · GPL-2.0-only AND LGPL-2.1-only
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms