1LIBTRACEEVENT(3) libtraceevent Manual LIBTRACEEVENT(3)
2
6 libtraceevent - Linux kernel trace event library
7
9 #include <event-parse.h>
10 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_sub_buffer_size(struct tep_handle *tep);
27 int tep_get_header_page_size(struct tep_handle *tep);
28 int tep_get_header_timestamp_size(struct tep_handle *tep);
29 bool tep_is_old_format(struct tep_handle *tep);
30 int tep_strerror(struct tep_handle *tep, enum tep_errno errnum, char *buf, size_t buflen);
31 struct kbuffer *tep_kbuffer(struct tep_handle *:_tep_);
32 Register / unregister APIs:
34 int tep_register_function(struct tep_handle *tep, char *name, unsigned long long addr, char *mod);
35 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);
36 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);
37 int tep_register_print_string(struct tep_handle *tep, const char *fmt, unsigned long long addr);
38 int tep_register_print_function(struct tep_handle *tep, tep_func_handler func, enum tep_func_arg_type ret_type, char *name, ...);
39 int tep_unregister_print_function(struct tep_handle *tep, tep_func_handler func, char *name);
40 int tep_get_function_count(struct tep_handle tep);
41 Trace printk parsing:
43 void *tep_print_printk(struct tep_handle *tep);
44 void tep_print_funcs(struct tep_handle *tep);
45 void tep_set_test_filters(struct tep_handle *tep, int test_filters);
46 void tep_plugin_print_options(struct trace_seq *s);
47 int tep_plugin_add_option(const char *name, const char *val);
48 Meta data parsing:
50 int tep_parse_saved_cmdlines(struct tep_handle *tep, const char *buf);
51 int tep_parse_printk_formats(struct tep_handle *tep, const char *buf);
52 int tep_parse_kallsyms(struct tep_handle *tep, const char *buf);
53 Plugins management:
55 struct tep_plugin_list *tep_load_plugins(struct tep_handle *tep);
56 void tep_unload_plugins(struct tep_plugin_list *plugin_list, struct tep_handle *tep);
57 char **tep_plugin_list_options(void);
58 void tep_plugin_free_options_list(char **list);
59 int tep_plugin_add_options(const char *name, struct tep_plugin_option *options);
60 void tep_plugin_remove_options(struct tep_plugin_option *options);
61 void tep_print_plugins(struct trace_seq *s, const char *prefix, const char *suffix, const struct tep_plugin_list *list);
62 void tep_load_plugins_hook(struct tep_handle *tep, const char *suffix,
63 void (*load_plugin)(struct tep_handle *tep,
64 const char *path,
65 const char *name,
66 void *data),
67 void *data);
68 int tep_add_plugin_path(struct tep_handle *tep, char *path,
69 enum tep_plugin_load_priority prio);
70 Event related APIs:
72 struct tep_event *tep_get_event(struct tep_handle *tep, int index);
73 struct tep_event *tep_get_first_event(struct tep_handle *tep);
74 int tep_get_events_count(struct tep_handle *tep);
75 struct tep_event **tep_list_events(struct tep_handle *tep, enum tep_event_sort_type sort_type);
76 struct tep_event **tep_list_events_copy(struct tep_handle *tep, enum tep_event_sort_type sort_type);
77 void tep_print_event(struct tep_handle *tep, struct trace_seq *s, struct tep_record *record, const char *fmt, ...);
78 Event finding:
80 struct tep_event *tep_find_event(struct tep_handle *tep, int id);
81 struct tep_event *tep_find_event_by_name(struct tep_handle *tep, const char *sys, const char *name);
82 struct tep_event *tep_find_event_by_record(struct tep_handle *tep, struct tep_record *record);
83 Parsing of event files:
85 int tep_parse_header_page(struct tep_handle *tep, char *buf, unsigned long size, int long_size);
86 enum tep_errno tep_parse_event(struct tep_handle *tep, const char *buf, unsigned long size, const char *sys);
87 enum tep_errno tep_parse_format(struct tep_handle *tep, struct tep_event **eventp, const char *buf, unsigned long size, const char *sys);
88 APIs related to fields from event’s format files:
90 struct tep_format_field **tep_event_common_fields(struct tep_event *event);
91 struct tep_format_field **tep_event_fields(struct tep_event *event);
92 void *tep_get_field_raw(struct trace_seq *s, struct tep_event *event, const char *name, struct tep_record *record, int *len, int err);
93 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);
94 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);
95 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);
96 int tep_read_number_field(struct tep_format_field *field, const void *data, unsigned long long *value);
97 Event fields printing:
99 void tep_print_field_content(struct trace_seq *s, void *data, int size, struct tep_format_field *field);
100 void tep_print_fields(struct trace_seq *s, void *data, int size, struct tep_event *event);
101 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);
102 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);
103 void tep_record_print_fields(struct trace_seq *s, struct tep_record *record, struct tep_event *event);
104 void tep_record_print_selected_fields(struct trace_seq *s, struct tep_record *record, struct tep_event *event, int select_mask);
105 Event fields finding:
107 struct tep_format_field *tep_find_common_field(struct tep_event *event, const char *name);
108 struct tep_format_field *tep_find_field(struct tep_event_ormat *event, const char *name);
109 struct tep_format_field *tep_find_any_field(struct tep_event *event, const char *name);
110 Functions resolver:
112 int tep_set_function_resolver(struct tep_handle *tep, tep_func_resolver_t *func, void *priv);
113 void tep_reset_function_resolver(struct tep_handle *tep);
114 const char *tep_find_function(struct tep_handle *tep, unsigned long long addr);
115 unsigned long long tep_find_function_address(struct tep_handle *tep, unsigned long long addr);
116 int tep_find_function_info(struct tep_handle *tep, unsigned long long addr, const char **name,
117 unsigned long long *start, unsigned long *size);
118 Filter management:
120 struct tep_event_filter *tep_filter_alloc(struct tep_handle *tep);
121 enum tep_errno tep_filter_add_filter_str(struct tep_event_filter *filter, const char *filter_str);
122 enum tep_errno tep_filter_match(struct tep_event_filter *filter, struct tep_record *record);
123 int tep_filter_strerror(struct tep_event_filter *filter, enum tep_errno err, char *buf, size_t buflen);
124 int tep_event_filtered(struct tep_event_filter *filter, int event_id);
125 void tep_filter_reset(struct tep_event_filter *filter);
126 void tep_filter_free(struct tep_event_filter *filter);
127 char *tep_filter_make_string(struct tep_event_filter *filter, int event_id);
128 int tep_filter_remove_event(struct tep_event_filter *filter, int event_id);
129 int tep_filter_copy(struct tep_event_filter *dest, struct tep_event_filter *source);
130 int tep_filter_compare(struct tep_event_filter *filter1, struct tep_event_filter *filter2);
131 Parsing various data from the records:
133 int tep_data_type(struct tep_handle *tep, struct tep_record *rec);
134 int tep_data_pid(struct tep_handle *tep, struct tep_record *rec);
135 int tep_data_preempt_count(struct tep_handle *tep, struct tep_record *rec);
136 int tep_data_flags(struct tep_handle *tep, struct tep_record *rec);
137 Command and task related APIs:
139 const char *tep_data_comm_from_pid(struct tep_handle *tep, int pid);
140 struct cmdline *tep_data_pid_from_comm(struct tep_handle *tep, const char *comm, struct cmdline *next);
141 int tep_register_comm(struct tep_handle *tep, const char *comm, int pid);
142 int tep_override_comm(struct tep_handle *tep, const char *comm, int pid);
143 bool tep_is_pid_registered(struct tep_handle *tep, int pid);
144 int tep_cmdline_pid(struct tep_handle *tep, struct cmdline *cmdline);
145 Endian related APIs:
147 int tep_is_bigendian(void);
148 unsigned long long tep_read_number(struct tep_handle *tep, const void *ptr, int size);
149 bool tep_is_file_bigendian(struct tep_handle *tep);
150 void tep_set_file_bigendian(struct tep_handle *tep, enum tep_endian endian);
151 bool tep_is_local_bigendian(struct tep_handle *tep);
152 void tep_set_local_bigendian(struct tep_handle *tep, enum tep_endian endian);
153 Control library logs:
155 int tep_set_loglevel(enum tep_loglevel level);
156 KVM plugin calllbacks: (Defined by the application and complied with -rdynamic)
158 const char *tep_plugin_kvm_get_func(struct tep_event *event,
159 struct tep_record *record,
160 unsigned long long *paddr);
161 void tep_plugin_kvm_put_func(const char *func);
162 Trace sequences:
164 #include <trace-seq.h>
165 void trace_seq_init(struct trace_seq *s);
166 void trace_seq_reset(struct trace_seq *s);
167 void trace_seq_destroy(struct trace_seq *s);
168 int trace_seq_printf(struct trace_seq *s, const char *fmt, ...);
169 int trace_seq_vprintf(struct trace_seq *s, const char *fmt, va_list args);
170 int trace_seq_puts(struct trace_seq *s, const char *str);
171 int trace_seq_putc(struct trace_seq *s, unsigned char c);
172 void trace_seq_terminate(struct trace_seq *s);
173 int trace_seq_do_fprintf(struct trace_seq *s, FILE *fp);
174 int trace_seq_do_printf(struct trace_seq *s);
175 kbuffer parsing:
177 #include <kbuffer.h>
178 struct kbuffer *kbuffer_alloc(enum kbuffer_long_size size, enum kbuffer_endian endian);
179 void kbuffer_free(struct kbuffer *kbuf);
180 int kbuffer_load_subbuffer(struct kbuffer *kbuf, void *subbuffer);
181 int kbuffer_subbuffer_size(struct kbuffer *kbuf);
182 int kbuffer_start_of_data(struct kbuffer *_kbuf);
183 unsigned long long kbuffer_timestamp(struct kbuffer *kbuf);
184 unsigned long long kbuffer_subbuf_timestamp(struct kbuffer *kbuf, void *subbuf);
185 void *kbuffer_read_event(struct kbuffer *kbuf, unsigned long long *ts);
186 void *kbuffer_next_event(struct kbuffer *kbuf, unsigned long long *ts);
187 void *kbuffer_read_at_offset(struct kbuffer *kbuf, int offset, unsigned long long *ts);
188 int kbuffer_missed_events(struct kbuffer *kbuf);
189 int kbuffer_event_size(struct kbuffer *kbuf);
190 int kbuffer_curr_size(struct kbuffer *kbuf);
191 int kbuffer_curr_offset(struct kbuffer *kbuf);
192 int kbuffer_curr_index(struct kbuffer *kbuf);
193
195 The libtraceevent(3) library provides APIs to access kernel tracepoint
196 events, located in the tracefs file system under the events directory.
197
199 TRACEEVENT_PLUGIN_DIR
200 Additional plugin directory. All shared object files, located in this directory will be loaded as traceevent plugins.
201
203 event-parse.h
204 Header file to include in order to have access to the library APIs.
205 trace-seq.h
206 Header file to include in order to have access to trace sequences related APIs.
207 Trace sequences are used to allow a function to call several other functions
208 to create a string of data to use.
209 -ltraceevent
210 Linker switch to add when building a program that uses the library.
211
213 trace-cmd(1)
214
216 Steven Rostedt <rostedt@goodmis.org[1]>, author of libtraceevent.
217 Tzvetomir Stoyanov <tz.stoyanov@gmail.com[2]>, author of this man page.
218
220 Report bugs to <linux-trace-devel@vger.kernel.org[3]>
221
223 libtraceevent is Free Software licensed under the GNU LGPL 2.1
224
226 https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/
227
229 1. rostedt@goodmis.org
230 mailto:rostedt@goodmis.org
231 2. tz.stoyanov@gmail.com
233 mailto:tz.stoyanov@gmail.com
234 3. linux-trace-devel@vger.kernel.org
236 mailto:linux-trace-devel@vger.kernel.org
237libtraceevent 1.7.2 04/05/2023 LIBTRACEEVENT(3)