1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
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 <event-parse.h>*
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 <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);
}
--
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* <rostedt@goodmis.org>, author of *libtraceevent*.
*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
--
REPORTING BUGS
--------------
Report bugs to <linux-trace-devel@vger.kernel.org>
LICENSE
-------
libtraceevent is Free Software licensed under the GNU LGPL 2.1
RESOURCES
---------
https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/
|
