# tep_filter_alloc

## NAME



           tep_filter_alloc, tep_filter_free, tep_filter_reset,
           tep_filter_make_string, tep_filter_copy, tep_filter_compare,
           tep_filter_match, tep_event_filtered, tep_filter_remove_event,
           tep_filter_strerror, tep_filter_add_filter_str - Event filter
           related APIs.
    


## SYNOPSIS



           **#include <event-parse.h>**
    
           struct tep_event_filter * **tep_filter_alloc**(struct tep_handle *_tep_);
           void **tep_filter_free**(struct tep_event_filter *_filter_);
           void **tep_filter_reset**(struct tep_event_filter *_filter_);
           enum tep_errno **tep_filter_add_filter_str**(struct tep_event_filter *_filter_ , const char *_filter_str_);
           int **tep_event_filtered**(struct tep_event_filter *_filter_ , int _event_id_);
           int **tep_filter_remove_event**(struct tep_event_filter *_filter_ , int _event_id_);
           enum tep_errno **tep_filter_match**(struct tep_event_filter *_filter_ , struct tep_record *_record_);
           int **tep_filter_copy**(struct tep_event_filter *_dest_ , struct tep_event_filter *_source_);
           int **tep_filter_compare**(struct tep_event_filter *_filter1_ , struct tep_event_filter *_filter2_);
           char * **tep_filter_make_string**(struct tep_event_filter *_filter_ , int _event_id_);
           int **tep_filter_strerror**(struct tep_event_filter *_filter_ , enum tep_errno _err_ , char *buf, size_t _buflen_);
    


## DESCRIPTION



           Filters can be attached to traced events. They can be used to
           filter out various events when outputting them. Each event can be
           filtered based on its parameters, described in the event’s format
           file. This set of functions can be used to create, delete, modify
           and attach event filters.
    
           The **tep_filter_alloc()** function creates a new event filter. The
           _tep_ argument is the trace event parser context.
    
           The **tep_filter_free()** function frees an event filter and all
           resources that it had used.
    
           The **tep_filter_reset()** function removes all rules from an event
           filter and resets it.
    
           The **tep_filter_add_filter_str()** function adds a new rule to the
           _filter_. The _filter_str_ argument is the filter string, that
           contains the rule.
    
           The **tep_event_filtered()** function checks if the event with
           _event_id_ has _filter_.
    
           The **tep_filter_remove_event()** function removes a _filter_ for an
           event with _event_id_.
    
           The **tep_filter_match()** function tests if a _record_ matches given
           _filter_.
    
           The **tep_filter_copy()** function copies a _source_ filter into a _dest_
           filter.
    
           The **tep_filter_compare()** function compares two filers - _filter1_
           and _filter2_.
    
           The **tep_filter_make_string()** function constructs a string,
           displaying the _filter_ contents for given _event_id_.
    
           The **tep_filter_strerror()** function copies the _filter_ error buffer
           into the given _buf_ with the size _buflen_. If the error buffer is
           empty, in the _buf_ is copied a string, describing the error _err_.
    


## RETURN VALUE



           The **tep_filter_alloc()** function returns a pointer to the newly
           created event filter, or NULL in case of an error.
    
           The **tep_filter_add_filter_str()** function returns 0 if the rule was
           successfully added or a negative error code. Use
           **tep_filter_strerror()** to see actual error message in case of an
           error.
    
           The **tep_event_filtered()** function returns 1 if the filter is found
           for given event, or 0 otherwise.
    
           The **tep_filter_remove_event()** function returns 1 if the vent was
           removed, or 0 if the event was not found.
    
           The **tep_filter_match()** function returns _tep_errno_ , according to
           the result:
    
               _TEP_ERRNO__FILTER_MATCH_        - filter found for event, the record matches.
               _TEP_ERRNO__FILTER_MISS_         - filter found for event, the record does not match.
               _TEP_ERRNO__FILTER_NOT_FOUND_    - no filter found for record’s event.
               _TEP_ERRNO__NO_FILTER_           - no rules in the filter.
    
           or any other _tep_errno_ , if an error occurred during the test.
    
           The **tep_filter_copy()** function returns 0 on success or -1 if not
           all rules were copied.
    
           The **tep_filter_compare()** function returns 1 if the two filters
           hold the same content, or 0 if they do not.
    
           The **tep_filter_make_string()** function returns a string, which must
           be freed with free(), or NULL in case of an error.
    
           The **tep_filter_strerror()** function returns 0 if message was filled
           successfully, or -1 in case of an error.
    


## EXAMPLE



               #include <event-parse.h>
               ...
               struct tep_handle *tep = tep_alloc();
               ...
               char errstr[200];
               int ret;
    
               struct tep_event_filter *filter = tep_filter_alloc(tep);
               struct tep_event_filter *filter1 = tep_filter_alloc(tep);
               ret = tep_filter_add_filter_str(filter, "sched/sched_wakeup:target_cpu==1");
               if(ret < 0) {
                       tep_filter_strerror(filter, ret, errstr, sizeof(errstr));
                       /* Failed to add a new rule to the filter, the error string is in errstr */
               }
               if (tep_filter_copy(filter1, filter) != 0) {
                       /* Failed to copy filter in filter1 */
               }
               ...
               if (tep_filter_compare(filter, filter1) != 1) {
                       /* Both filters are different */
               }
               ...
               void process_record(struct tep_handle *tep, struct tep_record *record)
               {
                       struct tep_event *event;
                       char *fstring;
    
                       event = tep_find_event_by_record(tep, record);
    
                       if (tep_event_filtered(filter, event->id) == 1) {
                               /* The event has filter */
                               fstring = tep_filter_make_string(filter, event->id);
                               if (fstring != NULL) {
                                       /* The filter for the event is in fstring */
                                       free(fstring);
                               }
                       }
    
                       switch (tep_filter_match(filter, record)) {
                       case TEP_ERRNO__FILTER_MATCH:
                               /* The filter matches the record */
                               break;
                       case TEP_ERRNO__FILTER_MISS:
                               /* The filter does not match the record */
                               break;
                       case TEP_ERRNO__FILTER_NOT_FOUND:
                               /* No filter found for record's event */
                               break;
                       case TEP_ERRNO__NO_FILTER:
                               /* There are no rules in the filter */
                               break
                       default:
                               /* An error occurred during the test */
                               break;
                       }
    
                       if (tep_filter_remove_event(filter, event->id) == 1) {
                               /* The event was removed from the filter */
                       }
               }
    
               ...
               tep_filter_reset(filter);
               ...
               tep_filter_free(filter);
               tep_filter_free(filter1);
               ...
    


## FILES



               **event-parse.h**
                       Header file to include in order to have access to the library APIs.
               **-ltraceevent**
                       Linker switch to add when building a program that uses the library.
    


## LICENSE



           libtraceevent is Free Software licensed under the GNU LGPL 2.1
    


## RESOURCES



           **https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/ **
    


## NOTES



            1. rostedt@goodmis.org
               mailto:rostedt@goodmis.org
    
            2. tz.stoyanov@gmail.com
               mailto:tz.stoyanov@gmail.com
    
            3. linux-trace-devel@vger.kernel.org
               mailto:linux-trace-devel@vger.kernel.org
    


* * *