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

   1 libtraceevent(3)
   2 ================
   3
   4 NAME
   5 ----
   6 tep_print_field, tep_print_fields, tep_print_num_field, tep_print_func_field -
   7 Print the field content.
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 --
  13 *#include <event-parse.h>*
  14 *#include <trace-seq.h>*
  15
  16 void *tep_print_field*(struct trace_seq pass:[*]_s_, void pass:[*]_data_, struct tep_format_field pass:[*]_field_);
  17 void *tep_print_fields*(struct trace_seq pass:[*]_s_, void pass:[*]_data_, int _size_, struct tep_event pass:[*]_event_);
  18 int *tep_print_num_field*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int _err_);
  19 int *tep_print_func_field*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int _err_);
  20 --
  21
  22 DESCRIPTION
  23 -----------
  24 These functions print recorded field's data, according to the field's type.
  25
  26 The _tep_print_field()_ function extracts from the recorded raw _data_ value of
  27 the _field_ and prints it into _s_, according to the field type.
  28
  29 The _tep_print_fields()_ prints each field name followed by the record's field
  30 value according to the field's type:
  31 [verse]
  32 --
  33 "field1_name=field1_value field2_name=field2_value ..."
  34 --
  35 It iterates all fields of the _event_, and calls _tep_print_field()_ for each of
  36 them.
  37
  38 The _tep_print_num_field()_ function prints a numeric field with given format
  39 string. A search is performed in the _event_ for a field with _name_. If such
  40 field is found, its value is extracted from the _record_ and is printed in the
  41 _s_, according to the given format string _fmt_. If the argument _err_ is
  42 non-zero, and an error occures - it is printed in the _s_.
  43
  44 The _tep_print_func_field()_ function prints a function field with given format
  45 string.  A search is performed in the _event_ for a field with _name_. If such
  46 field is found, its value is extracted from the _record_. The value is assumed
  47 to be a function address, and a search is perform to find the name of this
  48 function. The function name (if found) and its address are printed in the _s_,
  49 according to the given format string _fmt_. If the argument _err_ is non-zero,
  50 and an error occures - it is printed in _s_.
  51
  52 RETURN VALUE
  53 ------------
  54 The _tep_print_num_field()_ and _tep_print_func_field()_ functions return 1
  55 on success, -1 in case of an error or 0 if the print buffer _s_ is full.
  56
  57 EXAMPLE
  58 -------
  59 [source,c]
  60 --
  61 #include <event-parse.h>
  62 #include <trace-seq.h>
  63 ...
  64 struct tep_handle *tep = tep_alloc();
  65 ...
  66 struct trace_seq seq;
  67 trace_seq_init(&seq);
  68 struct tep_event *event = tep_find_event_by_name(tep, "timer", "hrtimer_start");
  69 ...
  70 void process_record(struct tep_record *record)
  71 {
  72         struct tep_format_field *field_pid = tep_find_common_field(event, "common_pid");
  73
  74         trace_seq_reset(&seq);
  75
  76         /* Print the value of "common_pid" */
  77         tep_print_field(&seq, record->data, field_pid);
  78
  79         /* Print all fields of the "hrtimer_start" event */
  80         tep_print_fields(&seq, record->data, record->size, event);
  81
  82         /* Print the value of "expires" field with custom format string */
  83         tep_print_num_field(&seq, " timer expires in %llu ", event, "expires", record, 0);
  84
  85         /* Print the address and the name of "function" field with custom format string */
  86         tep_print_func_field(&seq, " timer function is %s ", event, "function", record, 0);
  87  }
  88  ...
  89 --
  90
  91 FILES
  92 -----
  93 [verse]
  94 --
  95 *event-parse.h*
  96         Header file to include in order to have access to the library APIs.
  97 *trace-seq.h*
  98         Header file to include in order to have access to trace sequences related APIs.
  99         Trace sequences are used to allow a function to call several other functions
 100         to create a string of data to use.
 101 *-ltraceevent*
 102         Linker switch to add when building a program that uses the library.
 103 --
 104
 105 SEE ALSO
 106 --------
 107 _libtraceevent(3)_, _trace-cmd(1)_
 108
 109 AUTHOR
 110 ------
 111 [verse]
 112 --
 113 *Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
 114 *Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
 115 --
 116 REPORTING BUGS
 117 --------------
 118 Report bugs to  <linux-trace-devel@vger.kernel.org>
 119
 120 LICENSE
 121 -------
 122 libtraceevent is Free Software licensed under the GNU LGPL 2.1
 123
 124 RESOURCES
 125 ---------
 126 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git