libtraceevent(3) ================ 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 -------- [verse] -- *#include * int *tep_register_comm*(struct tep_handle pass:[*]_tep_, const char pass:[*]_comm_, int _pid_); int *tep_override_comm*(struct tep_handle pass:[*]_tep_, const char pass:[*]_comm_, int _pid_); bool *tep_is_pid_registered*(struct tep_handle pass:[*]_tep_, int _pid_); const char pass:[*]*tep_data_comm_from_pid*(struct tep_handle pass:[*]_pevent_, int _pid_); struct cmdline pass:[*]*tep_data_pid_from_comm*(struct tep_handle pass:[*]_pevent_, const char pass:[*]_comm_, struct cmdline pass:[*]_next_); int *tep_cmdline_pid*(struct tep_handle pass:[*]_pevent_, struct cmdline pass:[*]_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: [source,c] -- #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 ----- [verse] -- *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), *trace-cmd*(1) AUTHOR ------ [verse] -- *Steven Rostedt* , author of *libtraceevent*. *Tzvetomir Stoyanov* , author of this man page. -- REPORTING BUGS -------------- Report bugs to LICENSE ------- libtraceevent is Free Software licensed under the GNU LGPL 2.1 RESOURCES --------- https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/