LIBTRACEFS(3)

✨ LIBTRACEFS(3) ✨

okay bestie, welcome to the libtracefs Manual 💖 this one is all about the little functions that let you poke at trace event files without losing your whole entire mind. it's giving "I know the system and the event already, just gimme the file" energy, and honestly? iconic.

---

🌸 NAME 🌸

tracefs_event_get_file, tracefs_event_file_read, tracefs_event_file_write, tracefs_event_file_append, tracefs_event_file_clear, tracefs_event_file_exists — literally all the functions for working with trace event files 🎀

---

🦋 SYNOPSIS 🦋

#include <tracefs.h>

char *tracefs_event_get_file(struct tracefs_instance *instance, const char *system, const char *event,
                             const char *file);
char *tracefs_event_file_read(struct tracefs_instance *instance, const char *system, const char *event,
                              const char *file, int *psize);
int tracefs_event_file_write(struct tracefs_instance *instance, const char *system, const char *event,
                             const char *file, const char *str);
int tracefs_event_file_append(struct tracefs_instance *instance, const char *system, const char *event,
                              const char *file, const char *str);
int tracefs_event_file_clear(struct tracefs_instance *instance, const char *system, const char *event,
                             const char *file);
bool tracefs_event_file_exists(struct tracefs_instance *instance, const char *system, const char *event,
                               const char *file);

---

💅 DESCRIPTION 💅

so these are the functions for getting at tracefs event-specific files. they do the same kind of thing as the tracefs instance file functions, but they're way easier to reach when you already know the system and the event upfront. no cap, it's just less running around.

• tracefs_event_get_file() — returns the full path of the file for the given system and event, inside the given instance. if instance is NULL, you get the file for that event in the top level instance instead. ⚠️ heads up though: it does not check whether the file actually exists, and it doesn't even check whether the system and event exist. it just builds the path name for that event as if it did exist. this behaves like tracefs_instance_get_file(3), but it's the one you use to get to event files when the system and event are already known.
• tracefs_event_file_read() — reads the content of the event file for the given instance, or the top level instance if instance is NULL. you get the content back, and psize is set to the amount of data that was read. the returned content must be freed with free(3). behaves like tracefs_instance_file_read(3), but for reading the event file when the system and event are already known.
• tracefs_event_file_write() — writes str to the event file. it truncates anything already in that file, so don't say I didn't warn you 😭. behaves like tracefs_instance_file_write(3), but for the event file when the system and event are already known.
• tracefs_event_file_append() — appends str to the event file. it does not clear out the file when it writes the string. behaves like tracefs_instance_file_append(3), but for the event file when the system and event are already known.
• tracefs_event_file_clear() — clears the content of the event file. behaves like tracefs_instance_file_clear(3), but for the event file when the system and event are already known.
• tracefs_event_file_exists() — returns true if the event file exists, and false otherwise. behaves like tracefs_instance_file_exists(3), but for the event file when the system and event are already known.

---

🫶 RETURN VALUE 🫶

• tracefs_event_get_file() → returns the path of the given system/event file on success, and NULL on error. you gotta free that return value with tracefs_put_tracing_file(3).
• tracefs_event_file_read() → reads the content of the system/event file, or returns NULL on error. the returned pointer must be freed with free(3).
• tracefs_event_file_write() and tracefs_event_file_append() → return the number of bytes written to the system/event file, or a negative value on error.
• tracefs_event_file_clear() → returns zero on success, and -1 on error.
• tracefs_event_file_exists() → returns true if the system/event file exists for the given instance (or top level if instance is NULL), or false otherwise.

---

🧚 EXAMPLE 🧚

here's the whole demo program, copied exactly because we do not mess with code in this house 👑

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <tracefs.h>

int main(int argc, char **argv)
{
        char *system;
        char *event;
        char *file;
        char *cmd = NULL;
        char *buf;
        char *str;
        char ch = 'r';
        int size;

        if (argc < 4) {
                printf("usage: %s sytem event file [(-a|-w) write | -c]\n"
                       "   reads the system/event file or writes if [write is supplied]\n",
                       argv[0]);
                exit(0);
        }

        system = argv[1];
        event = argv[2];
        file = argv[3];
        if (argc > 4)
                cmd = argv[4];

        if (!tracefs_event_file_exists(NULL, system, event, file)) {
                fprintf(stderr, "File %s/%s/%s does not exist\n",
                                system, event, file);
                exit(-1);
        }

        if (cmd) {
                if (cmd[0] != '-')
                        ch = cmd[0];
                else
                        ch = cmd[1];
                if (!ch)
                        ch = 'c';
        }

        switch (ch) {
        case 'r':
                buf = tracefs_event_file_read(NULL, system, event, file, &size);
                if (buf)
                        printf("%s", buf);
                else
                        fprintf(stderr, "Failed to read %s/%s/%s\n",
                                system, event, file);
                free(buf);
                break;
        case 'w':
        case 'a':
                if (argc < 6) {
                        fprintf(stderr, "%s command requires something to write\n",
                                ch == 'w' ? "write" : "append");
                        exit(-1);
                }
                if (ch == 'w')
                        size = tracefs_event_file_write(NULL, system, event, file, argv[5]);
                else
                        size = tracefs_event_file_append(NULL, system, event, file, argv[5]);
                if (size < 0) {
                        fprintf(stderr, "Failed to write '%s' to %s/%s/%s\n",
                                        argv[5], system, event, file);
                        exit(-1);
                }
                break;
        case 'c':
                if (tracefs_event_file_clear(NULL, system, event, file) < 0) {
                        fprintf(stderr, "Failed to clear %s/%s/%s\n",
                                system, event, file);
                        exit(-1);
                }
                break;
        default:
                fprintf(stderr, "Unknown command '%c'\n", ch);
                exit(-1);
        }
        exit(0);
}

---

🍓 FILES 🍓

• tracefs.h — the header file you include so you can actually use 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)

---

👑 AUTHOR 👑

Steven Rostedt <rostedt@goodmis.org>

---

💀 REPORTING BUGS 💀

report bugs to <linux-trace-devel@vger.kernel.org> — they wanna hear about it, fr fr.

---

💜 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

---

and that's the whole page bestie 🦋✨ this was libtracefs 1.8.4, dated 10/21/2026 — go forth and read those event files, you absolute main character 💅💖