| libtracefs(3) |
| ============= |
| |
| NAME |
| ---- |
| tracefs_filter_string_append, tracefs_filter_string_verify, tracefs_event_filter_apply, tracefs_event_filter_clear - |
| Add, verify and apply event filters |
| |
| SYNOPSIS |
| -------- |
| [verse] |
| -- |
| *#include <tracefs.h>* |
| |
| int *tracefs_filter_string_append*(struct tep_event pass:[*]_event_, char pass:[**]_filter_, |
| struct tracefs_filter _type_, const char pass:[*]_field_, |
| enum tracefs_synth_compare _compare_, const char pass:[*]_val_); |
| int *tracefs_filter_string_verify*(struct tep_event pass:[*]_event_, const char pass:[*]_filter_, char pass:[**]_err_); |
| int *tracefs_event_filter_apply*(struct tracefs_instance pass:[*]_instance_, struct tep_event pass:[*]_event_, const char pass:[*]_filter_); |
| int *tracefs_event_filter_clear*(struct tracefs_instance pass:[*]_instance_, struct tep_event pass:[*]_event_); |
| |
| -- |
| |
| DESCRIPTION |
| ----------- |
| *tracefs_filter_string_append*() is a way to create and verify event filters for |
| a given event. It will verify that the _field_ belongs to the event and that |
| the _compare_ option that is used is valid for the type of the field, as well |
| as _val_. For the _type_ that is not of *TRACEFS_FILTER_COMPARE*, it will build |
| the logical string and also make sure that the syntax is correct. For example, |
| there are no more close parenthesis than open parenthesis. An AND (&&) or OR |
| (||) is not misplaced, etc. |
| |
| *tracefs_synth_append_start_filter*() creates a filter or appends to it for the |
| starting event. Depending on _type_, it will build a string of tokens for |
| parenthesis or logic statemens, or it may add a comparison of _field_ |
| to _val_ based on _compare_. |
| |
| If _type_ is: |
| *TRACEFS_FILTER_COMPARE* - See below |
| *TRACEFS_FILTER_AND* - Append "&&" to the filter |
| *TRACEFS_FILTER_OR* - Append "||" to the filter |
| *TRACEFS_FILTER_NOT* - Append "!" to the filter |
| *TRACEFS_FILTER_OPEN_PAREN* - Append "(" to the filter |
| *TRACEFS_FILTER_CLOSE_PAREN* - Append ")" to the filter |
| |
| _field_, _compare_, and _val_ are ignored unless _type_ is equal to |
| *TRACEFS_FILTER_COMPARE*, then _compare will be used for the following: |
| |
| *TRACEFS_COMPARE_EQ* - _field_ == _val_ |
| |
| *TRACEFS_COMPARE_NE* - _field_ != _val_ |
| |
| *TRACEFS_COMPARE_GT* - _field_ > _val_ |
| |
| *TRACEFS_COMPARE_GE* - _field_ >= _val_ |
| |
| *TRACEFS_COMPARE_LT* - _field_ < _val_ |
| |
| *TRACEFS_COMPARE_LE* - _field_ <pass:[=] _val_ |
| |
| *TRACEFS_COMPARE_RE* - _field_ ~ "_val_" : where _field_ is a string. |
| |
| *TRACEFS_COMPARE_AND* - _field_ & _val_ : where _field_ is a flags field. |
| |
| *tracefs_filter_string_verify*() will parse _filter_ to make sure that the |
| fields are for the _event_, and that the syntax is correct. If there's an |
| error in the syntax, and _err_ is not NULL, then it will be allocated with an |
| error message stating what was found wrong with the filter. _err_ must be freed |
| with *free*(). |
| |
| *tracefs_event_filter_apply*() applies given _filter_ string on _event_ in given _instance_. |
| |
| *tracefs_event_filter_clear*() clear all filters on _event_ in given _instance_. |
| |
| RETURN VALUE |
| ------------ |
| *tracefs_filter_string_append*() returns 0 on success and -1 on error. |
| |
| *tracefs_filter_string_verify*() returns 0 on success and -1 on error. if there |
| is an error, and _errno_ is not *ENOMEM*, then _err_ is allocated and will |
| contain a string describing what was found wrong with _filter_. _err_ must be |
| freed with *free*(). |
| |
| *tracefs_event_filter_apply*() returns 0 on success and -1 on error. |
| |
| *tracefs_event_filter_clear*() returns 0 on success and -1 on error. |
| |
| EXAMPLE |
| ------- |
| [source,c] |
| -- |
| #include <stdlib.h> |
| #include <stdio.h> |
| #include <ctype.h> |
| #include <tracefs.h> |
| |
| static void usage(char **argv) |
| { |
| fprintf(stderr, "usage: %s [system] event filter\n", argv[0]); |
| exit(-1); |
| } |
| |
| int main (int argc, char **argv) |
| { |
| struct tep_handle *tep; |
| struct tep_event *event; |
| const char *system = NULL; |
| const char *event_name; |
| const char *filter; |
| char *new_filter = NULL; |
| char *err = NULL; |
| int i; |
| |
| if (argc < 3) |
| usage(argv); |
| |
| if (argc < 4) { |
| event_name = argv[1]; |
| filter = argv[2]; |
| } else { |
| system = argv[1]; |
| event_name = argv[2]; |
| filter = argv[3]; |
| } |
| |
| /* Load all events from the system */ |
| tep = tracefs_local_events(NULL); |
| if (!tep) { |
| perror("tep"); |
| exit(-1); |
| } |
| |
| event = tep_find_event_by_name(tep, system, event_name); |
| if (!event) { |
| fprintf(stderr, "Event %s%s%s not found\n", |
| system ? system : "" , system ? " " : "", |
| event_name); |
| exit(-1); |
| } |
| |
| if (tracefs_filter_string_verify(event, filter, &err) < 0) { |
| perror("tracecfs_event_verify_filter"); |
| if (err) |
| fprintf(stderr, "%s", err); |
| free(err); |
| exit(-1); |
| } |
| |
| for (i = 0; filter[i]; i++) { |
| char buf[strlen(filter)]; |
| char *field = NULL; |
| char *val = NULL; |
| enum tracefs_filter type; |
| enum tracefs_compare compare = 0; |
| int start_i, n; |
| int quote; |
| bool backslash; |
| |
| while (isspace(filter[i])) |
| i++; |
| |
| switch(filter[i]) { |
| case '(': |
| type = TRACEFS_FILTER_OPEN_PAREN; |
| break; |
| case ')': |
| type = TRACEFS_FILTER_CLOSE_PAREN; |
| break; |
| case '!': |
| type = TRACEFS_FILTER_NOT; |
| break; |
| case '&': |
| type = TRACEFS_FILTER_AND; |
| i++; |
| break; |
| case '|': |
| type = TRACEFS_FILTER_OR; |
| i++; |
| break; |
| default: |
| type = TRACEFS_FILTER_COMPARE; |
| |
| while (isspace(filter[i])) |
| i++; |
| |
| start_i = i; |
| for (; filter[i]; i++) { |
| switch(filter[i]) { |
| case 'a' ... 'z': |
| case 'A' ... 'Z': |
| case '0' ... '9': |
| case '_': |
| continue; |
| } |
| break; |
| } |
| |
| n = i - start_i; |
| field = buf; |
| strncpy(field, filter + start_i, n); |
| field[n++] = '\0'; |
| |
| val = buf + n; |
| |
| while (isspace(filter[i])) |
| i++; |
| |
| start_i = i; |
| switch(filter[i++]) { |
| case '>': |
| compare = TRACEFS_COMPARE_GT; |
| if (filter[i] == '=') { |
| i++; |
| compare = TRACEFS_COMPARE_GE; |
| } |
| break; |
| case '<': |
| compare = TRACEFS_COMPARE_LT; |
| if (filter[i] == '=') { |
| i++; |
| compare = TRACEFS_COMPARE_LE; |
| } |
| break; |
| case '=': |
| compare = TRACEFS_COMPARE_EQ; |
| i++; |
| break; |
| case '!': |
| compare = TRACEFS_COMPARE_NE; |
| i++; |
| break; |
| case '~': |
| compare = TRACEFS_COMPARE_RE; |
| break; |
| case '&': |
| compare = TRACEFS_COMPARE_AND; |
| break; |
| } |
| |
| while (isspace(filter[i])) |
| i++; |
| |
| quote = 0; |
| backslash = false; |
| start_i = i; |
| for (; filter[i]; i++) { |
| if (quote) { |
| if (backslash) |
| backslash = false; |
| else if (filter[i] == '\\') |
| backslash = true; |
| else if (filter[i] == quote) |
| quote = 0; |
| continue; |
| } |
| switch(filter[i]) { |
| case '"': case '\'': |
| quote = filter[i]; |
| continue; |
| case 'a' ... 'z': |
| case 'A' ... 'Z': |
| case '0' ... '9': |
| case '_': |
| continue; |
| } |
| break; |
| } |
| n = i - start_i; |
| strncpy(val, filter + start_i, n); |
| val[n] = '\0'; |
| break; |
| } |
| n = tracefs_filter_string_append(event, &new_filter, type, |
| field, compare, val); |
| if (n < 0) { |
| fprintf(stderr, "Failed making new filter:\n'%s'\n", |
| new_filter ? new_filter : "(null)"); |
| exit(-1); |
| } |
| } |
| |
| if (tracefs_event_filter_apply(NULL, event, new_filter)) |
| fprintf(stderr, "Failed to apply filter on event"); |
| |
| tep_free(tep); |
| |
| printf("Created new filter: '%s'\n", new_filter); |
| free(new_filter); |
| |
| exit(0); |
| } |
| -- |
| |
| FILES |
| ----- |
| [verse] |
| -- |
| *tracefs.h* |
| Header file to include in order to have access to the library APIs. |
| *-ltracefs* |
| Linker switch to add when building a program that uses the library. |
| -- |
| |
| SEE ALSO |
| -------- |
| *libtracefs*(3), |
| *libtraceevent*(3), |
| *trace-cmd*(1), |
| *tracefs_hist_alloc*(3), |
| *tracefs_hist_alloc_2d*(3), |
| *tracefs_hist_alloc_nd*(3), |
| *tracefs_hist_free*(3), |
| *tracefs_hist_add_key*(3), |
| *tracefs_hist_add_value*(3), |
| *tracefs_hist_add_name*(3), |
| *tracefs_hist_start*(3), |
| *tracefs_hist_destory*(3), |
| *tracefs_hist_add_sort_key*(3), |
| *tracefs_hist_sort_key_direction*(3) |
| |
| AUTHOR |
| ------ |
| [verse] |
| -- |
| *Steven Rostedt* <rostedt@goodmis.org> |
| *Tzvetomir Stoyanov* <tz.stoyanov@gmail.com> |
| *sameeruddin shaik* <sameeruddin.shaik8@gmail.com> |
| -- |
| REPORTING BUGS |
| -------------- |
| Report bugs to <linux-trace-devel@vger.kernel.org> |
| |
| LICENSE |
| ------- |
| libtracefs is Free Software licensed under the GNU LGPL 2.1 |
| |
| RESOURCES |
| --------- |
| https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ |
| |
| COPYING |
| ------- |
| Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under |
| the terms of the GNU Public License (GPL). |
