--- name: "tracecmd_map_vcpus" section: "3" platform: "linux" package: "trace-cmd" version: "3.4-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/tracecmd_map_vcpus" --- # tracecmd\_map\_vcpus(3) Mapping host and guest data ## 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 ## SYNOPSIS ``` #include 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 This set of APIs is used to map host and guest trace files for to facilitate further tracing analysis. The **tracecmd\_map\_vcpus()** takes an array of *handles* where each item in that array was created by one of the **[tracecmd\_open(3)](/tracecmd_open/3.md)** functions, and the number of handles as *nr\_handles*. The first handle in the array of *handles* is expected to be the descriptor for the host tracing file, and the rest are guest trace files that run on the host, and were created by the **trace-cmd [record(1)](/record/1.md)** and **trace-cmd agent(1)** interactions. It returns the number of guests found in *handles* that were associated with the host, or negative on error. The **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 the mapping created from that function that is associated to this particular vCPU (denoted by *cpu*) from *handle*. This destriptor can be used by **tarcecmd\_map\_get\_guest()**, **tracecmd\_map\_set\_private()** and **tracecmd\_map\_get\_private()** functions. The **tracecmd\_map\_find\_by\_host\_pid()** will return a mapping for a guest virtual CPU that is handled by the given *host\_pid*. Note, the *handle* passed 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 does not have the vCPU that the *host\_pid* represents. The **tracecmd\_map\_get\_host\_pid()** will recturn the host\_pid for a given *map* that was retrieved by one of the above functions. The **tracecmd\_map\_get\_guest()** will recturn the guest\_handle for a given *map* that was retrieved by one of the above functions. The **tracecmd\_map\_set\_private()** allows the application to assign private data for a given guest vCPU to host thread mapping defined by *map*. The **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 that is the first entry in *handles*. It 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 is not found. **tracecmd\_map\_find\_by\_host\_pid()** returns a map that is associated by the host task with *host\_pid* as its process ID. *handle* can be either a 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 another guest than the one that the mapping is for. It 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 ``` #include #include #include 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 in order to have access to the library APIs. -ltracecmd Linker switch to add when building a program that uses the library. ``` ## SEE ALSO **[libtracefs(3)](/libtracefs/3.md)**, **[libtraceevent(3)](/libtraceevent/3.md)**, **[trace-cmd(1)](/trace-cmd/1.md)** **[trace-cmd.dat(5)](/trace-cmd.dat/5.md)** ## 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