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

   1 libtraceevent(3)
   2 ================
   3
   4 NAME
   5 ----
   6 tep_get_any_field_val, tep_get_common_field_val, tep_get_field_val,
   7 tep_get_field_raw - Get value of a field.
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 --
  13 *#include <event-parse.h>*
  14 *#include <trace-seq.h>*
  15
  16 int *tep_get_any_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_);
  17 int *tep_get_common_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_);
  18 int *tep_get_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_);
  19 void pass:[*]*tep_get_field_raw*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int pass:[*]_len_, int _err_);
  20 --
  21
  22 DESCRIPTION
  23 -----------
  24 These functions can be used to find a field and retrieve its value.
  25
  26 The _tep_get_any_field_val()_ function searches in the _record_ for a field
  27 with _name_, part of the _event_. If the field is found, its value is stored in
  28 _val_. If there is an error and _err_ is not zero, then an error string is
  29 written into _s_.
  30
  31 The _tep_get_common_field_val()_ function does the same as
  32 _tep_get_any_field_val()_, but searches only in the common fields. This works
  33 for any event as all events include the common fields.
  34
  35 The _tep_get_field_val()_ function does the same as _tep_get_any_field_val()_,
  36 but searches only in the event specific fields.
  37
  38 The _tep_get_field_raw()_ function searches in the _record_ for a field with
  39 _name_, part of the _event_. If the field is found, a pointer to where the field
  40 exists in the record's raw data is returned. The size of the data is stored in
  41 _len_. If there is an error and _err_ is not zero, then an error string is
  42 written into _s_.
  43
  44 RETURN VALUE
  45 ------------
  46 The _tep_get_any_field_val()_, _tep_get_common_field_val()_ and
  47 _tep_get_field_val()_ functions return 0 on success, or -1 in case of an error.
  48
  49 The _tep_get_field_raw()_ function returns a pointer to field's raw data, and
  50 places the length of this data in _len_. In case of an error NULL is returned.
  51
  52 EXAMPLE
  53 -------
  54 [source,c]
  55 --
  56 #include <event-parse.h>
  57 #include <trace-seq.h>
  58 ...
  59 struct tep_handle *tep = tep_alloc();
  60 ...
  61 struct tep_event *event = tep_find_event_by_name(tep, "kvm", "kvm_exit");
  62 ...
  63 void process_record(struct tep_record *record)
  64 {
  65         int len;
  66         char *comm;
  67         struct tep_event_format *event;
  68         unsigned long long val;
  69
  70         event = tep_find_event_by_record(pevent, record);
  71         if (event != NULL) {
  72                 if (tep_get_common_field_val(NULL, event, "common_type",
  73                                              record, &val, 0) == 0) {
  74                         /* Got the value of common type field */
  75                 }
  76                 if (tep_get_field_val(NULL, event, "pid", record, &val, 0) == 0) {
  77                         /* Got the value of pid specific field */
  78                 }
  79                 comm = tep_get_field_raw(NULL, event, "comm", record, &len, 0);
  80                 if (comm != NULL) {
  81                         /* Got a pointer to the comm event specific field */
  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 *trace-seq.h*
  94         Header file to include in order to have access to trace sequences
  95         related APIs. Trace sequences are used to allow a function to call
  96         several other functions to create a string of data to use.
  97 *-ltraceevent*
  98         Linker switch to add when building a program that uses the library.
  99 --
 100
 101 SEE ALSO
 102 --------
 103 _libtraceevent(3)_, _trace-cmd(1)_
 104
 105 AUTHOR
 106 ------
 107 [verse]
 108 --
 109 *Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
 110 *Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
 111 --
 112 REPORTING BUGS
 113 --------------
 114 Report bugs to  <linux-trace-devel@vger.kernel.org>
 115
 116 LICENSE
 117 -------
 118 libtraceevent is Free Software licensed under the GNU LGPL 2.1
 119
 120 RESOURCES
 121 ---------
 122 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git