LIBTRACECMD(3)

🦋 LIBTRACECMD(3) — the libtracefs manual, bestie edition ✨

okay so this page is from the libtracefs manual, and it's literally all about peeking at tracing instances that are chillin' inside a trace file. let's get into it 💅

---

🌸 NAME 🌸

tracecmd_buffer_instances, tracecmd_buffer_instance_name, tracecmd_buffer_instance_handle — the little trio that lets you read tracing instances out of a trace file. that's the whole vibe 🫶

---

✨ SYNOPSIS ✨

#include <trace-cmd.h>

int tracecmd_buffer_instances(struct tracecmd_input *handle);
const char *tracecmd_buffer_instance_name(struct tracecmd_input *handle, int indx);
struct tracecmd_input *tracecmd_buffer_instance_handle(struct tracecmd_input *handle, int indx);

---

💖 DESCRIPTION 💖

so this whole set of APIs is your go-to for getting info and reading tracing data from tracing instances that are stored inside a trace file. iconic behavior tbh.

tracecmd_buffer_instances() gets you the number of tracing instances recorded in a trace file. ⚠️ heads up: the top instance is not counted, so don't come for me when the number's smaller than you expected. the handle is a tracecmd_input handler that came from tracecmd_open_head().

tracecmd_buffer_instance_name() gets you the name of the tracing instance at the given index indx, recorded in a trace file. the indx is a number in the interval [0 .. count-1], where count is the number that tracecmd_buffer_instances() gave you. and yeah, the handle is a tracecmd_input handler returned by tracecmd_open_head().

tracecmd_buffer_instance_handle() allocates and initializes a tracecmd_input handle that's associated with the trace instance at index indx from a trace file. again: handle is a tracecmd_input handler from tracecmd_open_head(), and indx is in the interval [0 .. count-1] where count came from tracecmd_buffer_instances(). slay, consistent indexing 🎀

---

🔥 RETURN VALUE 🔥

• tracecmd_buffer_instances() — returns the number of tracing instances recorded in a trace file. it's giving "just a number, no drama" ✨
• tracecmd_buffer_instance_name() — returns a string, the name of a tracing instance, or NULL in case of an error. > 🚨 the string must not be freed. like, do not touch it. put your hands down. it's not yours 😭
• tracecmd_buffer_instance_handle() — returns a pointer to a newly allocated tracecmd_input handler, or NULL in case of an error. > 🌸 the returned handler must be closed by tracecmd_close()(3) — don't just leave it hanging, that's rude.

---

🧚 EXAMPLE 🧚

here's the whole thing in action, bestie 👑

#include <trace-cmd.h>
...
struct tracecmd_input *handle = tracecmd_open_head("trace.dat");
        if (!handle) {
                /* Failed to open trace.dat file */
        }
...
int num = tracecmd_buffer_instances(handle);

        while(num) {
                struct tracecmd_input *h;
                char *name;

                name = tracecmd_buffer_instance_name(handle, num);
                if (!name) {
                        /* Failed to get name of instance num */
                }
                h = tracecmd_buffer_instance_handle(handle, num);
                if (!h) {
                        /* Failed to initialize handler for instance num */
                }

                ...
                tracecmd_close(h);
                num--;
        }
...
        tracecmd_close(handle);

see how we open it, loop through, close every h, then close the main handle? that's the self-care routine 💅

---

🎀 FILES 🎀

• trace-cmd.h — the header file to include so you actually have access to the library APIs. no include, no vibes.
• -ltracecmd — the linker switch to add when you're building a program that uses the library. don't forget it, or the linker will simply not know her 💀

---

🌈 SEE ALSO 🌈

libtracefs(3), libtraceevent(3), trace-cmd(1) trace-cmd.dat(5)

---

👑 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're lovely, promise 🫶

---

⭐ LICENSE ⭐

libtracecmd is Free Software licensed under the GNU LGPL 2.1. free as in freedom, bestie ✨

---

💜 RESOURCES 💜

https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/

go forth and clone 🔥

---

🍓 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

---

k that's the whole page!! 💖 this was the libtracefs manual, dated 03/09/2026, page LIBTRACECMD(3) — mwah, go read your trace files, ily 🎀🦋