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

   1 libtraceevent(3)
   2 ================
   3
   4 NAME
   5 ----
   6 tep_find_event,tep_find_event_by_name,tep_find_event_by_record -
   7 Find events by given key.
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 --
  13 *#include <event-parse.h>*
  14
  15 struct tep_event pass:[*]*tep_find_event*(struct tep_handle pass:[*]_tep_, int _id_);
  16 struct tep_event pass:[*]*tep_find_event_by_name*(struct tep_handle pass:[*]_tep_, const char pass:[*]_sys_, const char pass:[*]_name_);
  17 struct tep_event pass:[*]*tep_find_event_by_record*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_record_);
  18 --
  19
  20 DESCRIPTION
  21 -----------
  22 This set of functions can be used to search for an event, based on a given
  23 criteria. All functions require a pointer to a _tep_, trace event parser
  24 context.
  25
  26 The _tep_find_event()_ function searches for an event by given event _id_. The
  27 event ID is assigned dynamically and can be viewed in event's format file,
  28 "ID" field.
  29
  30 The tep_find_event_by_name()_ function searches for an event by given
  31 event _name_, under the system _sys_. If the _sys_ is NULL (not specified),
  32 the first event with _name_ is returned.
  33
  34 The tep_find_event_by_record()_ function searches for an event from a given
  35 _record_.
  36
  37 RETURN VALUE
  38 ------------
  39 All these functions return a pointer to the found event, or NULL if there is no
  40 such event.
  41
  42 EXAMPLE
  43 -------
  44 [source,c]
  45 --
  46 #include <event-parse.h>
  47 ...
  48 struct tep_handle *tep = tep_alloc();
  49 ...
  50 struct tep_event *event;
  51
  52 event = tep_find_event(tep, 1857);
  53 if (event == NULL) {
  54         /* There is no event with ID 1857 */
  55 }
  56
  57 event = tep_find_event_by_name(tep, "kvm", "kvm_exit");
  58 if (event == NULL) {
  59         /* There is no kvm_exit event, from kvm system */
  60 }
  61
  62 void event_from_record(struct tep_record *record)
  63 {
  64  struct tep_event *event = tep_find_event_by_record(tep, record);
  65         if (event == NULL) {
  66                 /* There is no event from given record */
  67         }
  68 }
  69 ...
  70 --
  71
  72 FILES
  73 -----
  74 [verse]
  75 --
  76 *event-parse.h*
  77         Header file to include in order to have access to the library APIs.
  78 *-ltraceevent*
  79         Linker switch to add when building a program that uses the library.
  80 --
  81
  82 SEE ALSO
  83 --------
  84 _libtraceevent(3)_, _trace-cmd(1)_
  85
  86 AUTHOR
  87 ------
  88 [verse]
  89 --
  90 *Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
  91 *Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
  92 --
  93 REPORTING BUGS
  94 --------------
  95 Report bugs to  <linux-trace-devel@vger.kernel.org>
  96
  97 LICENSE
  98 -------
  99 libtraceevent is Free Software licensed under the GNU LGPL 2.1
 100
 101 RESOURCES
 102 ---------
 103 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git