LIBTRACEEVENT(3)

📦
version 1.9.0 · 14 versions
, in ubuntu stonking

💖 LIBTRACEEVENT(3) — the libtraceevent manual, bestie edition 💖

okay so this is a page straight outta the libtraceevent manual, and it's all about the pid ↔ process name situation. strap in 🎀

✨ NAME ✨

tep_register_comm, tep_override_comm, tep_is_pid_registered, tep_data_comm_from_pid, tep_data_pid_from_comm, tep_cmdline_pid — managing pid-to-process-name mappings, basically the group chat between "who is this number" and "oh that's their name" 💅

🌸 SYNOPSIS 🌸

#include <event-parse.h>

int tep_register_comm(struct tep_handle *tep, const char *comm, int pid);
int tep_override_comm(struct tep_handle *tep, const char *comm, int pid);
bool tep_is_pid_registered(struct tep_handle *tep, int pid);
const char *tep_data_comm_from_pid(struct tep_handle *pevent, int pid);
struct cmdline *tep_data_pid_from_comm(struct tep_handle *pevent, const char *comm, struct cmdline *next);
int tep_cmdline_pid(struct tep_handle *pevent, struct cmdline *cmdline);

🦋 DESCRIPTION 🦋

so these functions handle the whole mapping between a pid and a process name. the library builds a lil cache of these mappings, and that cache is what lets it show you the name of a process instead of just a sad lonely pid. you can pull this info out of the tracefs/saved_cmdlines file ✨

  • tep_register_comm() — registers a pid / process name mapping. if a command with the same pid is already registered, it returns an error, no cap. the pid argument is the process ID, the comm argument is the process name, and tep is the event context. the comm gets duplicated internally 💖
  • tep_override_comm() — also registers a pid / process name mapping, but if a process with the same pid is already in there, the process name string gets updated with the new one (iconic, no drama). the pid argument is the process ID, the comm argument is the process name, tep is the event context. the comm is duplicated internally 🎀
  • tep_is_pid_registered() — checks whether a pid already has a process name mapping registered. pid is the process ID, tep is the event context. yes/no energy only 🙈
  • tep_data_comm_from_pid() — returns the process name for a given pid. pid is the process ID, tep is the event context. the returned string should not be freed by you — it gets freed when the tep handler is closed, so hands off bestie 💅
  • tep_data_pid_from_comm() — returns a pid for a given process name. comm is the process name, tep is the event context. the next argument is the cmdline structure to search for the next pid. because there can be more than one pid for a given process, you can pass the result of this call right back in through the next parameter on a recurring call to hunt down the next pid. if next is NULL, it returns the first pid associated with the comm. > heads up: this function does a linear search, so it may be slow 😭
  • tep_cmdline_pid() — returns the pid associated with a given cmdline. the tep argument is the event context 🫶

⭐ RETURN VALUE ⭐

  • tep_register_comm() — returns 0 on success. on error, -1 comes back and errno is set to tell you why: ENOMEM if there isn't enough memory to duplicate the comm, or EEXIST if a mapping for this pid is already registered 💀
  • tep_override_comm() — returns 0 on success. on error, -1 and errno explains it: ENOMEM if there's not enough memory to duplicate the comm ✨
  • tep_is_pid_registered() — returns true if the pid has a process name mapped to it, false otherwise 🌈
  • tep_data_comm_from_pid() — returns the process name as a string, or the string "<...>" if there's no mapping for that pid 🎀
  • tep_data_pid_from_comm() — returns a pointer to a struct cmdline that holds a pid for a given process, or NULL if none is found. you can pass this result back into a recurring call as the next parameter 🦋
  • tep_cmdline_pid() — returns the pid for the given cmdline. if cmdline is NULL, then -1 is returned 😭

🔥 EXAMPLE 🔥

this example registers a pid for the command "ls", in the context of the event tep, and then does a bunch of different searches for pid / process name mappings. slay:

#include <event-parse.h>
...
int ret;
int ls_pid = 1021;
struct tep_handle *tep = tep_alloc();
...
        ret = tep_register_comm(tep, "ls", ls_pid);
        if (ret != 0 && errno == EEXIST)
                ret = tep_override_comm(tep, "ls", ls_pid);
        if (ret != 0) {
                /* Failed to register pid / command mapping */
        }
...
        if (tep_is_pid_registered(tep, ls_pid) == 0) {
                /* Command mapping for ls_pid is not registered */
        }
...
        const char *comm = tep_data_comm_from_pid(tep, ls_pid);
        if (comm) {
                /* Found process name for ls_pid */
        }
...
        int pid;
        struct cmdline *cmd = tep_data_pid_from_comm(tep, "ls", NULL);
        while (cmd) {
                pid = tep_cmdline_pid(tep, cmd);
                /* Found pid for process "ls" */
                cmd = tep_data_pid_from_comm(tep, "ls", cmd);
        }

🍓 FILES 🍓

  • event-parse.h
    • header file you gotta include to get access to the library APIs 🫶
  • -ltraceevent
    • the linker switch you add when building a program that uses the library ✨

💜 SEE ALSO 💜

👑 AUTHOR 👑

  • Steven Rostedt <rostedt@goodmis.org>, author of libtraceevent 💖
  • Tzvetomir Stoyanov <tz.stoyanov@gmail.com>, author of this man page 🎀

🌈 REPORTING BUGS 🌈

Report bugs to <linux-trace-devel@vger.kernel.org> — they wanna hear it, fr fr 🙈

🧚 LICENSE 🧚

libtraceevent is Free Software licensed under the GNU LGPL 2.1 📜✨

🌸 RESOURCES 🌸

https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/

💅 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, periodt 💖 this was libtraceevent 1.9.0, dated 06/15/2026 — thanks for reading, ily, go map some pids 🎀🦋✨

📦 where this page comes from