LIBTRACECMD(3)

🦋 LIBTRACECMD(3) 🦋

okay so bestie, welcome to the libtracefs manual page for LIBTRACECMD(3) — this is the one about opening and closing trace files, and I promise it's gonna make sense 💖

---

✨ NAME ✨

tracecmd_open, tracecmd_open_fd, tracecmd_open_head, tracecmd_init_data, tracecmd_close, tracecmd_set_private, tracecmd_get_private — open and close a trace file 🎀

---

🌈 SYNOPSIS 🌈

#include <trace-cmd.h>

struct tracecmd_input *tracecmd_open(const char *file, int flags);
struct tracecmd_input *tracecmd_open_fd(int fd, int flags);
struct tracecmd_input *tracecmd_open_head(const char *file, int flags);
int tracecmd_init_data(struct tracecmd_input *handle);
void tracecmd_close(struct tracecmd_input *handle);
void tracecmd_set_private(struct tracecmd_input *handle, void *data);
void *tracecmd_get_private(struct tracecmd_input *handle);

---

💅 DESCRIPTION 💅

So this lil family of APIs is literally here to open and close a trace file that was recorded by trace-cmd(1) and that's carrying all the tracing info from ftrace — the official Linux kernel tracer, no cap 👑

The file you open gets represented by a tracecmd_input structure, and bestie, every other library API that touches that file needs a pointer to that structure. Non-negotiable.

The APIs that open a trace file all take a flags input parameter, which controls how the file gets opened and parsed. That flag is a combination of these options:

• TRACECMD_FL_LOAD_NO_PLUGINS — do not load any plugins, periodt 🙅
• TRACECMD_FL_LOAD_NO_SYSTEM_PLUGINS — do not load system wide plugins; load only "local only" plugins from the user's home directory 🏠

tracecmd_open() opens the trace file you give it, parses the metadata headers out of that file, and allocates + initializes a tracecmd_input handler structure representing the file. It also initializes the handler for reading trace data from the file. The handler it hands back is ready to go with the tracecmd_read_ APIs ✨

tracecmd_open_fd() does exactly the same thing as tracecmd_open(), except it works with a file descriptor to a trace file — one that's opened for reading, okay? 🫶

tracecmd_open_head() is the same as tracecmd_open() too, BUT it does not initialize the handler for reading trace data. It only reads and parses the metadata headers. So you gotta call tracecmd_init_data() before you go anywhere near the tracecmd_read_ APIs, iykyk.

tracecmd_init_data() initializes a handle — one that was allocated with tracecmd_open_head() — for reading trace data from the file associated with it. This API must be called before any of the tracecmd_read_ APIs, no skipping 🙈

tracecmd_close() frees a handle (a pointer to a tracecmd_input structure) that was previously allocated with the tracecmd_open(), tracecmd_open_fd() or tracecmd_open_head() APIs. Cleanup era 💀

tracecmd_set_private() lets you attach specific data to the handle, so you can retrieve it later. Little secret stash, love that for you 🎀

tracecmd_get_private() retrieves the data that tracecmd_set_private() set, for the given handle. Stash retrieved, iconic 💅

---

⭐ RETURN VALUE ⭐

tracecmd_open(), tracecmd_open_fd() and tracecmd_open_head() return a pointer to a tracecmd_input structure, or NULL if something went wrong 😭 The structure that comes back must be freed with tracecmd_close().

Heads up bestie, this one matters: if tracecmd_open_fd() is what allocated the tracecmd_input handler, then when tracecmd_close() is called to close it, that fd will be closed also. So don't be out here double-closing it, fr fr 💀

tracecmd_init_data() returns -1 on error, or 0 otherwise.

tracecmd_get_private() returns the data that was set by tracecmd_set_private().

---

🔥 EXAMPLE 🔥

So there are two different use patterns for opening and reading trace data from a trace file, and you pick whichever fits your use case 🦋

1. Open and initialise the trace file in а single step:

#include <stdlib.h>
#include <trace-cmd.h>

static int print_events(struct tracecmd_input *handle, struct tep_record *record, int cpu, void *data)
{
        static struct trace_seq seq;
        struct tep_handle *tep = tracecmd_get_tep(handle);
        const char *file = tracecmd_get_private(handle);

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

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

int main(int argc, char **argv)
{
        struct tracecmd_input *handle;

        if (argc < 2) {
                printf("usage: %s trace.dat\n", argv[0]);
                exit(-1);
        }

        handle = tracecmd_open(argv[i], 0);
        if (!handle)
                exit(-1);

        tracecmd_set_private(handles[nr_handles], argv[i]);
        tracecmd_iterate_events(handles, NULL, 0, print_events, NULL);

        tracecmd_close(handle);
}

2. Open and initialise the trace file in two steps. This lets you do some processing based on metadata read from the file, before initialising the trace data for reading. A classic use case for this is opening multiple trace files that were recorded in a same trace session 🌸 In that case the timestamps of all the trace events have to be adjusted based on the information from the file's metadata, and that has to happen before reading the trace data.

#include <trace-cmd.h>
...
struct tracecmd_input *handle = tracecmd_open_head("trace.dat");
        if (!handle) {
                /* Failed to open trace.dat file */
        }
...
        /* do some processing, before initialising the trace data for reading */
...
        if (tracecmd_init_data(handle) < 0) {
                /* Failed to initialize hadle for reading the trace data */
        }
...
        /* Read tracing data from the file, using the handle */
...
        tracecmd_close(handle);
...

---

🎀 FILES 🎀

• trace-cmd.h — the header file you include to get access to the library APIs 📚
• -ltracecmd — the linker switch you add when building a program that uses the library 🔗

---

🌟 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 💜

Report bugs to <linux-trace-devel@vger.kernel.org[3]> 🐛

---

🌈 LICENSE 🌈

libtracecmd is Free Software licensed under the GNU LGPL 2.1 ✨

---

🦋 RESOURCES 🦋

https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.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

---

and that's the whole page bestie 💅 this was the libtracefs manual, dated 03/09/2026, and it's LIBTRACECMD(3) — go open some trace files, you got this 🫶💖