# tep_register_comm

## 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.
    


## 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
    


* * *