libtraceevent-commands.txt (5510B)
1libtraceevent(3) 2================ 3 4NAME 5---- 6tep_register_comm, tep_override_comm, tep_pid_is_registered, 7tep_data_comm_from_pid, tep_data_pid_from_comm, tep_cmdline_pid - 8Manage pid to process name mappings. 9 10SYNOPSIS 11-------- 12[verse] 13-- 14*#include <event-parse.h>* 15 16int *tep_register_comm*(struct tep_handle pass:[*]_tep_, const char pass:[*]_comm_, int _pid_); 17int *tep_override_comm*(struct tep_handle pass:[*]_tep_, const char pass:[*]_comm_, int _pid_); 18bool *tep_is_pid_registered*(struct tep_handle pass:[*]_tep_, int _pid_); 19const char pass:[*]*tep_data_comm_from_pid*(struct tep_handle pass:[*]_pevent_, int _pid_); 20struct cmdline pass:[*]*tep_data_pid_from_comm*(struct tep_handle pass:[*]_pevent_, const char pass:[*]_comm_, struct cmdline pass:[*]_next_); 21int *tep_cmdline_pid*(struct tep_handle pass:[*]_pevent_, struct cmdline pass:[*]_cmdline_); 22-- 23 24DESCRIPTION 25----------- 26These functions can be used to handle the mapping between pid and process name. 27The library builds a cache of these mappings, which is used to display the name 28of the process, instead of its pid. This information can be retrieved from 29tracefs/saved_cmdlines file. 30 31The _tep_register_comm()_ function registers a _pid_ / process name mapping. 32If a command with the same _pid_ is already registered, an error is returned. 33The _pid_ argument is the process ID, the _comm_ argument is the process name, 34_tep_ is the event context. The _comm_ is duplicated internally. 35 36The _tep_override_comm()_ function registers a _pid_ / process name mapping. 37If a process with the same pid is already registered, the process name string is 38udapted with the new one. The _pid_ argument is the process ID, the _comm_ 39argument is the process name, _tep_ is the event context. The _comm_ is 40duplicated internally. 41 42The _tep_is_pid_registered()_ function checks if a pid has a process name 43mapping registered. The _pid_ argument is the process ID, _tep_ is the event 44context. 45 46The _tep_data_comm_from_pid()_ function returns the process name for a given 47pid. The _pid_ argument is the process ID, _tep_ is the event context. 48The returned string should not be freed, but will be freed when the _tep_ 49handler is closed. 50 51The _tep_data_pid_from_comm()_ function returns a pid for a given process name. 52The _comm_ argument is the process name, _tep_ is the event context. 53The argument _next_ is the cmdline structure to search for the next pid. 54As there may be more than one pid for a given process, the result of this call 55can be passed back into a recurring call in the _next_ parameter, to search for 56the next pid. If _next_ is NULL, it will return the first pid associated with 57the _comm_. The function performs a linear search, so it may be slow. 58 59The _tep_cmdline_pid()_ function returns the pid associated with a given 60_cmdline_. The _tep_ argument is the event context. 61 62RETURN VALUE 63------------ 64_tep_register_comm()_ function returns 0 on success. In case of an error -1 is 65returned and errno is set to indicate the cause of the problem: ENOMEM, if there 66is not enough memory to duplicate the _comm_ or EEXIST if a mapping for this 67_pid_ is already registered. 68 69_tep_override_comm()_ function returns 0 on success. In case of an error -1 is 70returned and errno is set to indicate the cause of the problem: ENOMEM, if there 71is not enough memory to duplicate the _comm_. 72 73_tep_is_pid_registered()_ function returns true if the _pid_ has a process name 74mapped to it, false otherwise. 75 76_tep_data_comm_from_pid()_ function returns the process name as string, or the 77string "<...>" if there is no mapping for the given pid. 78 79_tep_data_pid_from_comm()_ function returns a pointer to a struct cmdline, that 80holds a pid for a given process, or NULL if none is found. This result can be 81passed back into a recurring call as the _next_ parameter of the function. 82 83_tep_cmdline_pid()_ functions returns the pid for the give cmdline. If _cmdline_ 84 is NULL, then -1 is returned. 85 86EXAMPLE 87------- 88The following example registers pid for command "ls", in context of event _tep_ 89and performs various searches for pid / process name mappings: 90[source,c] 91-- 92#include <event-parse.h> 93... 94int ret; 95int ls_pid = 1021; 96struct tep_handle *tep = tep_alloc(); 97... 98 ret = tep_register_comm(tep, "ls", ls_pid); 99 if (ret != 0 && errno == EEXIST) 100 ret = tep_override_comm(tep, "ls", ls_pid); 101 if (ret != 0) { 102 /* Failed to register pid / command mapping */ 103 } 104... 105 if (tep_is_pid_registered(tep, ls_pid) == 0) { 106 /* Command mapping for ls_pid is not registered */ 107 } 108... 109 const char *comm = tep_data_comm_from_pid(tep, ls_pid); 110 if (comm) { 111 /* Found process name for ls_pid */ 112 } 113... 114 int pid; 115 struct cmdline *cmd = tep_data_pid_from_comm(tep, "ls", NULL); 116 while (cmd) { 117 pid = tep_cmdline_pid(tep, cmd); 118 /* Found pid for process "ls" */ 119 cmd = tep_data_pid_from_comm(tep, "ls", cmd); 120 } 121-- 122FILES 123----- 124[verse] 125-- 126*event-parse.h* 127 Header file to include in order to have access to the library APIs. 128*-ltraceevent* 129 Linker switch to add when building a program that uses the library. 130-- 131 132SEE ALSO 133-------- 134_libtraceevent(3)_, _trace-cmd(1)_ 135 136AUTHOR 137------ 138[verse] 139-- 140*Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*. 141*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page. 142-- 143REPORTING BUGS 144-------------- 145Report bugs to <linux-trace-devel@vger.kernel.org> 146 147LICENSE 148------- 149libtraceevent is Free Software licensed under the GNU LGPL 2.1 150 151RESOURCES 152--------- 153https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git