# libtraceevent

## NAME



           libtraceevent - Linux kernel trace event library
    


## SYNOPSIS



           **#include <event-parse.h>**
    
           Management of tep handler data structure and access of its members:
                   struct tep_handle * **tep_alloc**(void);
                   void **tep_free**(struct tep_handle *_tep_);
                   void **tep_ref**(struct tep_handle *_tep_);
                   void **tep_unref**(struct tep_handle *_tep_);
                   int **tep_get_ref**(struct tep_handle *_tep_);
                   void **tep_set_flag**(struct tep_handle *_tep_ , enum tep_flag _flag_);
                   void **tep_clear_flag**(struct tep_handle *_tep_ , enum tep_flag _flag_);
                   bool **tep_test_flag**(struct tep_handle *_tep_ , enum tep_flag _flags_);
                   int **tep_get_cpus**(struct tep_handle *_tep_);
                   void **tep_set_cpus**(struct tep_handle *_tep_ , int _cpus_);
                   int **tep_get_long_size**(strucqt tep_handle *_tep_);
                   void **tep_set_long_size**(struct tep_handle *_tep_ , int _long_size_);
                   int **tep_get_page_size**(struct tep_handle *_tep_);
                   void **tep_set_page_size**(struct tep_handle *_tep_ , int _page_size_);
                   int **tep_get_sub_buffer_size**(struct tep_handle *_tep_);
                   int **tep_get_sub_buffer_data_size**(struct tep_handle *_tep_);
                   int **tep_get_sub_buffer_commit_offset**(struct tep_handle *_tep_);
                   int **tep_get_header_page_size**(struct tep_handle *_tep_);
                   int **tep_get_header_timestamp_size**(struct tep_handle *_tep_);
                   bool **tep_is_old_format**(struct tep_handle *_tep_);
                   int **tep_strerror**(struct tep_handle *_tep_ , enum tep_errno _errnum_ , char *_buf_ , size_t _buflen_);
                   struct kbuffer * **tep_kbuffer**(struct tep_handle *_tep_);
    
           Register / unregister APIs:
                   int **tep_register_function**(struct tep_handle *_tep_ , char *_name_ , unsigned long long _addr_ , char *_mod_);
                   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_);
                   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_);
                   int **tep_register_print_string**(struct tep_handle *_tep_ , const char *_fmt_ , unsigned long long _addr_);
                   int **tep_register_print_function**(struct tep_handle *_tep_ , tep_func_handler _func_ , enum tep_func_arg_type _ret_type_ , char *_name_ , _..._);
                   int **tep_unregister_print_function**(struct tep_handle *_tep_ , tep_func_handler _func_ , char *_name_);
                   int **tep_get_function_count**(struct tep_handle _tep_**);**
    
           **Trace printk parsing:**
                   **void *tep_print_printk**(struct tep_handle *tep);
                   void **tep_print_funcs**(struct tep_handle *tep);
                   void **tep_set_test_filters**(struct tep_handle *tep, int test_filters);
                   void **tep_plugin_print_options**(struct trace_seq *s);
                   int **tep_plugin_add_option**(const char *_name_ , const char *_val_);
    
           Meta data parsing:
                   int **tep_parse_saved_cmdlines**(struct tep_handle *_tep_ , const char *_buf_);
                   int **tep_parse_printk_formats**(struct tep_handle *_tep_ , const char *_buf_);
                   int **tep_parse_kallsyms**(struct tep_handle *_tep_ , const char *_buf_);
    
           Plugins management:
                   struct tep_plugin_list * **tep_load_plugins**(struct tep_handle *_tep_);
                   void **tep_unload_plugins**(struct tep_plugin_list *_plugin_list_ , struct tep_handle *_tep_);
                   char ** **tep_plugin_list_options**(void);
                   void **tep_plugin_free_options_list**(char **_list_);
                   int **tep_plugin_add_options**(const char *_name_ , struct tep_plugin_option *_options_);
                   void **tep_plugin_remove_options**(struct tep_plugin_option *_options_);
                   void **tep_print_plugins**(struct trace_seq *_s_ , const char *_prefix_ , const char *_suffix_ , const struct tep_plugin_list *_list_);
                   void **tep_load_plugins_hook**(struct tep_handle *_tep_ , const char *_suffix_ ,
                                      void (*_load_plugin_)(struct tep_handle *tep,
                                                          const char *path,
                                                          const char *name,
                                                          void *data),
                                      void *_data_);
                   int **tep_add_plugin_path**(struct tep_handle *tep, char *path,
                                     enum tep_plugin_load_priority prio);
    
           Event related APIs:
                   struct tep_event * **tep_get_event**(struct tep_handle *_tep_ , int _index_);
                   struct tep_event * **tep_get_first_event**(struct tep_handle *_tep_);
                   int **tep_get_events_count**(struct tep_handle *_tep_);
                   struct tep_event ** **tep_list_events**(struct tep_handle *_tep_ , enum tep_event_sort_type _sort_type_);
                   struct tep_event ** **tep_list_events_copy**(struct tep_handle *_tep_ , enum tep_event_sort_type _sort_type_);
                   void **tep_print_event**(struct tep_handle *_tep_ , struct trace_seq *_s_ , struct tep_record *_record_ , const char *_fmt_ , _..._);
    
           Event finding:
                   struct tep_event * **tep_find_event**(struct tep_handle *_tep_ , int _id_);
                   struct tep_event * **tep_find_event_by_name**(struct tep_handle *_tep_ , const char *_sys_ , const char *_name_);
                   struct tep_event * **tep_find_event_by_record**(struct tep_handle *_tep_ , struct tep_record *_record_);
                   bool **tep_record_is_event**(struct tep_record *record, struct tep_event *event);
    
           Parsing of event files:
                   int **tep_parse_header_page**(struct tep_handle *_tep_ , char *_buf_ , unsigned long _size_ , int _long_size_);
                   enum tep_errno **tep_parse_event**(struct tep_handle *_tep_ , const char *_buf_ , unsigned long _size_ , const char *_sys_);
                   enum tep_errno **tep_parse_format**(struct tep_handle *_tep_ , struct tep_event **_eventp_ , const char *_buf_ , unsigned long _size_ , const char *_sys_);
    
           APIs related to fields from event’s format files:
                   struct tep_format_field ** **tep_event_common_fields**(struct tep_event *_event_);
                   struct tep_format_field ** **tep_event_fields**(struct tep_event *_event_);
                   void * **tep_get_field_raw**(struct trace_seq *_s_ , struct tep_event *_event_ , const char *_name_ , struct tep_record *_record_ , int *_len_ , int _err_);
                   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_);
                   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_);
                   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_);
                   int **tep_read_number_field**(struct tep_format_field *_field_ , const void *_data_ , unsigned long long *_value_);
    
           Event fields printing:
                   void **tep_print_field_content**(struct trace_seq *_s_ , void *_data_ , int size, struct tep_format_field *_field_);
                   void **tep_print_fields**(struct trace_seq *_s_ , void *_data_ , int _size_ , struct tep_event *_event_);
                   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_);
                   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_);
                   void **tep_record_print_fields**(struct trace_seq *_s_ , struct tep_record *_record_ , struct tep_event *_event_);
                   void **tep_record_print_selected_fields**(struct trace_seq *_s_ , struct tep_record *_record_ , struct tep_event *_event_ , int _select_mask_);
    
           Event fields finding:
                   struct tep_format_field * **tep_find_common_field**(struct tep_event *_event_ , const char *_name_);
                   struct tep_format_field * **tep_find_field**(struct tep_event_ormat *_event_ , const char *_name_);
                   struct tep_format_field * **tep_find_any_field**(struct tep_event *_event_ , const char *_name_);
    
           Functions resolver:
                   int **tep_set_function_resolver**(struct tep_handle *_tep_ , tep_func_resolver_t *_func_ , void *_priv_);
                   void **tep_reset_function_resolver**(struct tep_handle *_tep_);
                   const char * **tep_find_function**(struct tep_handle *_tep_ , unsigned long long _addr_);
                   unsigned long long **tep_find_function_address**(struct tep_handle *_tep_ , unsigned long long _addr_);
                   int **tep_find_function_info**(struct tep_handle *_tep_ , unsigned long long _addr_ , const char **_name_ ,
                                      unsigned long long *_start_ , unsigned long *_size_);
    
           Filter management:
                   struct tep_event_filter * **tep_filter_alloc**(struct tep_handle *_tep_);
                   enum tep_errno **tep_filter_add_filter_str**(struct tep_event_filter *_filter_ , const char *_filter_str_);
                   enum tep_errno **tep_filter_match**(struct tep_event_filter *_filter_ , struct tep_record *_record_);
                   int **tep_filter_strerror**(struct tep_event_filter *_filter_ , enum tep_errno _err_ , char *buf, size_t _buflen_);
                   int **tep_event_filtered**(struct tep_event_filter *_filter_ , int _event_id_);
                   void **tep_filter_reset**(struct tep_event_filter *_filter_);
                   void **tep_filter_free**(struct tep_event_filter *_filter_);
                   char * **tep_filter_make_string**(struct tep_event_filter *_filter_ , int _event_id_);
                   int **tep_filter_remove_event**(struct tep_event_filter *_filter_ , int _event_id_);
                   int **tep_filter_copy**(struct tep_event_filter *_dest_ , struct tep_event_filter *_source_);
                   int **tep_filter_compare**(struct tep_event_filter *_filter1_ , struct tep_event_filter *_filter2_);
    
           Parsing various data from the records:
                   int **tep_data_type**(struct tep_handle *_tep_ , struct tep_record *_rec_);
                   int **tep_data_pid**(struct tep_handle *_tep_ , struct tep_record *_rec_);
                   int **tep_data_preempt_count**(struct tep_handle *_tep_ , struct tep_record *_rec_);
                   int **tep_data_flags**(struct tep_handle *_tep_ , struct tep_record *_rec_);
    
           Command and task related APIs:
                   const char * **tep_data_comm_from_pid**(struct tep_handle *_tep_ , int _pid_);
                   struct cmdline * **tep_data_pid_from_comm**(struct tep_handle *_tep_ , const char *_comm_ , struct cmdline *_next_);
                   int **tep_register_comm**(struct tep_handle *_tep_ , const char *_comm_ , int _pid_);
                   int **tep_override_comm**(struct tep_handle *_tep_ , const char *_comm_ , int _pid_);
                   bool **tep_is_pid_registered**(struct tep_handle *_tep_ , int _pid_);
                   int **tep_cmdline_pid**(struct tep_handle *_tep_ , struct cmdline *_cmdline_);
    
           Endian related APIs:
                   int **tep_is_bigendian**(void);
                   unsigned long long **tep_read_number**(struct tep_handle *_tep_ , const void *_ptr_ , int _size_);
                   bool **tep_is_file_bigendian**(struct tep_handle *_tep_);
                   void **tep_set_file_bigendian**(struct tep_handle *_tep_ , enum tep_endian _endian_);
                   bool **tep_is_local_bigendian**(struct tep_handle *_tep_);
                   void **tep_set_local_bigendian**(struct tep_handle *_tep_ , enum tep_endian _endian_);
    
           Control library logs:
                   int **tep_set_loglevel**(enum tep_loglevel _level_);
    
           KVM plugin calllbacks: (Defined by the application and complied with -rdynamic)
                   const char * **tep_plugin_kvm_get_func**(struct tep_event *event,
                                               struct tep_record *record,
                                               unsigned long long *paddr);
                   void **tep_plugin_kvm_put_func**(const char *func);
    
           Trace sequences:
           **#include <trace-seq.h>**
                   void **trace_seq_init**(struct trace_seq *_s_);
                   void **trace_seq_reset**(struct trace_seq *_s_);
                   void **trace_seq_destroy**(struct trace_seq *_s_);
                   int **trace_seq_printf**(struct trace_seq *_s_ , const char *_fmt_ , ...);
                   int **trace_seq_vprintf**(struct trace_seq *_s_ , const char *_fmt_ , va_list _args_);
                   int **trace_seq_puts**(struct trace_seq *_s_ , const char *_str_);
                   int **trace_seq_putc**(struct trace_seq *_s_ , unsigned char _c_);
                   void **trace_seq_terminate**(struct trace_seq *_s_);
                   int **trace_seq_do_fprintf**(struct trace_seq *_s_ , FILE *_fp_);
                   int **trace_seq_do_printf**(struct trace_seq *_s_);
    
           kbuffer parsing:
           #include <kbuffer.h>
                   struct kbuffer * **kbuffer_alloc**(enum kbuffer_long_size _size_ , enum kbuffer_endian _endian_);
                   struct kbuffer * **kbuffer_dup**(struct kbuffer *_kbuf_);
                   void **kbuffer_free**(struct kbuffer *_kbuf_);
                   int **kbuffer_load_subbuffer**(struct kbuffer *_kbuf_ , void *_subbuffer_);
                   int **kbuffer_subbuffer_size**(struct kbuffer *_kbuf);_
                   _void *_ **kbuffer_subbuffer** _(struct kbuffer *_kbuf);_
                   _int_ **kbuffer_refresh** _(struct kbuffer *_kbuf_);
                   int **kbuffer_start_of_data**(struct kbuffer *_kbuf_);
                   unsigned long long **kbuffer_timestamp**(struct kbuffer *_kbuf_);
                   unsigned long long **kbuffer_subbuf_timestamp**(struct kbuffer *_kbuf_ , void *_subbuf_);
                   void * **kbuffer_read_event**(struct kbuffer *_kbuf_ , unsigned long long *_ts_);
                   void * **kbuffer_next_event**(struct kbuffer *_kbuf_ , unsigned long long *_ts_);
                   void * **kbuffer_read_at_offset**(struct kbuffer *_kbuf_ , int _offset_ , unsigned long long *_ts_);
                   int **kbuffer_missed_events**(struct kbuffer *_kbuf_);
                   int **kbuffer_event_size**(struct kbuffer *_kbuf_);
                   int **kbuffer_curr_size**(struct kbuffer *_kbuf_);
                   int **kbuffer_curr_offset**(struct kbuffer *_kbuf_);
                   int **kbuffer_curr_index**(struct kbuffer *_kbuf_);
                   int **kbuffer_read_buffer**(struct kbuffer *_kbuf_ , void *_buffer_ , int _start_ , int _len_);
    


## DESCRIPTION



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


## ENVIRONMENT



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


## FILES



               **event-parse.h**
                       Header file to include in order to have access to the library APIs.
               **trace-seq.h**
                       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.
               **-ltraceevent**
                       Linker switch to add when building a program that uses the library.
    


## LICENSE



           libtraceevent is Free Software licensed under the GNU LGPL 2.1
    


## RESOURCES



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


## NOTES



            1. rostedt@goodmis.org
               mailto:rostedt@goodmis.org
    
            2. tz.stoyanov@gmail.com
               mailto:tz.stoyanov@gmail.com
    
            3. linux-trace-devel@vger.kernel.org
               mailto:linux-trace-devel@vger.kernel.org
    


* * *