LIBTRACECMD(3)

📦
version 3.4 · 14 versions
, in arch rolling

✨ LIBTRACECMD(3) ✨

okay so this is from the libtracefs manual, and bestie, it's literally the page about reading recorded events out of a trace file. sit down, grab a strawberry 🍓, we're doing this.

🌸 NAME 🌸

tracecmd_read_cpu_first, tracecmd_read_data, tracecmd_read_at, tracecmd_free_record, tracecmd_get_tep — all of them are here to read recorded events from a trace file. that's the whole vibe. no cap.

💅 SYNOPSIS 💅

#include <trace-cmd.h>

struct tep_record *tracecmd_read_cpu_first(struct tracecmd_input *handle, int cpu);
struct tep_record *tracecmd_read_data(struct tracecmd_input *handle, int cpu);
struct tep_record *tracecmd_read_at(struct tracecmd_input *handle, unsigned long long offset, int *cpu);
void tracecmd_free_record(struct tep_record *record);
struct tep_handle *tracecmd_get_tep(struct tracecmd_input *handle);

look at her. iconic signatures. copy them character for character or she WILL fail on you 💀

🦋 DESCRIPTION 🦋

so this whole little squad of APIs is for pulling tracing data out of a trace file that you already opened with tracecmd_open()(3), tracecmd_open_fd()(3) or tracecmd_open_head()(3). like, you gotta open the file first, that's the prerequisite, we don't skip steps 🫶

The tracecmd_read_cpu_first() function reads the first trace record for a given cpu from the trace file associated with handle. and the returned record must be freed with tracecmd_free_record(). yes. must. it's not a suggestion, it's a lifestyle.

The tracecmd_read_data() function reads the next trace record for a given cpu from the trace file associated with handle, and it increments the read location pointer — so the next call to tracecmd_read_data() won't read the same record again. it moves forward, it has main character energy, it does not look back. the returned record must be freed with tracecmd_free_record().

The tracecmd_read_at() function reads a trace record from a specific offset within the file associated with handle. the CPU on which the recorded event occurred gets stored in cpu. and here's the cute part: the function does not change the current read location pointer. it's just a lil peek, no side effects. the returned record must be freed with tracecmd_free_record().

The tracecmd_free_record() function frees a record returned by any of the tracecmd_read_ APIs. all of them. every single one. this is your cleanup bestie and she's doing the lord's work 🧚

The tracecmd_get_tep() function returns a tep context for a given handle. that's it. that's the function.

⭐ RETURN VALUE ⭐

tracecmd_read_cpu_first(), tracecmd_read_data() and tracecmd_read_at() return a pointer to struct tep_record, or NULL in case of an error. and (say it with me) the returned record must be freed with tracecmd_free_record().

The tracecmd_get_tep() function returns a pointer to tep context, or NULL if there is no tep context for the given handle. and lowkey important: the returned tep pointer must not be freed. do not free it. hands off. not yours 🙈

🔥 EXAMPLE 🔥

#include <trace-cmd.h>
...
struct tracecmd_input *handle = tracecmd_open("trace.dat");
        if (!handle) {
                /* Failed to open trace.dat file */
        }
...
unsigned long long offset = 0;
struct tep_record *rec;
int cpu = 0;
        rec = tracecmd_read_cpu_first(handle, cpu);
        while (rec) {
                ...
                if ( /* some interesting record noticed */) {
                        /* store the offset of the interesting record */
                        offset = rec->offset;
                }
                ...
                tracecmd_free_record(rec);
                rec = tracecmd_read_data(handle, cpu);
        }
        ...
        if (offset) {
                rec = tracecmd_read_at(handle, offset, &cpu);
                if (rec) {
                        /* Got record at offset on cpu */
                        ...
                        tracecmd_free_record(rec);
                }
        }

...
        tracecmd_close(hadle);

okay yes, we see it, hadle is spelled like that up there and we are keeping it exactly as written because that's what the page says. do not come for me, come for the source 💀

🎀 FILES 🎀

  • trace-cmd.h — the header file to include in order to have 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)

(the whole friend group, honestly)

👑 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 dropped from the libtracefs crew on 03/09/2026 and it's labeled LIBTRACECMD(3) — go read some trace files, you're gonna slay ✨💜

📦 where this page comes from