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

   1 libtraceevent(3)
   2 ================
   3
   4 NAME
   5 ----
   6 tep_filter_alloc, tep_filter_free, tep_filter_reset, tep_filter_make_string,
   7 tep_filter_copy, tep_filter_compare, tep_filter_match, tep_event_filtered,
   8 tep_filter_remove_event, tep_filter_strerror, tep_filter_add_filter_str -
   9 Event filter related APIs.
  10
  11 SYNOPSIS
  12 --------
  13 [verse]
  14 --
  15 *#include <event-parse.h>*
  16
  17 struct tep_event_filter pass:[*]*tep_filter_alloc*(struct tep_handle pass:[*]_tep_);
  18 void *tep_filter_free*(struct tep_event_filter pass:[*]_filter_);
  19 void *tep_filter_reset*(struct tep_event_filter pass:[*]_filter_);
  20 enum tep_errno *tep_filter_add_filter_str*(struct tep_event_filter pass:[*]_filter_, const char pass:[*]_filter_str_);
  21 int *tep_event_filtered*(struct tep_event_filter pass:[*]_filter_, int _event_id_);
  22 int *tep_filter_remove_event*(struct tep_event_filter pass:[*]_filter_, int _event_id_);
  23 enum tep_errno *tep_filter_match*(struct tep_event_filter pass:[*]_filter_, struct tep_record pass:[*]_record_);
  24 int *tep_filter_copy*(struct tep_event_filter pass:[*]_dest_, struct tep_event_filter pass:[*]_source_);
  25 int *tep_filter_compare*(struct tep_event_filter pass:[*]_filter1_, struct tep_event_filter pass:[*]_filter2_);
  26 char pass:[*]*tep_filter_make_string*(struct tep_event_filter pass:[*]_filter_, int _event_id_);
  27 int *tep_filter_strerror*(struct tep_event_filter pass:[*]_filter_, enum tep_errno _err_, char pass:[*]buf, size_t _buflen_);
  28 --
  29
  30 DESCRIPTION
  31 -----------
  32 Filters can be attached to traced events. They can be used to filter out various
  33 events when outputting them. Each event can be filtered based on its parameters,
  34 described in the event's format file. This set of functions can be used to
  35 create, delete, modify and attach event filters.
  36
  37 The _tep_filter_alloc()_ function creates a new event filter. The _tep_ argument
  38 is the trace event parser context.
  39
  40 The _tep_filter_free()_ function frees an event filter and all resources that it
  41 had used.
  42
  43 The _tep_filter_reset()_ function removes all rules from an event filter and
  44 resets it.
  45
  46 The _tep_filter_add_filter_str()_ function adds a new rule to the _filter_. The
  47 _filter_str_ argument is the filter string, that contains the rule.
  48
  49 The _tep_event_filtered()_ function checks if the event with _event_id_ has
  50 _filter_.
  51
  52 The _tep_filter_remove_event()_ function removes a _filter_ for an event with
  53 _event_id_.
  54
  55 The _tep_filter_match()_ function tests if a _record_ matches given _filter_.
  56
  57 The _tep_filter_copy()_ function copies a _source_ filter into a _dest_ filter.
  58
  59 The _tep_filter_compare()_ function compares two filers - _filter1_ and _filter2_.
  60
  61 The _tep_filter_make_string()_ function constructs a string, displaying
  62 the _filter_ contents for given _event_id_.
  63
  64 The _tep_filter_strerror()_ function copies the _filter_ error buffer into the
  65 given _buf_ with the size _buflen_. If the error buffer is empty, in the _buf_
  66 is copied a string, describing the error _err_.
  67
  68 RETURN VALUE
  69 ------------
  70 The _tep_filter_alloc()_ function returns a pointer to the newly created event
  71 filter, or NULL in case of an error.
  72
  73 The _tep_filter_add_filter_str()_ function returns 0 if the rule was
  74 successfully added or a negative error code.  Use _tep_filter_strerror()_ to see
  75 actual error message in case of an error.
  76
  77 The _tep_event_filtered()_ function returns 1 if the filter is found for given
  78 event, or 0 otherwise.
  79
  80 The _tep_filter_remove_event()_ function returns 1 if the vent was removed, or
  81 0 if the event was not found.
  82
  83 The _tep_filter_match()_ function returns _tep_errno_, according to the result:
  84 [verse]
  85 --
  86 _pass:[TEP_ERRNO__FILTER_MATCH]_        - filter found for event, the record matches.
  87 _pass:[TEP_ERRNO__FILTER_MISS]_         - filter found for event, the record does not match.
  88 _pass:[TEP_ERRNO__FILTER_NOT_FOUND]_    - no filter found for record's event.
  89 _pass:[TEP_ERRNO__NO_FILTER]_           - no rules in the filter.
  90 --
  91 or any other _tep_errno_, if an error occurred during the test.
  92
  93 The _tep_filter_copy()_ function returns 0 on success or -1 if not all rules
  94  were copied.
  95
  96 The _tep_filter_compare()_ function returns 1 if the two filters hold the same
  97 content, or 0 if they do not.
  98
  99 The _tep_filter_make_string()_ function returns a string, which must be freed
 100 with free(), or NULL in case of an error.
 101
 102 The _tep_filter_strerror()_ function returns 0 if message was filled
 103 successfully, or -1 in case of an error.
 104
 105 EXAMPLE
 106 -------
 107 [source,c]
 108 --
 109 #include <event-parse.h>
 110 ...
 111 struct tep_handle *tep = tep_alloc();
 112 ...
 113 char errstr[200];
 114 int ret;
 115
 116 struct tep_event_filter *filter = tep_filter_alloc(tep);
 117 struct tep_event_filter *filter1 = tep_filter_alloc(tep);
 118 ret = tep_filter_add_filter_str(filter, "sched/sched_wakeup:target_cpu==1");
 119 if(ret < 0) {
 120         tep_filter_strerror(filter, ret, errstr, sizeof(errstr));
 121         /* Failed to add a new rule to the filter, the error string is in errstr */
 122 }
 123 if (tep_filter_copy(filter1, filter) != 0) {
 124         /* Failed to copy filter in filter1 */
 125 }
 126 ...
 127 if (tep_filter_compare(filter, filter1) != 1) {
 128         /* Both filters are different */
 129 }
 130 ...
 131 void process_record(struct tep_handle *tep, struct tep_record *record)
 132 {
 133         struct tep_event *event;
 134         char *fstring;
 135
 136         event = tep_find_event_by_record(tep, record);
 137
 138         if (tep_event_filtered(filter, event->id) == 1) {
 139                 /* The event has filter */
 140                 fstring = tep_filter_make_string(filter, event->id);
 141                 if (fstring != NULL) {
 142                         /* The filter for the event is in fstring */
 143                         free(fstring);
 144                 }
 145         }
 146
 147         switch (tep_filter_match(filter, record)) {
 148         case TEP_ERRNO__FILTER_MATCH:
 149                 /* The filter matches the record */
 150                 break;
 151         case TEP_ERRNO__FILTER_MISS:
 152                 /* The filter does not match the record */
 153                 break;
 154         case TEP_ERRNO__FILTER_NOT_FOUND:
 155                 /* No filter found for record's event */
 156                 break;
 157         case TEP_ERRNO__NO_FILTER:
 158                 /* There are no rules in the filter */
 159                 break
 160         default:
 161                 /* An error occurred during the test */
 162                 break;
 163         }
 164
 165         if (tep_filter_remove_event(filter, event->id) == 1) {
 166                 /* The event was removed from the filter */
 167         }
 168 }
 169
 170 ...
 171 tep_filter_reset(filter);
 172 ...
 173 tep_filter_free(filter);
 174 tep_filter_free(filter1);
 175 ...
 176 --
 177
 178 FILES
 179 -----
 180 [verse]
 181 --
 182 *event-parse.h*
 183         Header file to include in order to have access to the library APIs.
 184 *-ltraceevent*
 185         Linker switch to add when building a program that uses the library.
 186 --
 187
 188 SEE ALSO
 189 --------
 190 _libtraceevent(3)_, _trace-cmd(1)_
 191
 192 AUTHOR
 193 ------
 194 [verse]
 195 --
 196 *Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
 197 *Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
 198 --
 199 REPORTING BUGS
 200 --------------
 201 Report bugs to  <linux-trace-devel@vger.kernel.org>
 202
 203 LICENSE
 204 -------
 205 libtraceevent is Free Software licensed under the GNU LGPL 2.1
 206
 207 RESOURCES
 208 ---------
 209 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git