LIBTRACECMD(3)

📦
version 3.4 · 13 versions
, in arch rolling

💅 LIBTRACECMD(3) — the mapping-host-and-guest-files one ✨

okay so this page lives in the libtracefs manual, section 3, and it's all about LIBTRACECMD(3) — the little family of functions that lets you glue your host trace files to your guest trace files so you can actually analyze them together. bestie, it's giving "detective work but make it C" 🔍💖

🌸 NAME 🌸

tracecmd_map_vcpus, tracecmd_get_cpu_map, tracecmd_map_find_by_host_pid, tracecmd_map_get_host_pid, tracecmd_map_get_guest, tracecmd_map_set_private, tracecmd_map_get_private — mapping host and guest data. literally the whole friend group 🫶

✨ SYNOPSIS ✨

#include <trace-cmd.h>

int tracecmd_map_vcpus(struct tracecmd_input **handles, int nr_handles);
struct tracecmd_cpu_map *tracecmd_get_cpu_map(struct tracecmd_input *handle, int cpu);
struct tracecmd_cpu_map *tracecmd_map_find_by_host_pid(struct tracecmd_input *handle,
                                                      int host_pid);
int tracecmd_map_get_host_pid(struct tracecmd_cpu_map *map);
struct tracecmd_input *tracecmd_map_get_guest(struct tracecmd_cpu_map *map);
void tracecmd_map_set_private(struct tracecmd_cpu_map *map, void *priv);
void *tracecmd_map_get_private(struct tracecmd_cpu_map *map);

🦋 DESCRIPTION 🦋

so this whole API set is here to map host and guest trace files together so you can do more tracing analysis afterwards. it's the matchmaker of trace files, no cap 💘

tracecmd_map_vcpus() takes an array of handles — each item in that array was made by one of the tracecmd_open(3) functions — plus the number of handles as nr_handles. the first handle in that array is expected to be the descriptor for the host tracing file, and the rest are guest trace files that run on the host, created through the trace-cmd record(1) and trace-cmd agent(1) interactions. it returns the number of guests found in handles that got associated with the host, or negative on error. 👑

tracecmd_get_cpu_map() returns a descriptor for a given CPU for a handle. if the handle was a guest defined from tracecmd_map_vcpus(), then you get the mapping created by that function that's associated with this particular vCPU (denoted by cpu) from handle. this descriptor can be used by the tracecmd_map_get_guest(), tracecmd_map_set_private() and tracecmd_map_get_private() functions. iconic lil handoff 🎀

tracecmd_map_find_by_host_pid() returns a mapping for a guest virtual CPU that is handled by the given host_pid. note — bestie, this part matters — the handle you pass in can be either the host handle or one of the guest's handles for that host that was mapped by tracecmd_map_vcpus(), even if the guest handle doesn't have the vCPU that the host_pid represents. yeah. it's flexible like that 💅

tracecmd_map_get_host_pid() returns the host_pid for a given map that was retrieved by one of the above functions.

tracecmd_map_get_guest() returns the guest_handle for a given map that was retrieved by one of the above functions.

tracecmd_map_set_private() lets the app assign private data for a given guest vCPU → host thread mapping defined by map. your lil stash spot 🙈

tracecmd_map_get_private() retrieves the priv data from map that was set by tracecmd_map_set_private().

🔥 RETURN VALUE 🔥

  • tracecmd_map_vcpus() — returns the number of guests in the handles array that were mapped to the host handle (which is the first entry in handles). returns -1 on error.
  • tracecmd_get_cpu_map() — returns a map created by tracecmd_map_vcpus() for a given cpu for a given handle, or NULL if it's not found.
  • tracecmd_map_find_by_host_pid() — returns a map associated with the host task that has host_pid as its process ID. handle can be either the host handle, or one of the guest handles that were mapped to the host via tracecmd_map_vcpus() — even if the guest handle is a different guest than the one the mapping is for. returns NULL if not found.
  • tracecmd_map_get_host_pid() — returns the host process ID for an associated mapping defined by map.
  • tracecmd_map_get_guest() — returns the guest handle for an associated mapping defined by map.
  • tracecmd_map_get_private() — returns the private data of a mapping defined by map that was set by tracecmd_map_set_private().

🌈 EXAMPLE 🌈

here's the whole vibe in one program, copy-paste ready 💖

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

    int main(int argc, char **argv)
    {
            struct tracecmd_input **handles = NULL;
            int nr_handles;
            int i;

            if (argc < 2) {
                    printf("usage: host_trace.dat guest1_trace.dat [guest2_trace.dat ...]\n");
                    exit(-1);
            }

            for (i = 1; 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[1]);
                            exit(-1);
                    }
                    tracecmd_set_private(handles[nr_handles], argv[i]);
                    nr_handles++;
            }

            tracecmd_map_vcpus(handles, nr_handles);

            for (i = 1; i < nr_handles; i++) {
                    struct tracecmd_cpu_map *map;
                    struct tep_handle *tep;
                    const char *file = tracecmd_get_private(handles[i]);
                    int cpus, cpu;

                    printf("Mappings for guest %s:\n", file);
                    tep = tracecmd_get_tep(handles[i]);
                    cpus = tep_get_cpus(tep);
                    for (cpu = 0; cpu < cpus; cpu++) {
                            printf("  [%03d] ", cpu);
                            map = tracecmd_get_cpu_map(handles[i], cpu);
                            if (!map) {
                                    printf("Has no mapping!\n");
                                    continue;
                            }
                            printf("host_pid: %d\n", tracecmd_map_get_host_pid(map));
                    }
            }
            for (i = 0; i < nr_handles; i++)
                    tracecmd_close(handles[i]);
            free(handles);
            exit(0);
    }

🎀 FILES 🎀

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

👀 SEE ALSO 👀

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

💀 REPORTING BUGS 💀

report bugs to <linux-trace-devel@vger.kernel.org[1]>

🌸 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. linux-trace-devel@vger.kernel.org mailto:linux-trace-devel@vger.kernel.org
ok that's the whole page, bestie — go map some vCPUs, you're gonna slay 💅✨

mwah 💋 — this one shipped from the libtracefs manual, dated 03/09/2026, and it answers to the name LIBTRACECMD(3). bye bye, ily 🫶

📦 where this page comes from