LIBTRACEFS(3)

✨ LIBTRACEFS(3) — snapshot slay era ✨

okay bestie, welcome to the libtracefs manual for the snapshot squad. We’re talking tracefs_snapshot_snap, tracefs_snapshot_clear, and tracefs_snapshot_free — the create/clear/read snapshot API. It’s giving kernel tracing, but make it cute 🎀

---

🌸 NAME 🌸

tracefs_snapshot_snap, tracefs_snapshot_clear, tracefs_snapshot_free — API to create, clear and read snapshots 💅

---

✨ SYNOPSIS ✨

#include <tracefs.h>

int tracefs_snapshot_snap(struct tracefs_instance *instance);
int tracefs_snapshot_clear(struct tracefs_instance *instance);
int tracefs_snapshot_free(struct tracefs_instance *instance);

---

💖 DESCRIPTION 💖

So the Linux kernel tracing girlies have this thing called a "snapshot" feature. The kernel has two ring buffers: one that the tracing system writes to, and another one that is the "snapshot" buffer. When a snapshot happens, the two buffers are swapped — the current snapshot buffer becomes the one being written to, and the buffer that was being written to becomes the saved snapshot. Literally swapping main character energy 🔥

real talk: the snapshot buffer is allocated the first time it is taken, so it is best to take a snapshot at the start before one is needed so that it is allocated and a snapshot is ready. Then the snapshot will happen immediately. no cap, plan ahead bestie 💅

tracefs_snapshot_snap() will allocate the snapshot buffer if it’s not already allocated, and then take a "snapshot" — aka swap the main buffer that’s being written to with the allocated snapshot buffer. It does this to the given instance buffer, or the top instance if instance is NULL. slay 🦋

tracefs_snapshot_clear() will erase the content of the snapshot buffer for the given instance, or the top level instance if instance is NULL. clean slate vibes ✨

tracefs_snapshot_free() will free the allocated snapshot for the given instance, or the top level instance if instance is NULL. That is, if another call to tracefs_snapshot_snap() is done after this, then it will need to allocate the snapshot buffer again before it can take a snapshot. This function should be used to free up the kernel memory used by hte snapshot buffer when no longer in use. (yes, hte is literally in the original 😭 not me, bestie)

---

🔥 RETURN VALUE 🔥

tracefs_snapshot_snap(), tracefs_snapshot_clear() and tracefs_snapshot_free() all return 0 on success and -1 on failure. periodt 💀

---

🎀 EXAMPLE 🎀

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

           static int callback(struct tep_event *event, struct tep_record *record, int cpu, void *data)
           {
                   static struct trace_seq seq;
                   struct tep_handle *tep = event->tep;

                   if (!seq.buffer)
                           trace_seq_init(&seq);

                   trace_seq_reset(&seq);

                   tep_print_event(tep, &seq, record, "[%03d] %s-%d %6.1000d\t%s: %s\n",
                                           TEP_PRINT_CPU,
                                           TEP_PRINT_COMM,
                                           TEP_PRINT_PID,
                                           TEP_PRINT_TIME,
                                           TEP_PRINT_NAME,
                                           TEP_PRINT_INFO);
                   trace_seq_do_printf(&seq);
                   return 0;
           }

           int main (int argc, char **argv)
           {
                   struct tracefs_instance *instance;
                   struct tep_handle *tep;
                   char *line = NULL;
                   size_t len = 0;
                   int ret;

                   instance = tracefs_instance_create("my_snapshots");
                   if (!instance) {
                           perror("creating instance");
                           exit(-1);
                   }

                   tep = tracefs_local_events(NULL);
                   if (!tep) {
                           perror("reading event formats");
                           goto out;
                   }

                   /* Make sure the snapshot buffer is allocated */
                   ret = tracefs_snapshot_snap(instance);
                   if (ret < 0)
                           goto out;

                   ret = tracefs_event_enable(instance, "sched", NULL);
                   if (ret < 0) {
                           perror("enabling event");
                           goto out;
                   }

                   for (;;) {
                           printf("Hit enter without text to take snapshot!\n");
                           printf("Enter any text to display the snapshot\n");
                           printf("Enter 'quit' to exit\n");
                           getline(&line, &len, stdin);
                           ret = tracefs_snapshot_snap(instance);
                           if (ret < 0) {
                                   perror("taking snapshot");
                                   goto out;
                           }
                           if (!line)
                                   break;
                           if (strlen(line) < 2)
                                   continue;
                           if (strncmp(line, "quit", 4) == 0)
                                   break;
                           tracefs_iterate_snapshot_events(tep, instance, NULL, 0, callback, NULL);
                   }

                   free(line);

                   tracefs_instance_clear(instance);

            out:
                   tracefs_snapshot_free(instance);
                   tracefs_event_disable(instance, "sched", NULL);
                   tracefs_instance_destroy(instance);
                   tracefs_instance_free(instance);

                   exit(0);
           }

---

🦋 FILES 🦋

• tracefs.h — header file to include in order to have access to the library APIs. include her, bestie 💖
• -ltracefs — linker switch to add when building a program that uses the library. yes, add it to your build, iykyk 🌈

---

🌈 SEE ALSO 🌈

• tracefs_iterate_snapshot_events(3)
• libtracefs(3)
• libtraceevent(3)
• trace-cmd(1)

go read the whole friend group, fr fr 🫶

---

👑 AUTHOR 👑

Steven Rostedt — rostedt@goodmis.org [1] — icon behavior 👑

---

💀 REPORTING BUGS 💀

Report bugs to linux-trace-devel@vger.kernel.org [2]. please be nice and specific, bestie 🙈

---

⭐ LICENSE ⭐

libtracefs is Free Software licensed under the GNU LGPL 2.1. slay and respect the license 💅

---

🧚 RESOURCES 🧚

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

the source is right there, go off 🔥

---

🍓 COPYING 🍓

Copyright (C) 2023 Google, LLC. 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

---

signing off from libtracefs 1.8.4, dated 10/21/2026 — go take that snapshot, bestie 💅✨