'\" t .\" Title: libtraceevent .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 10/13/2024 .\" Manual: libtraceevent Manual .\" Source: libtraceevent .\" Language: English .\" .TH "LIBTRACEEVENT" "3" "10/13/2024" "libtraceevent" "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" libtraceevent \- Linux kernel trace event library .SH "SYNOPSIS" .sp .nf \fB#include \fR Management of tep handler data structure and access of its members: struct tep_handle *\fBtep_alloc\fR(void); void \fBtep_free\fR(struct tep_handle *\fItep\fR); void \fBtep_ref\fR(struct tep_handle *\fItep\fR); void \fBtep_unref\fR(struct tep_handle *\fItep\fR); int \fBtep_get_ref\fR(struct tep_handle *\fItep\fR); void \fBtep_set_flag\fR(struct tep_handle *\fItep\fR, enum tep_flag \fIflag\fR); void \fBtep_clear_flag\fR(struct tep_handle *\fItep\fR, enum tep_flag \fIflag\fR); bool \fBtep_test_flag\fR(struct tep_handle *\fItep\fR, enum tep_flag \fIflags\fR); int \fBtep_get_cpus\fR(struct tep_handle *\fItep\fR); void \fBtep_set_cpus\fR(struct tep_handle *\fItep\fR, int \fIcpus\fR); int \fBtep_get_long_size\fR(strucqt tep_handle *\fItep\fR); void \fBtep_set_long_size\fR(struct tep_handle *\fItep\fR, int \fIlong_size\fR); int \fBtep_get_page_size\fR(struct tep_handle *\fItep\fR); void \fBtep_set_page_size\fR(struct tep_handle *\fItep\fR, int \fIpage_size\fR); int \fBtep_get_sub_buffer_size\fR(struct tep_handle *\fItep\fR); int \fBtep_get_sub_buffer_data_size\fR(struct tep_handle *\fItep\fR); int \fBtep_get_sub_buffer_commit_offset\fR(struct tep_handle *\fItep\fR); int \fBtep_get_header_page_size\fR(struct tep_handle *\fItep\fR); int \fBtep_get_header_timestamp_size\fR(struct tep_handle *\fItep\fR); bool \fBtep_is_old_format\fR(struct tep_handle *\fItep\fR); int \fBtep_strerror\fR(struct tep_handle *\fItep\fR, enum tep_errno \fIerrnum\fR, char *\fIbuf\fR, size_t \fIbuflen\fR); struct kbuffer *\fBtep_kbuffer\fR(struct tep_handle *\fItep\fR); Register / unregister APIs: int \fBtep_register_function\fR(struct tep_handle *\fItep\fR, char *\fIname\fR, unsigned long long \fIaddr\fR, char *\fImod\fR); int \fBtep_register_event_handler\fR(struct tep_handle *\fItep\fR, int \fIid\fR, const char *\fIsys_name\fR, const char *\fIevent_name\fR, tep_event_handler_func \fIfunc\fR, void *\fIcontext\fR); int \fBtep_unregister_event_handler\fR(struct tep_handle *tep, int id, const char *sys_name, const char *event_name, tep_event_handler_func func, void *\fIcontext\fR); int \fBtep_register_print_string\fR(struct tep_handle *\fItep\fR, const char *\fIfmt\fR, unsigned long long \fIaddr\fR); int \fBtep_register_print_function\fR(struct tep_handle *\fItep\fR, tep_func_handler \fIfunc\fR, enum tep_func_arg_type \fIret_type\fR, char *\fIname\fR, \fI\&...\fR); int \fBtep_unregister_print_function\fR(struct tep_handle *\fItep\fR, tep_func_handler \fIfunc\fR, char *\fIname\fR); int \fBtep_get_function_count\fR(struct tep_handle \fB\fItep\fR\fR\fB); Trace printk parsing: void *tep_print_printk\fR(struct tep_handle *tep); void \fBtep_print_funcs\fR(struct tep_handle *tep); void \fBtep_set_test_filters\fR(struct tep_handle *tep, int test_filters); void \fBtep_plugin_print_options\fR(struct trace_seq *s); int \fBtep_plugin_add_option\fR(const char *\fIname\fR, const char *\fIval\fR); Meta data parsing: int \fBtep_parse_saved_cmdlines\fR(struct tep_handle *\fItep\fR, const char *\fIbuf\fR); int \fBtep_parse_printk_formats\fR(struct tep_handle *\fItep\fR, const char *\fIbuf\fR); int \fBtep_parse_kallsyms\fR(struct tep_handle *\fItep\fR, const char *\fIbuf\fR); Plugins management: struct tep_plugin_list *\fBtep_load_plugins\fR(struct tep_handle *\fItep\fR); void \fBtep_unload_plugins\fR(struct tep_plugin_list *\fIplugin_list\fR, struct tep_handle *\fItep\fR); char **\fBtep_plugin_list_options\fR(void); void \fBtep_plugin_free_options_list\fR(char **\fIlist\fR); int \fBtep_plugin_add_options\fR(const char *\fIname\fR, struct tep_plugin_option *\fIoptions\fR); void \fBtep_plugin_remove_options\fR(struct tep_plugin_option *\fIoptions\fR); void \fBtep_print_plugins\fR(struct trace_seq *\fIs\fR, const char *\fIprefix\fR, const char *\fIsuffix\fR, const struct tep_plugin_list *\fIlist\fR); void \fBtep_load_plugins_hook\fR(struct tep_handle *\fItep\fR, const char *\fIsuffix\fR, void (*\fIload_plugin\fR)(struct tep_handle *tep, const char *path, const char *name, void *data), void *\fIdata\fR); int \fBtep_add_plugin_path\fR(struct tep_handle *tep, char *path, enum tep_plugin_load_priority prio); Event related APIs: struct tep_event *\fBtep_get_event\fR(struct tep_handle *\fItep\fR, int \fIindex\fR); struct tep_event *\fBtep_get_first_event\fR(struct tep_handle *\fItep\fR); int \fBtep_get_events_count\fR(struct tep_handle *\fItep\fR); struct tep_event **\fBtep_list_events\fR(struct tep_handle *\fItep\fR, enum tep_event_sort_type \fIsort_type\fR); struct tep_event **\fBtep_list_events_copy\fR(struct tep_handle *\fItep\fR, enum tep_event_sort_type \fIsort_type\fR); void \fBtep_print_event\fR(struct tep_handle *\fItep\fR, struct trace_seq *\fIs\fR, struct tep_record *\fIrecord\fR, const char *\fIfmt\fR, \fI\&...\fR); Event finding: struct tep_event *\fBtep_find_event\fR(struct tep_handle *\fItep\fR, int \fIid\fR); struct tep_event *\fBtep_find_event_by_name\fR(struct tep_handle *\fItep\fR, const char *\fIsys\fR, const char *\fIname\fR); struct tep_event *\fBtep_find_event_by_record\fR(struct tep_handle *\fItep\fR, struct tep_record *\fIrecord\fR); bool \fBtep_record_is_event\fR(struct tep_record *record, struct tep_event *event); Parsing of event files: int \fBtep_parse_header_page\fR(struct tep_handle *\fItep\fR, char *\fIbuf\fR, unsigned long \fIsize\fR, int \fIlong_size\fR); enum tep_errno \fBtep_parse_event\fR(struct tep_handle *\fItep\fR, const char *\fIbuf\fR, unsigned long \fIsize\fR, const char *\fIsys\fR); enum tep_errno \fBtep_parse_format\fR(struct tep_handle *\fItep\fR, struct tep_event **\fIeventp\fR, const char *\fIbuf\fR, unsigned long \fIsize\fR, const char *\fIsys\fR); APIs related to fields from event\(cqs format files: struct tep_format_field **\fBtep_event_common_fields\fR(struct tep_event *\fIevent\fR); struct tep_format_field **\fBtep_event_fields\fR(struct tep_event *\fIevent\fR); void *\fBtep_get_field_raw\fR(struct trace_seq *\fIs\fR, struct tep_event *\fIevent\fR, const char *\fIname\fR, struct tep_record *\fIrecord\fR, int *\fIlen\fR, int \fIerr\fR); int \fBtep_get_field_val\fR(struct trace_seq *\fIs\fR, struct tep_event *\fIevent\fR, const char *\fIname\fR, struct tep_record *\fIrecord\fR, unsigned long long *\fIval\fR, int \fIerr\fR); int \fBtep_get_common_field_val\fR(struct trace_seq *\fIs\fR, struct tep_event *\fIevent\fR, const char *\fIname\fR, struct tep_record *\fIrecord\fR, unsigned long long *\fIval\fR, int \fIerr\fR); int \fBtep_get_any_field_val\fR(struct trace_seq *\fIs\fR, struct tep_event *\fIevent\fR, const char *\fIname\fR, struct tep_record *\fIrecord\fR, unsigned long long *\fIval\fR, int \fIerr\fR); int \fBtep_read_number_field\fR(struct tep_format_field *\fIfield\fR, const void *\fIdata\fR, unsigned long long *\fIvalue\fR); Event fields printing: void \fBtep_print_field_content\fR(struct trace_seq *\fIs\fR, void *\fIdata\fR, int size, struct tep_format_field *\fIfield\fR); void \fBtep_print_fields\fR(struct trace_seq *\fIs\fR, void *\fIdata\fR, int \fIsize\fR, struct tep_event *\fIevent\fR); int \fBtep_print_num_field\fR(struct trace_seq *\fIs\fR, const char *\fIfmt\fR, struct tep_event *\fIevent\fR, const char *\fIname\fR, struct tep_record *\fIrecord\fR, int \fIerr\fR); int \fBtep_print_func_field\fR(struct trace_seq *\fIs\fR, const char *\fIfmt\fR, struct tep_event *\fIevent\fR, const char *\fIname\fR, struct tep_record *\fIrecord\fR, int \fIerr\fR); void \fBtep_record_print_fields\fR(struct trace_seq *\fIs\fR, struct tep_record *\fIrecord\fR, struct tep_event *\fIevent\fR); void \fBtep_record_print_selected_fields\fR(struct trace_seq *\fIs\fR, struct tep_record *\fIrecord\fR, struct tep_event *\fIevent\fR, int \fIselect_mask\fR); Event fields finding: struct tep_format_field *\fBtep_find_common_field\fR(struct tep_event *\fIevent\fR, const char *\fIname\fR); struct tep_format_field *\fBtep_find_field\fR(struct tep_event_ormat *\fIevent\fR, const char *\fIname\fR); struct tep_format_field *\fBtep_find_any_field\fR(struct tep_event *\fIevent\fR, const char *\fIname\fR); Functions resolver: int \fBtep_set_function_resolver\fR(struct tep_handle *\fItep\fR, tep_func_resolver_t *\fIfunc\fR, void *\fIpriv\fR); void \fBtep_reset_function_resolver\fR(struct tep_handle *\fItep\fR); const char *\fBtep_find_function\fR(struct tep_handle *\fItep\fR, unsigned long long \fIaddr\fR); unsigned long long \fBtep_find_function_address\fR(struct tep_handle *\fItep\fR, unsigned long long \fIaddr\fR); int \fBtep_find_function_info\fR(struct tep_handle *\fItep\fR, unsigned long long \fIaddr\fR, const char **\fIname\fR, unsigned long long *\fIstart\fR, unsigned long *\fIsize\fR); Filter management: struct tep_event_filter *\fBtep_filter_alloc\fR(struct tep_handle *\fItep\fR); enum tep_errno \fBtep_filter_add_filter_str\fR(struct tep_event_filter *\fIfilter\fR, const char *\fIfilter_str\fR); enum tep_errno \fBtep_filter_match\fR(struct tep_event_filter *\fIfilter\fR, struct tep_record *\fIrecord\fR); int \fBtep_filter_strerror\fR(struct tep_event_filter *\fIfilter\fR, enum tep_errno \fIerr\fR, char *buf, size_t \fIbuflen\fR); int \fBtep_event_filtered\fR(struct tep_event_filter *\fIfilter\fR, int \fIevent_id\fR); void \fBtep_filter_reset\fR(struct tep_event_filter *\fIfilter\fR); void \fBtep_filter_free\fR(struct tep_event_filter *\fIfilter\fR); char *\fBtep_filter_make_string\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); 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); Parsing various data from the records: int \fBtep_data_type\fR(struct tep_handle *\fItep\fR, struct tep_record *\fIrec\fR); int \fBtep_data_pid\fR(struct tep_handle *\fItep\fR, struct tep_record *\fIrec\fR); int \fBtep_data_preempt_count\fR(struct tep_handle *\fItep\fR, struct tep_record *\fIrec\fR); int \fBtep_data_flags\fR(struct tep_handle *\fItep\fR, struct tep_record *\fIrec\fR); Command and task related APIs: const char *\fBtep_data_comm_from_pid\fR(struct tep_handle *\fItep\fR, int \fIpid\fR); struct cmdline *\fBtep_data_pid_from_comm\fR(struct tep_handle *\fItep\fR, const char *\fIcomm\fR, struct cmdline *\fInext\fR); int \fBtep_register_comm\fR(struct tep_handle *\fItep\fR, const char *\fIcomm\fR, int \fIpid\fR); int \fBtep_override_comm\fR(struct tep_handle *\fItep\fR, const char *\fIcomm\fR, int \fIpid\fR); bool \fBtep_is_pid_registered\fR(struct tep_handle *\fItep\fR, int \fIpid\fR); int \fBtep_cmdline_pid\fR(struct tep_handle *\fItep\fR, struct cmdline *\fIcmdline\fR); Endian related APIs: int \fBtep_is_bigendian\fR(void); unsigned long long \fBtep_read_number\fR(struct tep_handle *\fItep\fR, const void *\fIptr\fR, int \fIsize\fR); bool \fBtep_is_file_bigendian\fR(struct tep_handle *\fItep\fR); void \fBtep_set_file_bigendian\fR(struct tep_handle *\fItep\fR, enum tep_endian \fIendian\fR); bool \fBtep_is_local_bigendian\fR(struct tep_handle *\fItep\fR); void \fBtep_set_local_bigendian\fR(struct tep_handle *\fItep\fR, enum tep_endian \fIendian\fR); Control library logs: int \fBtep_set_loglevel\fR(enum tep_loglevel \fIlevel\fR); KVM plugin calllbacks: (Defined by the application and complied with \-rdynamic) const char *\fBtep_plugin_kvm_get_func\fR(struct tep_event *event, struct tep_record *record, unsigned long long *paddr); void \fBtep_plugin_kvm_put_func\fR(const char *func); Trace sequences: \fB#include \fR void \fBtrace_seq_init\fR(struct trace_seq *\fIs\fR); void \fBtrace_seq_reset\fR(struct trace_seq *\fIs\fR); void \fBtrace_seq_destroy\fR(struct trace_seq *\fIs\fR); int \fBtrace_seq_printf\fR(struct trace_seq *\fIs\fR, const char *\fIfmt\fR, \&...); int \fBtrace_seq_vprintf\fR(struct trace_seq *\fIs\fR, const char *\fIfmt\fR, va_list \fIargs\fR); int \fBtrace_seq_puts\fR(struct trace_seq *\fIs\fR, const char *\fIstr\fR); int \fBtrace_seq_putc\fR(struct trace_seq *\fIs\fR, unsigned char \fIc\fR); void \fBtrace_seq_terminate\fR(struct trace_seq *\fIs\fR); int \fBtrace_seq_do_fprintf\fR(struct trace_seq *\fIs\fR, FILE *\fIfp\fR); int \fBtrace_seq_do_printf\fR(struct trace_seq *\fIs\fR); kbuffer parsing: #include struct kbuffer *\fBkbuffer_alloc\fR(enum kbuffer_long_size \fIsize\fR, enum kbuffer_endian \fIendian\fR); struct kbuffer *\fBkbuffer_dup\fR(struct kbuffer *\fIkbuf\fR); void \fBkbuffer_free\fR(struct kbuffer *\fIkbuf\fR); int \fBkbuffer_load_subbuffer\fR(struct kbuffer *\fIkbuf\fR, void *\fIsubbuffer\fR); int \fBkbuffer_subbuffer_size\fR(struct kbuffer *\fIkbuf); void *\fR\fI\fBkbuffer_subbuffer\fR\fR\fI(struct kbuffer *_kbuf); int \fR\fI\fBkbuffer_refresh\fR\fR\fI(struct kbuffer *_kbuf\fR); int \fBkbuffer_start_of_data\fR(struct kbuffer *\fIkbuf\fR); unsigned long long \fBkbuffer_timestamp\fR(struct kbuffer *\fIkbuf\fR); unsigned long long \fBkbuffer_subbuf_timestamp\fR(struct kbuffer *\fIkbuf\fR, void *\fIsubbuf\fR); void *\fBkbuffer_read_event\fR(struct kbuffer *\fIkbuf\fR, unsigned long long *\fIts\fR); void *\fBkbuffer_next_event\fR(struct kbuffer *\fIkbuf\fR, unsigned long long *\fIts\fR); void *\fBkbuffer_read_at_offset\fR(struct kbuffer *\fIkbuf\fR, int \fIoffset\fR, unsigned long long *\fIts\fR); int \fBkbuffer_missed_events\fR(struct kbuffer *\fIkbuf\fR); int \fBkbuffer_event_size\fR(struct kbuffer *\fIkbuf\fR); int \fBkbuffer_curr_size\fR(struct kbuffer *\fIkbuf\fR); int \fBkbuffer_curr_offset\fR(struct kbuffer *\fIkbuf\fR); int \fBkbuffer_curr_index\fR(struct kbuffer *\fIkbuf\fR); int \fBkbuffer_read_buffer\fR(struct kbuffer *\fIkbuf\fR, void *\fIbuffer\fR, int \fIstart\fR, int \fIlen\fR); .fi .SH "DESCRIPTION" .sp The libtraceevent(3) library provides APIs to access kernel tracepoint events, located in the tracefs file system under the events directory\&. .SH "ENVIRONMENT" .sp .if n \{\ .RS 4 .\} .nf TRACEEVENT_PLUGIN_DIR Additional plugin directory\&. All shared object files, located in this directory will be loaded as traceevent plugins\&. .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\&. \fBtrace\-seq\&.h\fR Header file to include in order to have access to trace sequences related APIs\&. Trace sequences are used to allow a function to call several other functions to create a string of data to use\&. \fB\-ltraceevent\fR Linker switch to add when building a program that uses the library\&. .fi .if n \{\ .RE .\} .SH "SEE ALSO" .sp \fBtrace\-cmd\fR(1) .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