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

   1 libtraceevent(3)
   2 ================
   3
   4 NAME
   5 ----
   6 tep_find_common_field, tep_find_field, tep_find_any_field -
   7 Search for a field in an event.
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 --
  13 *#include <event-parse.h>*
  14
  15 struct tep_format_field pass:[*]*tep_find_common_field*(struct tep_event pass:[*]_event_, const char pass:[*]_name_);
  16 struct tep_format_field pass:[*]*tep_find_field*(struct tep_event_ormat pass:[*]_event_, const char pass:[*]_name_);
  17 struct tep_format_field pass:[*]*tep_find_any_field*(struct tep_event pass:[*]_event_, const char pass:[*]_name_);
  18 --
  19
  20 DESCRIPTION
  21 -----------
  22 These functions search for a field with given name in an event. The field
  23 returned can be used to find the field content from within a data record.
  24
  25 The _tep_find_common_field()_ function searches for a common field with _name_
  26 in the _event_.
  27
  28 The _tep_find_field()_ function searches for an event specific field with
  29 _name_ in the _event_.
  30
  31 The _tep_find_any_field()_ function searches for any field with _name_ in the
  32 _event_.
  33
  34 RETURN VALUE
  35 ------------
  36 The _tep_find_common_field(), _tep_find_field()_ and _tep_find_any_field()_
  37 functions return a pointer to the found field, or NULL in case there is no field
  38 with the requested name.
  39
  40 EXAMPLE
  41 -------
  42 [source,c]
  43 --
  44 #include <event-parse.h>
  45 ...
  46 void get_htimer_info(struct tep_handle *tep, struct tep_record *record)
  47 {
  48         struct tep_format_field *field;
  49         struct tep_event *event;
  50         long long softexpires;
  51         int mode;
  52         int pid;
  53
  54         event = tep_find_event_by_name(tep, "timer", "hrtimer_start");
  55
  56         field = tep_find_common_field(event, "common_pid");
  57         if (field == NULL) {
  58                 /* Cannot find "common_pid" field in the event */
  59         } else {
  60                 /* Get pid from the data record */
  61                 pid = tep_read_number(tep, record->data + field->offset,
  62                                       field->size);
  63         }
  64
  65         field = tep_find_field(event, "softexpires");
  66         if (field == NULL) {
  67                 /* Cannot find "softexpires" event specific field in the event */
  68         } else {
  69                 /* Get softexpires parameter from the data record */
  70                 softexpires = tep_read_number(tep, record->data + field->offset,
  71                                               field->size);
  72         }
  73
  74         field = tep_find_any_field(event, "mode");
  75         if (field == NULL) {
  76                 /* Cannot find "mode" field in the event */
  77         } else
  78         {
  79                 /* Get mode parameter from the data record */
  80                 mode = tep_read_number(tep, record->data + field->offset,
  81                                        field->size);
  82         }
  83 }
  84 ...
  85 --
  86
  87 FILES
  88 -----
  89 [verse]
  90 --
  91 *event-parse.h*
  92         Header file to include in order to have access to the library APIs.
  93 *-ltraceevent*
  94         Linker switch to add when building a program that uses the library.
  95 --
  96
  97 SEE ALSO
  98 --------
  99 _libtraceevent(3)_, _trace-cmd(1)_
 100
 101 AUTHOR
 102 ------
 103 [verse]
 104 --
 105 *Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
 106 *Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
 107 --
 108 REPORTING BUGS
 109 --------------
 110 Report bugs to  <linux-trace-devel@vger.kernel.org>
 111
 112 LICENSE
 113 -------
 114 libtraceevent is Free Software licensed under the GNU LGPL 2.1
 115
 116 RESOURCES
 117 ---------
 118 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git