tools/lib/traceevent/Documentation/libtraceevent-commands.txt

   1 libtraceevent(3)
   2 ================
   3
   4 NAME
   5 ----
   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
  10 SYNOPSIS
  11 --------
  12 [verse]
  13 --
  14 *#include <event-parse.h>*
  15
  16 int *tep_register_comm*(struct tep_handle pass:[*]_tep_, const char pass:[*]_comm_, int _pid_);
  17 int *tep_override_comm*(struct tep_handle pass:[*]_tep_, const char pass:[*]_comm_, int _pid_);
  18 bool *tep_is_pid_registered*(struct tep_handle pass:[*]_tep_, int _pid_);
  19 const char pass:[*]*tep_data_comm_from_pid*(struct tep_handle pass:[*]_pevent_, int _pid_);
  20 struct cmdline pass:[*]*tep_data_pid_from_comm*(struct tep_handle pass:[*]_pevent_, const char pass:[*]_comm_, struct cmdline pass:[*]_next_);
  21 int *tep_cmdline_pid*(struct tep_handle pass:[*]_pevent_, struct cmdline pass:[*]_cmdline_);
  22 --
  23
  24 DESCRIPTION
  25 -----------
  26 These functions can be used to handle the mapping between pid and process name.
  27 The library builds a cache of these mappings, which is used to display the name
  28 of the process, instead of its pid. This information can be retrieved from
  29 tracefs/saved_cmdlines file.
  30
  31 The _tep_register_comm()_ function registers a _pid_ / process name mapping.
  32 If a command with the same _pid_ is already registered, an error is returned.
  33 The _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
  36 The _tep_override_comm()_ function registers a _pid_ / process name mapping.
  37 If a process with the same pid is already registered, the process name string is
  38 udapted with the new one. The _pid_ argument is the process ID, the _comm_
  39 argument is the process name, _tep_ is the event context. The _comm_ is
  40 duplicated internally.
  41
  42 The _tep_is_pid_registered()_ function checks if a pid has a process name
  43 mapping registered. The _pid_ argument is the process ID, _tep_ is the event
  44 context.
  45
  46 The _tep_data_comm_from_pid()_ function returns the process name for a given
  47 pid. The _pid_ argument is the process ID, _tep_ is the event context.
  48 The returned string should not be freed, but will be freed when the _tep_
  49 handler is closed.
  50
  51 The _tep_data_pid_from_comm()_ function returns a pid for a given process name.
  52 The _comm_ argument is the process name, _tep_ is the event context.
  53 The argument _next_ is the cmdline structure to search for the next pid.
  54 As there may be more than one pid for a given process, the result of this call
  55 can be passed back into a recurring call in the _next_ parameter, to search for
  56 the next pid. If _next_ is NULL, it will return the first pid associated with
  57 the _comm_. The function performs a linear search, so it may be slow.
  58
  59 The _tep_cmdline_pid()_ function returns the pid associated with a given
  60 _cmdline_. The _tep_ argument is the event context.
  61
  62 RETURN VALUE
  63 ------------
  64 _tep_register_comm()_ function returns 0 on success. In case of an error -1 is
  65 returned and errno is set to indicate the cause of the problem: ENOMEM, if there
  66 is 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
  70 returned and errno is set to indicate the cause of the problem: ENOMEM, if there
  71 is not enough memory to duplicate the _comm_.
  72
  73 _tep_is_pid_registered()_ function returns true if the _pid_ has a process name
  74 mapped to it, false otherwise.
  75
  76 _tep_data_comm_from_pid()_ function returns the process name as string, or the
  77 string "<...>" 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
  80 holds a pid for a given process, or NULL if none is found. This result can be
  81 passed 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
  86 EXAMPLE
  87 -------
  88 The following example registers pid for command "ls", in context of event _tep_
  89 and performs various searches for pid / process name mappings:
  90 [source,c]
  91 --
  92 #include <event-parse.h>
  93 ...
  94 int ret;
  95 int ls_pid = 1021;
  96 struct 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 --
 122 FILES
 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
 132 SEE ALSO
 133 --------
 134 _libtraceevent(3)_, _trace-cmd(1)_
 135
 136 AUTHOR
 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 --
 143 REPORTING BUGS
 144 --------------
 145 Report bugs to  <linux-trace-devel@vger.kernel.org>
 146
 147 LICENSE
 148 -------
 149 libtraceevent is Free Software licensed under the GNU LGPL 2.1
 150
 151 RESOURCES
 152 ---------
 153 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git