tep_register_event_handler(3) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | EXAMPLE | FILES | SEE ALSO | AUTHOR | REPORTING BUGS | LICENSE | RESOURCES | NOTES | COLOPHON

LIBTRACEEVENT(3)          libtraceevent Manual          LIBTRACEEVENT(3)

NAME         top

       tep_register_event_handler, tep_unregister_event_handler -
       Register / unregisters a callback function to parse an event
       information.

SYNOPSIS         top

       #include <event-parse.h>

       enum tep_reg_handler {
               TEP_REGISTER_SUCCESS,
               TEP_REGISTER_SUCCESS_OVERWRITE,
       };

       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);

       typedef int (*tep_event_handler_func)(struct trace_seq *s, struct tep_record *record, struct tep_event *event, void *context);

DESCRIPTION         top

       The tep_register_event_handler() function registers a handler
       function, which is going to be called to parse the information
       for a given event. The tep argument is the trace event parser
       context. The id argument is the id of the event. The sys_name
       argument is the name of the system, the event belongs to. The
       event_name argument is the name of the event. If id is >= 0, it
       is used to find the event, otherwise sys_name and event_name are
       used. The func is a pointer to the function, which is going to be
       called to parse the event information. The context argument is a
       pointer to the context data, which will be passed to the func. If
       a handler function for the same event is already registered, it
       will be overridden with the new one. This mechanism allows a
       developer to override the parsing of a given event. If for some
       reason the default print format is not sufficient, the developer
       can register a function for an event to be used to parse the data
       instead.

       The tep_unregister_event_handler() function unregisters the
       handler function, previously registered with
       tep_register_event_handler(). The tep argument is the trace event
       parser context. The id, sys_name, event_name, func, and context
       are the same arguments, as when the callback function func was
       registered.

       The tep_event_handler_func is the type of the custom event
       handler function. The s argument is the trace sequence, it can be
       used to create a custom string, describing the event. A record to
       get the event from is passed as input parameter and also the
       event - the handle to the record’s event. The context is custom
       context, set when the custom event handler is registered.

RETURN VALUE         top

       The tep_register_event_handler() function returns
       TEP_REGISTER_SUCCESS if the new handler is registered
       successfully or TEP_REGISTER_SUCCESS_OVERWRITE if an existing
       handler is overwritten. If there is not enough memory to complete
       the registration, TEP_ERRNO__MEM_ALLOC_FAILED is returned.

       The tep_unregister_event_handler() function returns 0 if func was
       removed successful or, -1 if the event was not found.

       The tep_event_handler_func should return -1 in case of an error,
       or 0 otherwise.

EXAMPLE         top

           #include <event-parse.h>
           #include <trace-seq.h>
           ...
           struct tep_handle *tep = tep_alloc();
           ...
           int timer_expire_handler(struct trace_seq *s, struct tep_record *record,
                                    struct tep_event *event, void *context)
           {
                   trace_seq_printf(s, "hrtimer=");

                   if (tep_print_num_field(s, "0x%llx", event, "timer", record, 0) == -1)
                           tep_print_num_field(s, "0x%llx", event, "hrtimer", record, 1);

                   trace_seq_printf(s, " now=");

                   tep_print_num_field(s, "%llu", event, "now", record, 1);

                   tep_print_func_field(s, " function=%s", event, "function", record, 0);

                   return 0;
           }
           ...
                   int ret;

                   ret = tep_register_event_handler(tep, -1, "timer", "hrtimer_expire_entry",
                                                    timer_expire_handler, NULL);
                   if (ret < 0) {
                           char buf[32];

                           tep_strerror(tep, ret, buf, 32)
                           printf("Failed to register handler for hrtimer_expire_entry: %s\n", buf);
                   } else {
                           switch (ret) {
                           case TEP_REGISTER_SUCCESS:
                                   printf ("Registered handler for hrtimer_expire_entry\n");
                                   break;
                           case TEP_REGISTER_SUCCESS_OVERWRITE:
                                   printf ("Overwrote handler for hrtimer_expire_entry\n");
                                   break;
                           }
                   }
           ...
                   ret = tep_unregister_event_handler(tep, -1, "timer", "hrtimer_expire_entry",
                                                      timer_expire_handler, NULL);
                   if ( ret )
                           printf ("Failed to unregister handler for hrtimer_expire_entry\n");

FILES         top

           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.

SEE ALSO         top

       libtraceevent(3), trace-cmd(1)

AUTHOR         top

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

REPORTING BUGS         top

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

LICENSE         top

       libtraceevent is Free Software licensed under the GNU LGPL 2.1

RESOURCES         top

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

NOTES         top

        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

COLOPHON         top

       This page is part of the libtraceevent (Linux kernel trace event
       library) project.  Information about the project can be found at
       ⟨https://www.trace-cmd.org/⟩.  If you have a bug report for this
       manual page, see ⟨https://www.trace-cmd.org/⟩.  This page was
       obtained from the project's upstream Git repository
       ⟨https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git⟩
       on 2024-06-14.  (At that time, the date of the most recent commit
       that was found in the repository was 2024-05-17.)  If you
       discover any rendering problems in this HTML version of the page,
       or you believe there is a better or more up-to-date source for
       the page, or you have corrections or improvements to the
       information in this COLOPHON (which is not part of the original
       manual page), send a mail to man-pages@man7.org

libtraceevent 1.7.3            09/24/2023               LIBTRACEEVENT(3)