LIBTRACECMD(3)

LIBTRACECMD(3) 💅✨

okay so this is part of the libtracefs Manual bestie, and it's giving "the whole let's-read-events-out-of-a-trace-file situation" 🎀 buckle up

---

✨ NAME ✨

tracecmd_iterate_events, tracecmd_iterate_events_multi, tracecmd_follow_event, tracecmd_follow_missed_events, tracecmd_filter_add, tracecmd_iterate_reset — read events from a trace file 💖

---

🌸 SYNOPSIS 🌸

#include <trace-cmd.h>

int tracecmd_iterate_events(struct tracecmd_input *handle,
                            cpu_set_t *cpus, int cpu_size,
                            int (*callback)(struct tracecmd_input *,
                                            struct tep_record *,
                                            int, void *),
                            void *callback_data);
int tracecmd_iterate_events_multi(struct tracecmd_input **handles,
                                  int nr_handles,
                                  int (*callback)(struct tracecmd_input *,
                                                           struct tep_record *,
                                                           int, void *),
                                  void *callback_data);
int tracecmd_iterate_events_reverse(struct tracecmd_input *handle,
                            cpu_set_t *cpus, int cpu_size,
                            int (*callback)(struct tracecmd_input *,
                                            struct tep_record *,
                                            int, void *),
                            void *callback_data, bool cont);
int tracecmd_follow_event(struct tracecmd_input *handle,
                          const char *system, const char *event_name,
                          int (*callback)(struct tracecmd_input *,
                                          struct tep_event *,
                                          struct tep_record *,
                                          int, void *),
                          void *callback_data);
int tracecmd_follow_missed_events(struct tracecmd_input *handle,
                                   int (*callback)(struct tracecmd_input *,
                                                   struct tep_event *,
                                                   struct tep_record *,
                                                   int, void *),
                                   void *callback_data);
struct tracecmd_filter *tracecmd_filter_add(struct tracecmd_input handle,
                                            const char *filter_str, bool neg);
int *tracecmd_iterate_reset(struct tracecmd_input *handle);

---

🦋 DESCRIPTION 🦋

so this whole little squad of APIs? they're what you use to iterate over events once you've opened a trace file with one of the open functions, like tracecmd_open(3) or tracecmd_open_fd(3). iykyk 🫶

💜 tracecmd_iterate_events() — the main character

okay so tracecmd_iterate_events() goes through all the events in the trace file defined by handle, where handle is the thing you got back from one of the tracecmd_open(3) functions. it calls the callback() function on the events on the CPUs that cpus defines. cpu_size has to be the size of cpus — check CPU_SET(3) for how that works. if cpus is NULL, then cpu_size gets completely ignored and callback() gets called for all events on all CPUs in the trace file. callback_data gets passed to callback() as its last parameter. also callback may be NULL — which is genuinely useful if you're using tracecmd_follow_event() — but heads up, if callback is NULL then callback_data is ignored and never sent to the callback of tracecmd_follow_event(). 🙈

💜 tracecmd_iterate_events_multi() — the group project one

tracecmd_iterate_events_multi() is basically tracecmd_iterate_events() but it lets you iterate over more than one trace file at once. if tracecmd agent(1) was used to get a trace file for both the host and guest, make sure the host trace file is the first entry in handles, and tracecmd_iterate_events_multi() will do the synchronization of the meta data for the guest files that come later in handles. handles is an array of trace file descriptors that were opened by tracecmd_open(3) and friends. note, unlike tracecmd_iterate_events(), this one does not filter on CPUs — because that would make the API way too complex in knowing which handle to filter the CPUs on. if you do want CPU filtering, the callback should check record→cpu and return 0 if it's not the desired CPU to process. nr_handles denotes the number of elements in handles. callback_data is passed to the callback as its last parameter. callback may be NULL, which is useful if tracecmd_follow_event() is used, but note if callback is NULL, then callback_data is ignored and not sent to the callback of tracecmd_follow_event(). 😭

💜 tracecmd_iterate_events_reverse() — the rewind

tracecmd_iterate_events_reverse() works pretty much the same way as tracecmd_iterate_events() works, but instead of calling the callback() function for each event in order of the timestamp, it calls callback() for each event in reverse order of the timestamp. if cont is false, it starts by calling the event with the oldest timestamp in the trace.dat file. if cont is set to true, then it starts wherever the current position of the tracing data is. for instance, if the callback() returns something other than zero it will exit the iteration — and if tracecmd_iterate_events_reverse() is called again with cont set to true, it will continue where it left off. if cont is false, it starts again at the event with the oldest timestamp. handle, cpus, cpu_size, and callback_data act the same as in tracecmd_iterate_events(). ⭐

---

🧚 the callback prototype (for all three iterators)

the callback() for tracecmd_iterate_events(), tracecmd_iterate_events_reverse() and tracecmd_iterate_events_multi() is of the prototype:

int callback()(struct tracecmd_input *handle, struct tep_record *record, int cpu, void *data);

• handle is the same handle passed to tracecmd_iterate_events(), or the current handle of handles passed to tracecmd_iterate_events_multi() that the record belongs to. 🎀
• record is the current event record.
• cpu is the current CPU being processed. note: for tracecmd_iterate_events_multi() it may not be the actual CPU of the file, but the nth CPU of all the handles put together — so use record→cpu to get the actual CPU that the event is on. 💀

---

🍓 tracecmd_follow_event()

the tracecmd_follow_event() function attaches to a trace file descriptor handle and calls the callback when the event described by system and name matches an event in the iteration of tracecmd_iterate_events() or tracecmd_iterate_events_multi(). note, cpu is the nth CPU for both tracecmd_iterate_events() and tracecmd_iterate_events_multi(). if you need the actual CPU of the record, use record→cpu. for tracecmd_iterate_events_multi(), the callback is only called if the handle matches the current trace file descriptor within handles. callback_data is passed as the last parameter to the callback() function. note: this callback() function will be called before the callback() function of either tracecmd_iterate_events() or tracecmd_iterate_events_multi(). 👑

the callback() prototype for tracecmd_follow_event() is:

int callback()(struct tracecmd_input *handle, struct tep_event *event, struct tep_record *_record, int cpu, void *data);

---

🌈 tracecmd_follow_missed_events()

the tracecmd_follow_missed_events() function attaches to a trace file descriptor handle and calls the callback when missed events are detected. 😭

• the event will hold the type of event that the record is.
• the record will hold the information of the missed events.
• cpu is the nth CPU for both tracecmd_iterate_events() and tracecmd_iterate_events_multi(). if you need the CPU that the missed events are for, use record→cpu.
• if record→missed_events is a positive number, then it holds the number of missed events since the last event on its CPU. otherwise it'll be negative, and that means the number of missed events is unknown — but missed events do exist since the last event on the CPU. 🙈
• callback and callback_data are the same format as tracecmd_follow_event() above.

the missed events callback is called before any of the other callbacks, and any filters that were added by tracecmd_filter_add() are ignored. if callback returns a non-zero value, it will stop the iterator before it calls any of the other iterator callbacks for the given record. 💅

---

🌸 tracecmd_filter_add()

tracecmd_filter_add() adds a filter to handle that affects both tracecmd_iterate_events() and tracecmd_iterate_events_multi(). filter_str is a character string defining a filter in a format defined by tep_filter_add_filter_str(3). if neg is true, then the events that match the filter get skipped — otherwise the events that match will execute the callback() function in the iterators. so like, neg is your "actually no, not these ones bestie" switch ✨

---

🎀 tracecmd_iterate_reset()

tracecmd_iterate_reset() sets the handle back to start at the beginning, so that the next call to tracecmd_iterate_events() starts back at the first event again instead of continuing where it left off. it's the "rewind, we're doing that again" button 🦋

---

💖 RETURN VALUE 💖

tracecmd_iterate_events(), tracecmd_iterate_events_reverse() and tracecmd_iterate_events_multi() all return zero if they successfully iterated all events (handling the follow and filters appropriately). or, y'know, an error value — which can include returning a non-zero result from the callback() function. 😭

tracecmd_iterate_reset() returns 0 on success and -1 if an error occurred. note: if -1 is returned, a partial reset may have also happened. 🙈

fr fr, that partial-reset thing is not a vibe — check your return values, bestie 💀

---

✨ EXAMPLE ✨

ok bestie this is the part where it all comes together — a whole actual program, no cap 💖 Just read it top to bottom, it's giving "reference implementation" and it literally ate:

#define _GNU_SOURCE
#include <sched.h>
#include <stdlib.h>
#include <getopt.h>
#include <trace-cmd.h>

struct private_data {
        int             cpu;
        const char      *file;
};

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);
        struct private_data *pdata = tracecmd_get_private(handle);

        /* For multi handles we need this */
        if (pdata->cpu >= 0 && pdata->cpu != record->cpu)
                return 0;

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

        trace_seq_reset(&seq);
        trace_seq_printf(&seq, "%s: ", pdata->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;
}

static int print_event(struct tracecmd_input *handle, struct tep_event *event,
                       struct tep_record *record, int cpu, void *data)
{
        return print_events(handle, record, cpu, data);
}

static int missed_events(struct tracecmd_input *handle, struct tep_event *event,
                         struct tep_record *record, int cpu, void *data)
{
        if (record->missed_events > 0)
                printf("CPU [%03d] has %d missed events\n",
                         record->cpu, record->missed_events);
        else
                printf("CPU [%03d] has missed events\n", record->cpu);
        return 0;
}

static void usage(const char *argv0)
{
        printf("usage: [-c cpu][-f filter][-e event] %s trace.dat [trace.dat ...]\n",
               argv0);
        exit(-1);
}

int main(int argc, char **argv)
{
        struct tracecmd_input **handles = NULL;
        const char *filter_str = NULL;
        const char *argv0 = argv[0];
        struct private_data *priv;
        cpu_set_t *cpuset = NULL;
        char *event = NULL;
        size_t cpusize = 0;
        int nr_handles = 0;
        int cpu = -1;
        int i;
        int c;

        while ((c = getopt(argc, argv, "c:f:e:")) >= 0) {
                switch (c) {
                case 'c':
                        /* filter all trace data to this one CPU. */
                        cpu = atoi(optarg);
                        break;
                case 'f':
                        filter_str = optarg;
                        break;
                case 'e':
                        event = optarg;
                        break;
                default:
                        usage(argv0);
                }
        }
        argc -= optind;
        argv += optind;

        if (argc == 0)
                usage(argv0);

        for (i = 0; i < argc; i++) {
                handles = realloc(handles, sizeof(*handles) * (nr_handles + 1));
                if (!handles)
                        exit(-1);
                handles[nr_handles] = tracecmd_open(argv[i], 0);
                if (!handles[nr_handles]) {
                        perror(argv[i]);
                        exit(-1);
                }
                if (filter_str) {
                        if (tracecmd_filter_add(handles[nr_handles], filter_str, false) == NULL) {
                                perror("adding filter");
                                exit(-1);
                        }
                }
                priv = calloc(1, sizeof(*priv));
                if (!priv)
                        exit(-1);
                priv->file = argv[i];
                priv->cpu = cpu;
                tracecmd_set_private(handles[nr_handles], priv);
                if (event) {
                        if (tracecmd_follow_event(handles[nr_handles], NULL, event, print_event, NULL) < 0) {
                                printf("Could not follow event %s for file %s\n", event, argv[i]);
                                exit(-1);
                        }
                }
                tracecmd_follow_missed_events(handles[nr_handles], missed_events, NULL);
                nr_handles++;
        }

        /* Shortcut */
        if (nr_handles == 1) {
                if (cpu >= 0) {
                        cpuset = CPU_ALLOC(cpu + 1);
                        if (!cpuset)
                                exit(-1);
                        cpusize = CPU_ALLOC_SIZE(cpu + 1);
                        CPU_SET_S(cpu, cpusize, cpuset);
                }
                if (event)
                        tracecmd_iterate_events(handles[0], cpuset, cpusize, NULL, NULL);
                else
                        tracecmd_iterate_events(handles[0], cpuset, cpusize, print_events, NULL);
        } else {
                if (event)
                        tracecmd_iterate_events_multi(handles, nr_handles, NULL, NULL);
                else
                        tracecmd_iterate_events_multi(handles, nr_handles, print_events, NULL);
        }

        for (i = 0; i < nr_handles; i++) {
                priv = tracecmd_get_private(handles[i]);
                free(priv);
                tracecmd_close(handles[i]);
        }
        free(handles);
}

like… it's lowkey a whole lil' trace printer?? the way it opens every trace.dat you hand it, filters, follows events, and cleans up after itself — main character energy fr fr 👑 Notice the <pink>Shortcut</pink> comment: one handle gets the single-handle path, multiple handles get the _multi path. And yes, private_data is how it remembers which file each record came from. iykyk 💅

---

🎀 FILES 🎀

• trace-cmd.h — the header file you include so you can actually touch the library APIs. no header, no vibes ✨
• -ltracecmd — the linker switch you add when building a program that uses the library. it's literally the "let me in" handshake 🫶

🌈 SEE ALSO 🌈

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

(go read those too, bestie — they're the friend group 💜)

🌸 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]>

like please do tell them, they genuinely want to know 💀

⭐ 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 one's from libtracefs, dated 03/09/2026, filed under LIBTRACECMD(3) — go forth and trace literally everything 💅✨