LIBTRACEEVENT(3)

📦 version 1.3.3, in ubuntu jammy

💖 LIBTRACEEVENT(3) 💖

okay bestie, welcome to the libtraceevent manual — this is the page for the pid ↔ process-name mapping girlies. like, it's the libtraceevent Manual, section 3, and it's about to be your new obsession. no cap. ✨

🌸 NAME 🌸

tep_register_comm, tep_override_comm, tep_pid_is_registered, tep_data_comm_from_pid, tep_data_pid_from_comm, tep_cmdline_pid — the whole squad that handles the pid-to-process-name mappings. yes, all six of them, they're a package deal 💅

🎀 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);

like look at them. gorgeous. iconic. 🦋

✨ DESCRIPTION ✨

so these functions are literally here to handle the mapping between pid and process name. the library builds a whole lil cache of these mappings, and that cache is what gets used to show you the name of the process instead of just its boring old pid. and guess where this info can be retrieved from? the tracefs/saved_cmdlines file. periodt. 📁

tep_register_comm() registers a pid / process name mapping. if a command with the same pid is already registered, it returns an error — no duplicates allowed bestie 🙅‍♀️. the pid argument is the process ID, the comm argument is the process name, and tep is the event context. and yes, the comm gets duplicated internally (she's got her own copy now 💖).

tep_override_comm() also registers a pid / process name mapping, but this one is the chill version — if a process with the same pid is already registered, the process name string is udapted (yes that's exactly how the original spells it, we don't gatekeep typos here) with the new one. the pid argument is the process ID, the comm argument is the process name, tep is the event context. and once again, the comm is duplicated internally.

tep_is_pid_registered() checks if a pid has a process name mapping registered at all. the pid argument is the process ID, tep is the event context. simple. clean. vibe check passed ✅

tep_data_comm_from_pid() returns the process name for a given pid. the pid argument is the process ID, tep is the event context. important: the returned string should not be freed by you — she 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. the comm argument is the process name, tep is the event context. the next argument is the cmdline structure to search for the next pid. and here's the tea: since there may be more than one pid for a given process, you can take the result of this call and pass it back in as the next parameter in a recurring call, to search for the next pid 🔁. if next is NULL, it'll return the first pid associated with the comm. heads up though — this function performs a linear search, so it may be slow. it's giving "worth it but don't do it in a hot loop" 😭

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. if something goes wrong, -1 is returned and errno is set to tell you why: ENOMEM if there's not 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 is returned and errno is set: 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. binary queen 👑
  • tep_data_comm_from_pid() returns the process name as a string, or the string "<...>" if there's no mapping for the given pid. (yes, literally <...>, that's the placeholder vibe 💀)
  • 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. and you can pass this result back into a recurring call as the next parameter of the function.
  • tep_cmdline_pid() returns the pid for the given cmdline. if cmdline is NULL, then -1 is returned.

🧚 EXAMPLE 🧚

okay so this example registers a pid for the command "ls", in the context of event tep, and then performs various 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);
        }

see how the while (cmd) loop just keeps feeding cmd back in? that's the recurring call thing. chef's kiss 👨‍🍳💋

🍓 FILES 🍓

  • event-parse.h — the header file to include so you can have access to the library APIs. include her or you get nothing, bestie 🙈
  • -ltraceevent — the linker switch to add when building a program that uses the library. don't forget it, it's literally the whole point.

🌈 SEE ALSO 🌈

libtraceevent(3), trace-cmd(1)

go read those too, they're part of the extended universe 💜

👑 AUTHOR 👑

  • Steven Rostedt <rostedt@goodmis.org[1]>, author of libtraceevent. legend behaviour.
  • Tzvetomir Stoyanov <tz.stoyanov@gmail.com[2]>, author of this man page. icon.

💀 REPORTING BUGS 💀

found a bug? report it to <linux-trace-devel@vger.kernel.org[3]> — they wanna hear about it, fr fr.

💅 LICENSE 💅

libtraceevent is Free Software licensed under the GNU LGPL 2.1. free as in freedom, protected as in license 🫶

⭐ 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 🎀 this was libtraceevent version 1.3.3, dated 08/28/2021, and it lives at LIBTRACEEVENT(3). go register some comms. you got this. mwah 💖✨

📦 where this page comes from