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

       #include <event-parse.h>

       int tep_register_comm(struct tep_handle *tep, const char *comm, int pid);
       int tep_override_comm(struct tep_handle *tep, const char *comm, int pid);
       bool tep_is_pid_registered(struct tep_handle *tep, int pid);
       const char *tep_data_comm_from_pid(struct tep_handle *pevent, int pid);
       struct cmdline *tep_data_pid_from_comm(struct tep_handle *pevent, const char *comm, struct cmdline *next);
       int tep_cmdline_pid(struct tep_handle *pevent, struct cmdline *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:

           #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

           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

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

REPORTING BUGS

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

LICENSE

       libtraceevent is Free Software licensed under the GNU LGPL 2.1

RESOURCES

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

NOTES

        1. rostedt@goodmis.org
           mailto:rostedt@goodmis.org

        2. tz.stoyanov@gmail.com
           mailto:tz.stoyanov@gmail.com

        3. linux-trace-devel@vger.kernel.org
           mailto:linux-trace-devel@vger.kernel.org