1LIBTRACEEVENT(3)             libtraceevent Manual             LIBTRACEEVENT(3)
2
3
4

NAME

6       tep_register_comm, tep_override_comm, tep_pid_is_registered,
7       tep_data_comm_from_pid, tep_data_pid_from_comm, tep_cmdline_pid -
8       Manage pid to process name mappings.
9

SYNOPSIS

11       #include <event-parse.h>
12
13       int tep_register_comm(struct tep_handle *tep, const char *comm, int pid);
14       int tep_override_comm(struct tep_handle *tep, const char *comm, int pid);
15       bool tep_is_pid_registered(struct tep_handle *tep, int pid);
16       const char *tep_data_comm_from_pid(struct tep_handle *pevent, int pid);
17       struct cmdline *tep_data_pid_from_comm(struct tep_handle *pevent, const char *comm, struct cmdline *next);
18       int tep_cmdline_pid(struct tep_handle *pevent, struct cmdline *cmdline);
19

DESCRIPTION

21       These functions can be used to handle the mapping between pid and
22       process name. The library builds a cache of these mappings, which is
23       used to display the name of the process, instead of its pid. This
24       information can be retrieved from tracefs/saved_cmdlines file.
25
26       The tep_register_comm() function registers a pid / process name
27       mapping. If a command with the same pid is already registered, an error
28       is returned. The pid argument is the process ID, the comm argument is
29       the process name, tep is the event context. The comm is duplicated
30       internally.
31
32       The tep_override_comm() function registers a pid / process name
33       mapping. If a process with the same pid is already registered, the
34       process name string is udapted with the new one. The pid argument is
35       the process ID, the comm argument is the process name, tep is the event
36       context. The comm is duplicated internally.
37
38       The tep_is_pid_registered() function checks if a pid has a process name
39       mapping registered. The pid argument is the process ID, tep is the
40       event context.
41
42       The tep_data_comm_from_pid() function returns the process name for a
43       given pid. The pid argument is the process ID, tep is the event
44       context. The returned string should not be freed, but will be freed
45       when the tep handler is closed.
46
47       The tep_data_pid_from_comm() function returns a pid for a given process
48       name. The comm argument is the process name, tep is the event context.
49       The argument next is the cmdline structure to search for the next pid.
50       As there may be more than one pid for a given process, the result of
51       this call can be passed back into a recurring call in the next
52       parameter, to search for the next pid. If next is NULL, it will return
53       the first pid associated with the comm. The function performs a linear
54       search, so it may be slow.
55
56       The tep_cmdline_pid() function returns the pid associated with a given
57       cmdline. The tep argument is the event context.
58

RETURN VALUE

60       tep_register_comm() function returns 0 on success. In case of an error
61       -1 is returned and errno is set to indicate the cause of the problem:
62       ENOMEM, if there is not enough memory to duplicate the comm or EEXIST
63       if a mapping for this pid is already registered.
64
65       tep_override_comm() function returns 0 on success. In case of an error
66       -1 is returned and errno is set to indicate the cause of the problem:
67       ENOMEM, if there is not enough memory to duplicate the comm.
68
69       tep_is_pid_registered() function returns true if the pid has a process
70       name mapped to it, false otherwise.
71
72       tep_data_comm_from_pid() function returns the process name as string,
73       or the string "<...>" if there is no mapping for the given pid.
74
75       tep_data_pid_from_comm() function returns a pointer to a struct
76       cmdline, that holds a pid for a given process, or NULL if none is
77       found. This result can be passed back into a recurring call as the next
78       parameter of the function.
79
80       tep_cmdline_pid() functions returns the pid for the give cmdline. If
81       cmdline is NULL, then -1 is returned.
82

EXAMPLE

84       The following example registers pid for command "ls", in context of
85       event tep and performs various searches for pid / process name
86       mappings:
87
88           #include <event-parse.h>
89           ...
90           int ret;
91           int ls_pid = 1021;
92           struct tep_handle *tep = tep_alloc();
93           ...
94                   ret = tep_register_comm(tep, "ls", ls_pid);
95                   if (ret != 0 && errno == EEXIST)
96                           ret = tep_override_comm(tep, "ls", ls_pid);
97                   if (ret != 0) {
98                           /* Failed to register pid / command mapping */
99                   }
100           ...
101                   if (tep_is_pid_registered(tep, ls_pid) == 0) {
102                           /* Command mapping for ls_pid is not registered */
103                   }
104           ...
105                   const char *comm = tep_data_comm_from_pid(tep, ls_pid);
106                   if (comm) {
107                           /* Found process name for ls_pid */
108                   }
109           ...
110                   int pid;
111                   struct cmdline *cmd = tep_data_pid_from_comm(tep, "ls", NULL);
112                   while (cmd) {
113                           pid = tep_cmdline_pid(tep, cmd);
114                           /* Found pid for process "ls" */
115                           cmd = tep_data_pid_from_comm(tep, "ls", cmd);
116                   }
117

FILES

119           event-parse.h
120                   Header file to include in order to have access to the library APIs.
121           -ltraceevent
122                   Linker switch to add when building a program that uses the library.
123

SEE ALSO

125       libtraceevent(3), trace-cmd(1)
126

AUTHOR

128           Steven Rostedt <rostedt@goodmis.org[1]>, author of libtraceevent.
129           Tzvetomir Stoyanov <tz.stoyanov@gmail.com[2]>, author of this man page.
130

REPORTING BUGS

132       Report bugs to <linux-trace-devel@vger.kernel.org[3]>
133

LICENSE

135       libtraceevent is Free Software licensed under the GNU LGPL 2.1
136

RESOURCES

138       https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/
139

NOTES

141        1. rostedt@goodmis.org
142           mailto:rostedt@goodmis.org
143
144        2. tz.stoyanov@gmail.com
145           mailto:tz.stoyanov@gmail.com
146
147        3. linux-trace-devel@vger.kernel.org
148           mailto:linux-trace-devel@vger.kernel.org
149
150
151
152libtraceevent 1.1.1               02/08/2021                  LIBTRACEEVENT(3)
Impressum