libtraceevent(3)

1LIBTRACEEVENT(3)             libtraceevent Manual             LIBTRACEEVENT(3)
2
3
4

NAME

6       libtraceevent - Linux kernel trace event library
7

SYNOPSIS

9       #include <event-parse.h>
10
11       Management of tep handler data structure and access of its members:
12               struct tep_handle *tep_alloc(void);
13               void tep_free(struct tep_handle *tep);
14               void tep_ref(struct tep_handle *tep);
15               void tep_unref(struct tep_handle *tep);
16               int tep_get_ref(struct tep_handle *tep);
17               void tep_set_flag(struct tep_handle *tep, enum tep_flag flag);
18               void tep_clear_flag(struct tep_handle *tep, enum tep_flag flag);
19               bool tep_test_flag(struct tep_handle *tep, enum tep_flag flags);
20               int tep_get_cpus(struct tep_handle *tep);
21               void tep_set_cpus(struct tep_handle *tep, int cpus);
22               int tep_get_long_size(strucqt tep_handle *tep);
23               void tep_set_long_size(struct tep_handle *tep, int long_size);
24               int tep_get_page_size(struct tep_handle *tep);
25               void tep_set_page_size(struct tep_handle *tep, int page_size);
26               int tep_get_header_page_size(struct tep_handle *tep);
27               int tep_get_header_timestamp_size(struct tep_handle *tep);
28               bool tep_is_old_format(struct tep_handle *tep);
29               int tep_strerror(struct tep_handle *tep, enum tep_errno errnum, char *buf, size_t buflen);
30
31       Register / unregister APIs:
32               int tep_register_function(struct tep_handle *tep, char *name, unsigned long long addr, char *mod);
33               int tep_register_event_handler(struct tep_handle *tep, int id, const char *sys_name, const char *event_name, tep_event_handler_func func, void *context);
34               int tep_unregister_event_handler(struct tep_handle *tep, int id, const char *sys_name, const char *event_name, tep_event_handler_func func, void *context);
35               int tep_register_print_string(struct tep_handle *tep, const char *fmt, unsigned long long addr);
36               int tep_register_print_function(struct tep_handle *tep, tep_func_handler func, enum tep_func_arg_type ret_type, char *name, ...);
37               int tep_unregister_print_function(struct tep_handle *tep, tep_func_handler func, char *name);
38
39       Plugins management:
40               struct tep_plugin_list *tep_load_plugins(struct tep_handle *tep);
41               void tep_unload_plugins(struct tep_plugin_list *plugin_list, struct tep_handle *tep);
42               char **tep_plugin_list_options(void);
43               void tep_plugin_free_options_list(char **list);
44               int tep_plugin_add_options(const char *name, struct tep_plugin_option *options);
45               void tep_plugin_remove_options(struct tep_plugin_option *options);
46               void tep_print_plugins(struct trace_seq *s, const char *prefix, const char *suffix, const struct tep_plugin_list *list);
47
48       Event related APIs:
49               struct tep_event *tep_get_event(struct tep_handle *tep, int index);
50               struct tep_event *tep_get_first_event(struct tep_handle *tep);
51               int tep_get_events_count(struct tep_handle *tep);
52               struct tep_event **tep_list_events(struct tep_handle *tep, enum tep_event_sort_type sort_type);
53               struct tep_event **tep_list_events_copy(struct tep_handle *tep, enum tep_event_sort_type sort_type);
54               void tep_print_event(struct tep_handle *tep, struct trace_seq *s, struct tep_record *record, const char *fmt, ...);
55
56       Event finding:
57               struct tep_event *tep_find_event(struct tep_handle *tep, int id);
58               struct tep_event *tep_find_event_by_name(struct tep_handle *tep, const char *sys, const char *name);
59               struct tep_event *tep_find_event_by_record(struct tep_handle *tep, struct tep_record *record);
60
61       Parsing of event files:
62               int tep_parse_header_page(struct tep_handle *tep, char *buf, unsigned long size, int long_size);
63               enum tep_errno tep_parse_event(struct tep_handle *tep, const char *buf, unsigned long size, const char *sys);
64               enum tep_errno tep_parse_format(struct tep_handle *tep, struct tep_event **eventp, const char *buf, unsigned long size, const char *sys);
65
66       APIs related to fields from event’s format files:
67               struct tep_format_field **tep_event_common_fields(struct tep_event *event);
68               struct tep_format_field **tep_event_fields(struct tep_event *event);
69               void *tep_get_field_raw(struct trace_seq *s, struct tep_event *event, const char *name, struct tep_record *record, int *len, int err);
70               int tep_get_field_val(struct trace_seq *s, struct tep_event *event, const char *name, struct tep_record *record, unsigned long long *val, int err);
71               int tep_get_common_field_val(struct trace_seq *s, struct tep_event *event, const char *name, struct tep_record *record, unsigned long long *val, int err);
72               int tep_get_any_field_val(struct trace_seq *s, struct tep_event *event, const char *name, struct tep_record *record, unsigned long long *val, int err);
73               int tep_read_number_field(struct tep_format_field *field, const void *data, unsigned long long *value);
74
75       Event fields printing:
76               void tep_print_field_content(struct trace_seq *s, void *data, int size, struct tep_format_field *field);
77               void tep_print_fields(struct trace_seq *s, void *data, int size, struct tep_event *event);
78               int tep_print_num_field(struct trace_seq *s, const char *fmt, struct tep_event *event, const char *name, struct tep_record *record, int err);
79               int tep_print_func_field(struct trace_seq *s, const char *fmt, struct tep_event *event, const char *name, struct tep_record *record, int err);
80               void tep_record_print_fields(struct trace_seq *s, struct tep_record *record, struct tep_event *event);
81               void tep_record_print_selected_fields(struct trace_seq *s, struct tep_record *record, struct tep_event *event, int select_mask);
82
83       Event fields finding:
84               struct tep_format_field *tep_find_common_field(struct tep_event *event, const char *name);
85               struct tep_format_field *tep_find_field(struct tep_event_ormat *event, const char *name);
86               struct tep_format_field *tep_find_any_field(struct tep_event *event, const char *name);
87
88       Functions resolver:
89               int tep_set_function_resolver(struct tep_handle *tep, tep_func_resolver_t *func, void *priv);
90               void tep_reset_function_resolver(struct tep_handle *tep);
91               const char *tep_find_function(struct tep_handle *tep, unsigned long long addr);
92               unsigned long long tep_find_function_address(struct tep_handle *tep, unsigned long long addr);
93
94       Filter management:
95               struct tep_event_filter *tep_filter_alloc(struct tep_handle *tep);
96               enum tep_errno tep_filter_add_filter_str(struct tep_event_filter *filter, const char *filter_str);
97               enum tep_errno tep_filter_match(struct tep_event_filter *filter, struct tep_record *record);
98               int tep_filter_strerror(struct tep_event_filter *filter, enum tep_errno err, char *buf, size_t buflen);
99               int tep_event_filtered(struct tep_event_filter *filter, int event_id);
100               void tep_filter_reset(struct tep_event_filter *filter);
101               void tep_filter_free(struct tep_event_filter *filter);
102               char *tep_filter_make_string(struct tep_event_filter *filter, int event_id);
103               int tep_filter_remove_event(struct tep_event_filter *filter, int event_id);
104               int tep_filter_copy(struct tep_event_filter *dest, struct tep_event_filter *source);
105               int tep_filter_compare(struct tep_event_filter *filter1, struct tep_event_filter *filter2);
106
107       Parsing various data from the records:
108               int tep_data_type(struct tep_handle *tep, struct tep_record *rec);
109               int tep_data_pid(struct tep_handle *tep, struct tep_record *rec);
110               int tep_data_preempt_count(struct tep_handle *tep, struct tep_record *rec);
111               int tep_data_flags(struct tep_handle *tep, struct tep_record *rec);
112
113       Command and task related APIs:
114               const char *tep_data_comm_from_pid(struct tep_handle *tep, int pid);
115               struct cmdline *tep_data_pid_from_comm(struct tep_handle *tep, const char *comm, struct cmdline *next);
116               int tep_register_comm(struct tep_handle *tep, const char *comm, int pid);
117               int tep_override_comm(struct tep_handle *tep, const char *comm, int pid);
118               bool tep_is_pid_registered(struct tep_handle *tep, int pid);
119               int tep_cmdline_pid(struct tep_handle *tep, struct cmdline *cmdline);
120
121       Endian related APIs:
122               int tep_is_bigendian(void);
123               unsigned long long tep_read_number(struct tep_handle *tep, const void *ptr, int size);
124               bool tep_is_file_bigendian(struct tep_handle *tep);
125               void tep_set_file_bigendian(struct tep_handle *tep, enum tep_endian endian);
126               bool tep_is_local_bigendian(struct tep_handle *tep);
127               void tep_set_local_bigendian(struct tep_handle *tep, enum tep_endian endian);
128
129       Control library logs:
130               int tep_set_loglevel(enum tep_loglevel level);
131
132       Trace sequences:
133       #include <trace-seq.h>
134               void trace_seq_init(struct trace_seq *s);
135               void trace_seq_reset(struct trace_seq *s);
136               void trace_seq_destroy(struct trace_seq *s);
137               int trace_seq_printf(struct trace_seq *s, const char *fmt, ...);
138               int trace_seq_vprintf(struct trace_seq *s, const char *fmt, va_list args);
139               int trace_seq_puts(struct trace_seq *s, const char *str);
140               int trace_seq_putc(struct trace_seq *s, unsigned char c);
141               void trace_seq_terminate(struct trace_seq *s);
142               int trace_seq_do_fprintf(struct trace_seq *s, FILE *fp);
143               int trace_seq_do_printf(struct trace_seq *s);
144

DESCRIPTION

146       The libtraceevent(3) library provides APIs to access kernel tracepoint
147       events, located in the tracefs file system under the events directory.
148

ENVIRONMENT

150           TRACEEVENT_PLUGIN_DIR
151                   Additional plugin directory. All shared object files, located in this directory will be loaded as traceevent plugins.
152

FILES

154           event-parse.h
155                   Header file to include in order to have access to the library APIs.
156           trace-seq.h
157                   Header file to include in order to have access to trace sequences related APIs.
158                   Trace sequences are used to allow a function to call several other functions
159                   to create a string of data to use.
160           -ltraceevent
161                   Linker switch to add when building a program that uses the library.
162

AUTHOR

167           Steven Rostedt <rostedt@goodmis.org[1]>, author of libtraceevent.
168           Tzvetomir Stoyanov <tz.stoyanov@gmail.com[2]>, author of this man page.
169

REPORTING BUGS

171       Report bugs to <linux-trace-devel@vger.kernel.org[3]>
172

LICENSE

174       libtraceevent is Free Software licensed under the GNU LGPL 2.1
175

RESOURCES

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

NOTES

180        1. rostedt@goodmis.org
181           mailto:rostedt@goodmis.org
182
183        2. tz.stoyanov@gmail.com
184           mailto:tz.stoyanov@gmail.com
185
186        3. linux-trace-devel@vger.kernel.org
187           mailto:linux-trace-devel@vger.kernel.org
188
189
190
191libtraceevent 1.5.3               04/15/2022                  LIBTRACEEVENT(3)