--- name: "tep_register_comm" section: "3" platform: "linux" package: "libtraceevent" version: "1:1.9.1-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/tep_register_comm" --- # tep\_register\_comm(3) Manage pid to process name mappings. ## NAME tep\_register\_comm, tep\_override\_comm, tep\_is\_pid\_registered, tep\_data\_comm\_from\_pid, tep\_data\_pid\_from\_comm, tep\_cmdline\_pid - Manage pid to process name mappings. ## SYNOPSIS ``` #include 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 These functions can be used to handle the mapping between pid and process name. The library builds a cache of these mappings, which is used to display the name of the process, instead of its pid. This information can be retrieved from tracefs/saved\_cmdlines file. The **tep\_register\_comm()** function registers a *pid* / process name mapping. If a command with the same *pid* is already registered, an error is returned. The *pid* argument is the process ID, the *comm* argument is the process name, *tep* is the event context. The *comm* is duplicated internally. The **tep\_override\_comm()** function registers a *pid* / process name mapping. If a process with the same pid is already registered, the process name string is udapted with the new one. The *pid* argument is the process ID, the *comm* argument is the process name, *tep* is the event context. The *comm* is duplicated internally. The **tep\_is\_pid\_registered()** function checks if a pid has a process name mapping registered. The *pid* argument is the process ID, *tep* is the event context. The **tep\_data\_comm\_from\_pid()** function returns the process name for a given pid. The *pid* argument is the process ID, *tep* is the event context. The returned string should not be freed, but will be freed when the *tep* handler is closed. The **tep\_data\_pid\_from\_comm()** function returns a pid for a given process name. The *comm* argument is the process name, *tep* is the event context. The argument *next* is the cmdline structure to search for the next pid. As there may be more than one pid for a given process, the result of this call can be passed back into a recurring call in the *next* parameter, to search for the next pid. If *next* is NULL, it will return the first pid associated with the *comm*. The function performs a linear search, so it may be slow. The **tep\_cmdline\_pid()** function returns the pid associated with a given *cmdline*. The *tep* argument is the event context. ## RETURN VALUE **tep\_register\_comm()** function returns 0 on success. In case of an error -1 is returned and errno is set to indicate the cause of the problem: ENOMEM, if there is not enough memory to duplicate the *comm* or EEXIST if a mapping for this *pid* is already registered. **tep\_override\_comm()** function returns 0 on success. In case of an error -1 is returned and errno is set to indicate the cause of the problem: ENOMEM, if there is not enough memory to duplicate the *comm*. **tep\_is\_pid\_registered()** function returns true if the *pid* has a process name mapped to it, false otherwise. **tep\_data\_comm\_from\_pid()** function returns the process name as string, or the string "\<...\>" if there is no mapping for the given pid. **tep\_data\_pid\_from\_comm()** function returns a pointer to a struct cmdline, that holds a pid for a given process, or NULL if none is found. This result can be passed back into a recurring call as the *next* parameter of the function. **tep\_cmdline\_pid()** functions returns the pid for the give cmdline. If *cmdline* is NULL, then -1 is returned. ## EXAMPLE The following example registers pid for command "ls", in context of event *tep* and performs various searches for pid / process name mappings: ``` #include ... 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 to include in order to have access to the library APIs. -ltraceevent Linker switch to add when building a program that uses the library. ``` ## SEE ALSO [**libtraceevent**(3)](/libtraceevent/3.md), [**trace-cmd**(1)](/trace-cmd/1.md) ## AUTHOR ``` Steven Rostedt , author of libtraceevent. Tzvetomir Stoyanov , author of this man page. ``` ## REPORTING BUGS Report bugs to \<**linux-trace-devel@vger.kernel.org**\[3\]\> ## 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