1libtraceevent(3) 2================ 3 4NAME 5---- 6tep_filter_alloc, tep_filter_free, tep_filter_reset, tep_filter_make_string, 7tep_filter_copy, tep_filter_compare, tep_filter_match, tep_event_filtered, 8tep_filter_remove_event, tep_filter_strerror, tep_filter_add_filter_str - 9Event filter related APIs. 10 11SYNOPSIS 12-------- 13[verse] 14-- 15*#include <event-parse.h>* 16 17struct tep_event_filter pass:[*]*tep_filter_alloc*(struct tep_handle pass:[*]_tep_); 18void *tep_filter_free*(struct tep_event_filter pass:[*]_filter_); 19void *tep_filter_reset*(struct tep_event_filter pass:[*]_filter_); 20enum tep_errno *tep_filter_add_filter_str*(struct tep_event_filter pass:[*]_filter_, const char pass:[*]_filter_str_); 21int *tep_event_filtered*(struct tep_event_filter pass:[*]_filter_, int _event_id_); 22int *tep_filter_remove_event*(struct tep_event_filter pass:[*]_filter_, int _event_id_); 23enum tep_errno *tep_filter_match*(struct tep_event_filter pass:[*]_filter_, struct tep_record pass:[*]_record_); 24int *tep_filter_copy*(struct tep_event_filter pass:[*]_dest_, struct tep_event_filter pass:[*]_source_); 25int *tep_filter_compare*(struct tep_event_filter pass:[*]_filter1_, struct tep_event_filter pass:[*]_filter2_); 26char pass:[*]*tep_filter_make_string*(struct tep_event_filter pass:[*]_filter_, int _event_id_); 27int *tep_filter_strerror*(struct tep_event_filter pass:[*]_filter_, enum tep_errno _err_, char pass:[*]buf, size_t _buflen_); 28-- 29 30DESCRIPTION 31----------- 32Filters can be attached to traced events. They can be used to filter out various 33events when outputting them. Each event can be filtered based on its parameters, 34described in the event's format file. This set of functions can be used to 35create, delete, modify and attach event filters. 36 37The *tep_filter_alloc()* function creates a new event filter. The _tep_ argument 38is the trace event parser context. 39 40The *tep_filter_free()* function frees an event filter and all resources that it 41had used. 42 43The *tep_filter_reset()* function removes all rules from an event filter and 44resets it. 45 46The *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 49The *tep_event_filtered()* function checks if the event with _event_id_ has 50_filter_. 51 52The *tep_filter_remove_event()* function removes a _filter_ for an event with 53_event_id_. 54 55The *tep_filter_match()* function tests if a _record_ matches given _filter_. 56 57The *tep_filter_copy()* function copies a _source_ filter into a _dest_ filter. 58 59The *tep_filter_compare()* function compares two filers - _filter1_ and _filter2_. 60 61The *tep_filter_make_string()* function constructs a string, displaying 62the _filter_ contents for given _event_id_. 63 64The *tep_filter_strerror()* function copies the _filter_ error buffer into the 65given _buf_ with the size _buflen_. If the error buffer is empty, in the _buf_ 66is copied a string, describing the error _err_. 67 68RETURN VALUE 69------------ 70The *tep_filter_alloc()* function returns a pointer to the newly created event 71filter, or NULL in case of an error. 72 73The *tep_filter_add_filter_str()* function returns 0 if the rule was 74successfully added or a negative error code. Use *tep_filter_strerror()* to see 75actual error message in case of an error. 76 77The *tep_event_filtered()* function returns 1 if the filter is found for given 78event, or 0 otherwise. 79 80The *tep_filter_remove_event()* function returns 1 if the vent was removed, or 810 if the event was not found. 82 83The *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-- 91or any other _tep_errno_, if an error occurred during the test. 92 93The *tep_filter_copy()* function returns 0 on success or -1 if not all rules 94 were copied. 95 96The *tep_filter_compare()* function returns 1 if the two filters hold the same 97content, or 0 if they do not. 98 99The *tep_filter_make_string()* function returns a string, which must be freed 100with free(), or NULL in case of an error. 101 102The *tep_filter_strerror()* function returns 0 if message was filled 103successfully, or -1 in case of an error. 104 105EXAMPLE 106------- 107[source,c] 108-- 109#include <event-parse.h> 110... 111struct tep_handle *tep = tep_alloc(); 112... 113char errstr[200]; 114int ret; 115 116struct tep_event_filter *filter = tep_filter_alloc(tep); 117struct tep_event_filter *filter1 = tep_filter_alloc(tep); 118ret = tep_filter_add_filter_str(filter, "sched/sched_wakeup:target_cpu==1"); 119if(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} 123if (tep_filter_copy(filter1, filter) != 0) { 124 /* Failed to copy filter in filter1 */ 125} 126... 127if (tep_filter_compare(filter, filter1) != 1) { 128 /* Both filters are different */ 129} 130... 131void 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... 171tep_filter_reset(filter); 172... 173tep_filter_free(filter); 174tep_filter_free(filter1); 175... 176-- 177 178FILES 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 188SEE ALSO 189-------- 190*libtraceevent*(3), *trace-cmd*(1) 191 192AUTHOR 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-- 199REPORTING BUGS 200-------------- 201Report bugs to <linux-trace-devel@vger.kernel.org> 202 203LICENSE 204------- 205libtraceevent is Free Software licensed under the GNU LGPL 2.1 206 207RESOURCES 208--------- 209https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/ 210