'\" t
.\"     Title: libtraceevent
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 05/23/2021
.\"    Manual: libtraceevent Manual
.\"    Source: libtraceevent 1.3.0
.\"  Language: English
.\"
.TH "LIBTRACEEVENT" "3" "05/23/2021" "libtraceevent 1\&.3\&.0" "libtraceevent Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "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\&.
.SH "SYNOPSIS"
.sp
.nf
\fB#include <event\-parse\&.h>\fR

struct tep_event_filter *\fBtep_filter_alloc\fR(struct tep_handle *\fItep\fR);
void \fBtep_filter_free\fR(struct tep_event_filter *\fIfilter\fR);
void \fBtep_filter_reset\fR(struct tep_event_filter *\fIfilter\fR);
enum tep_errno \fBtep_filter_add_filter_str\fR(struct tep_event_filter *\fIfilter\fR, const char *\fIfilter_str\fR);
int \fBtep_event_filtered\fR(struct tep_event_filter *\fIfilter\fR, int \fIevent_id\fR);
int \fBtep_filter_remove_event\fR(struct tep_event_filter *\fIfilter\fR, int \fIevent_id\fR);
enum tep_errno \fBtep_filter_match\fR(struct tep_event_filter *\fIfilter\fR, struct tep_record *\fIrecord\fR);
int \fBtep_filter_copy\fR(struct tep_event_filter *\fIdest\fR, struct tep_event_filter *\fIsource\fR);
int \fBtep_filter_compare\fR(struct tep_event_filter *\fIfilter1\fR, struct tep_event_filter *\fIfilter2\fR);
char *\fBtep_filter_make_string\fR(struct tep_event_filter *\fIfilter\fR, int \fIevent_id\fR);
int \fBtep_filter_strerror\fR(struct tep_event_filter *\fIfilter\fR, enum tep_errno \fIerr\fR, char *buf, size_t \fIbuflen\fR);
.fi
.SH "DESCRIPTION"
.sp
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\(cqs format file\&. This set of functions can be used to create, delete, modify and attach event filters\&.
.sp
The \fItep_filter_alloc()\fR function creates a new event filter\&. The \fItep\fR argument is the trace event parser context\&.
.sp
The \fItep_filter_free()\fR function frees an event filter and all resources that it had used\&.
.sp
The \fItep_filter_reset()\fR function removes all rules from an event filter and resets it\&.
.sp
The \fItep_filter_add_filter_str()\fR function adds a new rule to the \fIfilter\fR\&. The \fIfilter_str\fR argument is the filter string, that contains the rule\&.
.sp
The \fItep_event_filtered()\fR function checks if the event with \fIevent_id\fR has \fIfilter\fR\&.
.sp
The \fItep_filter_remove_event()\fR function removes a \fIfilter\fR for an event with \fIevent_id\fR\&.
.sp
The \fItep_filter_match()\fR function tests if a \fIrecord\fR matches given \fIfilter\fR\&.
.sp
The \fItep_filter_copy()\fR function copies a \fIsource\fR filter into a \fIdest\fR filter\&.
.sp
The \fItep_filter_compare()\fR function compares two filers \- \fIfilter1\fR and \fIfilter2\fR\&.
.sp
The \fItep_filter_make_string()\fR function constructs a string, displaying the \fIfilter\fR contents for given \fIevent_id\fR\&.
.sp
The \fItep_filter_strerror()\fR function copies the \fIfilter\fR error buffer into the given \fIbuf\fR with the size \fIbuflen\fR\&. If the error buffer is empty, in the \fIbuf\fR is copied a string, describing the error \fIerr\fR\&.
.SH "RETURN VALUE"
.sp
The \fItep_filter_alloc()\fR function returns a pointer to the newly created event filter, or NULL in case of an error\&.
.sp
The \fItep_filter_add_filter_str()\fR function returns 0 if the rule was successfully added or a negative error code\&. Use \fItep_filter_strerror()\fR to see actual error message in case of an error\&.
.sp
The \fItep_event_filtered()\fR function returns 1 if the filter is found for given event, or 0 otherwise\&.
.sp
The \fItep_filter_remove_event()\fR function returns 1 if the vent was removed, or 0 if the event was not found\&.
.sp
The \fItep_filter_match()\fR function returns \fItep_errno\fR, according to the result:
.sp
.if n \{\
.RS 4
.\}
.nf
\fITEP_ERRNO__FILTER_MATCH\fR        \- filter found for event, the record matches\&.
\fITEP_ERRNO__FILTER_MISS\fR         \- filter found for event, the record does not match\&.
\fITEP_ERRNO__FILTER_NOT_FOUND\fR    \- no filter found for record\(cqs event\&.
\fITEP_ERRNO__NO_FILTER\fR           \- no rules in the filter\&.
.fi
.if n \{\
.RE
.\}
.sp
or any other \fItep_errno\fR, if an error occurred during the test\&.
.sp
The \fItep_filter_copy()\fR function returns 0 on success or \-1 if not all rules were copied\&.
.sp
The \fItep_filter_compare()\fR function returns 1 if the two filters hold the same content, or 0 if they do not\&.
.sp
The \fItep_filter_make_string()\fR function returns a string, which must be freed with free(), or NULL in case of an error\&.
.sp
The \fItep_filter_strerror()\fR function returns 0 if message was filled successfully, or \-1 in case of an error\&.
.SH "EXAMPLE"
.sp
.if n \{\
.RS 4
.\}
.nf
#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\*(Aqs 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);
\&.\&.\&.
.fi
.if n \{\
.RE
.\}
.SH "FILES"
.sp
.if n \{\
.RS 4
.\}
.nf
\fBevent\-parse\&.h\fR
        Header file to include in order to have access to the library APIs\&.
\fB\-ltraceevent\fR
        Linker switch to add when building a program that uses the library\&.
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
\fIlibtraceevent(3)\fR, \fItrace\-cmd(1)\fR
.SH "AUTHOR"
.sp
.if n \{\
.RS 4
.\}
.nf
\fBSteven Rostedt\fR <\m[blue]\fBrostedt@goodmis\&.org\fR\m[]\&\s-2\u[1]\d\s+2>, author of \fBlibtraceevent\fR\&.
\fBTzvetomir Stoyanov\fR <\m[blue]\fBtz\&.stoyanov@gmail\&.com\fR\m[]\&\s-2\u[2]\d\s+2>, author of this man page\&.
.fi
.if n \{\
.RE
.\}
.SH "REPORTING BUGS"
.sp
Report bugs to <\m[blue]\fBlinux\-trace\-devel@vger\&.kernel\&.org\fR\m[]\&\s-2\u[3]\d\s+2>
.SH "LICENSE"
.sp
libtraceevent is Free Software licensed under the GNU LGPL 2\&.1
.SH "RESOURCES"
.sp
\m[blue]\fBhttps://git\&.kernel\&.org/pub/scm/libs/libtrace/libtraceevent\&.git/\fR\m[]
.SH "NOTES"
.IP " 1." 4
rostedt@goodmis.org
.RS 4
\%mailto:rostedt@goodmis.org
.RE
.IP " 2." 4
tz.stoyanov@gmail.com
.RS 4
\%mailto:tz.stoyanov@gmail.com
.RE
.IP " 3." 4
linux-trace-devel@vger.kernel.org
.RS 4
\%mailto:linux-trace-devel@vger.kernel.org
.RE