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