0001 libtraceevent(3)
0002 ================
0003
0004 NAME
0005 ----
0006 tep_filter_alloc, tep_filter_free, tep_filter_reset, tep_filter_make_string,
0007 tep_filter_copy, tep_filter_compare, tep_filter_match, tep_event_filtered,
0008 tep_filter_remove_event, tep_filter_strerror, tep_filter_add_filter_str -
0009 Event filter related APIs.
0010
0011 SYNOPSIS
0012 --------
0013 [verse]
0014 --
0015 *#include <event-parse.h>*
0016
0017 struct tep_event_filter pass:[*]*tep_filter_alloc*(struct tep_handle pass:[*]_tep_);
0018 void *tep_filter_free*(struct tep_event_filter pass:[*]_filter_);
0019 void *tep_filter_reset*(struct tep_event_filter pass:[*]_filter_);
0020 enum tep_errno *tep_filter_add_filter_str*(struct tep_event_filter pass:[*]_filter_, const char pass:[*]_filter_str_);
0021 int *tep_event_filtered*(struct tep_event_filter pass:[*]_filter_, int _event_id_);
0022 int *tep_filter_remove_event*(struct tep_event_filter pass:[*]_filter_, int _event_id_);
0023 enum tep_errno *tep_filter_match*(struct tep_event_filter pass:[*]_filter_, struct tep_record pass:[*]_record_);
0024 int *tep_filter_copy*(struct tep_event_filter pass:[*]_dest_, struct tep_event_filter pass:[*]_source_);
0025 int *tep_filter_compare*(struct tep_event_filter pass:[*]_filter1_, struct tep_event_filter pass:[*]_filter2_);
0026 char pass:[*]*tep_filter_make_string*(struct tep_event_filter pass:[*]_filter_, int _event_id_);
0027 int *tep_filter_strerror*(struct tep_event_filter pass:[*]_filter_, enum tep_errno _err_, char pass:[*]buf, size_t _buflen_);
0028 --
0029
0030 DESCRIPTION
0031 -----------
0032 Filters can be attached to traced events. They can be used to filter out various
0033 events when outputting them. Each event can be filtered based on its parameters,
0034 described in the event's format file. This set of functions can be used to
0035 create, delete, modify and attach event filters.
0036
0037 The _tep_filter_alloc()_ function creates a new event filter. The _tep_ argument
0038 is the trace event parser context.
0039
0040 The _tep_filter_free()_ function frees an event filter and all resources that it
0041 had used.
0042
0043 The _tep_filter_reset()_ function removes all rules from an event filter and
0044 resets it.
0045
0046 The _tep_filter_add_filter_str()_ function adds a new rule to the _filter_. The
0047 _filter_str_ argument is the filter string, that contains the rule.
0048
0049 The _tep_event_filtered()_ function checks if the event with _event_id_ has
0050 _filter_.
0051
0052 The _tep_filter_remove_event()_ function removes a _filter_ for an event with
0053 _event_id_.
0054
0055 The _tep_filter_match()_ function tests if a _record_ matches given _filter_.
0056
0057 The _tep_filter_copy()_ function copies a _source_ filter into a _dest_ filter.
0058
0059 The _tep_filter_compare()_ function compares two filers - _filter1_ and _filter2_.
0060
0061 The _tep_filter_make_string()_ function constructs a string, displaying
0062 the _filter_ contents for given _event_id_.
0063
0064 The _tep_filter_strerror()_ function copies the _filter_ error buffer into the
0065 given _buf_ with the size _buflen_. If the error buffer is empty, in the _buf_
0066 is copied a string, describing the error _err_.
0067
0068 RETURN VALUE
0069 ------------
0070 The _tep_filter_alloc()_ function returns a pointer to the newly created event
0071 filter, or NULL in case of an error.
0072
0073 The _tep_filter_add_filter_str()_ function returns 0 if the rule was
0074 successfully added or a negative error code. Use _tep_filter_strerror()_ to see
0075 actual error message in case of an error.
0076
0077 The _tep_event_filtered()_ function returns 1 if the filter is found for given
0078 event, or 0 otherwise.
0079
0080 The _tep_filter_remove_event()_ function returns 1 if the vent was removed, or
0081 0 if the event was not found.
0082
0083 The _tep_filter_match()_ function returns _tep_errno_, according to the result:
0084 [verse]
0085 --
0086 _pass:[TEP_ERRNO__FILTER_MATCH]_ - filter found for event, the record matches.
0087 _pass:[TEP_ERRNO__FILTER_MISS]_ - filter found for event, the record does not match.
0088 _pass:[TEP_ERRNO__FILTER_NOT_FOUND]_ - no filter found for record's event.
0089 _pass:[TEP_ERRNO__NO_FILTER]_ - no rules in the filter.
0090 --
0091 or any other _tep_errno_, if an error occurred during the test.
0092
0093 The _tep_filter_copy()_ function returns 0 on success or -1 if not all rules
0094 were copied.
0095
0096 The _tep_filter_compare()_ function returns 1 if the two filters hold the same
0097 content, or 0 if they do not.
0098
0099 The _tep_filter_make_string()_ function returns a string, which must be freed
0100 with free(), or NULL in case of an error.
0101
0102 The _tep_filter_strerror()_ function returns 0 if message was filled
0103 successfully, or -1 in case of an error.
0104
0105 EXAMPLE
0106 -------
0107 [source,c]
0108 --
0109 #include <event-parse.h>
0110 ...
0111 struct tep_handle *tep = tep_alloc();
0112 ...
0113 char errstr[200];
0114 int ret;
0115
0116 struct tep_event_filter *filter = tep_filter_alloc(tep);
0117 struct tep_event_filter *filter1 = tep_filter_alloc(tep);
0118 ret = tep_filter_add_filter_str(filter, "sched/sched_wakeup:target_cpu==1");
0119 if(ret < 0) {
0120 tep_filter_strerror(filter, ret, errstr, sizeof(errstr));
0121 /* Failed to add a new rule to the filter, the error string is in errstr */
0122 }
0123 if (tep_filter_copy(filter1, filter) != 0) {
0124 /* Failed to copy filter in filter1 */
0125 }
0126 ...
0127 if (tep_filter_compare(filter, filter1) != 1) {
0128 /* Both filters are different */
0129 }
0130 ...
0131 void process_record(struct tep_handle *tep, struct tep_record *record)
0132 {
0133 struct tep_event *event;
0134 char *fstring;
0135
0136 event = tep_find_event_by_record(tep, record);
0137
0138 if (tep_event_filtered(filter, event->id) == 1) {
0139 /* The event has filter */
0140 fstring = tep_filter_make_string(filter, event->id);
0141 if (fstring != NULL) {
0142 /* The filter for the event is in fstring */
0143 free(fstring);
0144 }
0145 }
0146
0147 switch (tep_filter_match(filter, record)) {
0148 case TEP_ERRNO__FILTER_MATCH:
0149 /* The filter matches the record */
0150 break;
0151 case TEP_ERRNO__FILTER_MISS:
0152 /* The filter does not match the record */
0153 break;
0154 case TEP_ERRNO__FILTER_NOT_FOUND:
0155 /* No filter found for record's event */
0156 break;
0157 case TEP_ERRNO__NO_FILTER:
0158 /* There are no rules in the filter */
0159 break
0160 default:
0161 /* An error occurred during the test */
0162 break;
0163 }
0164
0165 if (tep_filter_remove_event(filter, event->id) == 1) {
0166 /* The event was removed from the filter */
0167 }
0168 }
0169
0170 ...
0171 tep_filter_reset(filter);
0172 ...
0173 tep_filter_free(filter);
0174 tep_filter_free(filter1);
0175 ...
0176 --
0177
0178 FILES
0179 -----
0180 [verse]
0181 --
0182 *event-parse.h*
0183 Header file to include in order to have access to the library APIs.
0184 *-ltraceevent*
0185 Linker switch to add when building a program that uses the library.
0186 --
0187
0188 SEE ALSO
0189 --------
0190 _libtraceevent(3)_, _trace-cmd(1)_
0191
0192 AUTHOR
0193 ------
0194 [verse]
0195 --
0196 *Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
0197 *Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
0198 --
0199 REPORTING BUGS
0200 --------------
0201 Report bugs to <linux-trace-devel@vger.kernel.org>
0202
0203 LICENSE
0204 -------
0205 libtraceevent is Free Software licensed under the GNU LGPL 2.1
0206
0207 RESOURCES
0208 ---------
0209 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
