tools/lib/traceevent/Documentation/libtraceevent-reg_event_handler.txt

   1 libtraceevent(3)
   2 ================
   3
   4 NAME
   5 ----
   6 tep_register_event_handler, tep_unregister_event_handler -  Register /
   7 unregisters a callback function to parse an event information.
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 --
  13 *#include <event-parse.h>*
  14
  15 enum *tep_reg_handler* {
  16         _TEP_REGISTER_SUCCESS_,
  17         _TEP_REGISTER_SUCCESS_OVERWRITE_,
  18 };
  19
  20 int *tep_register_event_handler*(struct tep_handle pass:[*]_tep_, int _id_, const char pass:[*]_sys_name_, const char pass:[*]_event_name_, tep_event_handler_func _func_, void pass:[*]_context_);
  21 int *tep_unregister_event_handler*(struct tep_handle pass:[*]tep, int id, const char pass:[*]sys_name, const char pass:[*]event_name, tep_event_handler_func func, void pass:[*]_context_);
  22
  23 typedef int (*pass:[*]tep_event_handler_func*)(struct trace_seq pass:[*]s, struct tep_record pass:[*]record, struct tep_event pass:[*]event, void pass:[*]context);
  24 --
  25
  26 DESCRIPTION
  27 -----------
  28 The _tep_register_event_handler()_ function registers a handler function,
  29 which is going to be called to parse the information for a given event.
  30 The _tep_ argument is the trace event parser context. The _id_ argument is
  31 the id of the event. The _sys_name_ argument is the name of the system,
  32 the event belongs to. The _event_name_ argument is the name of the event.
  33 If _id_ is >= 0, it is used to find the event, otherwise _sys_name_ and
  34 _event_name_ are used. The _func_ is a pointer to the function, which is going
  35 to be called to parse the event information. The _context_ argument is a pointer
  36 to the context data, which will be passed to the _func_. If a handler function
  37 for the same event is already registered, it will be overridden with the new
  38 one. This mechanism allows a developer to override the parsing of a given event.
  39 If for some reason the default print format is not sufficient, the developer
  40 can register a function for an event to be used to parse the data instead.
  41
  42 The _tep_unregister_event_handler()_ function unregisters the handler function,
  43 previously registered with _tep_register_event_handler()_. The _tep_ argument
  44 is the trace event parser context. The _id_, _sys_name_, _event_name_, _func_,
  45 and _context_ are the same arguments, as when the callback function _func_ was
  46 registered.
  47
  48 The _tep_event_handler_func_ is the type of the custom event handler
  49 function. The _s_ argument is the trace sequence, it can be used to create a
  50 custom string, describing the event. A _record_  to get the event from is passed
  51 as input parameter and also the _event_ - the handle to the record's event. The
  52 _context_ is custom context, set when the custom event handler is registered.
  53
  54 RETURN VALUE
  55 ------------
  56 The _tep_register_event_handler()_ function returns _TEP_REGISTER_SUCCESS_
  57 if the new handler is registered successfully or
  58 _TEP_REGISTER_SUCCESS_OVERWRITE_ if an existing handler is overwritten.
  59 If there is not  enough memory to complete the registration,
  60 TEP_ERRNO__MEM_ALLOC_FAILED is returned.
  61
  62 The _tep_unregister_event_handler()_ function returns 0 if _func_ was removed
  63 successful or, -1 if the event was not found.
  64
  65 The _tep_event_handler_func_ should return -1 in case of an error,
  66 or 0 otherwise.
  67
  68 EXAMPLE
  69 -------
  70 [source,c]
  71 --
  72 #include <event-parse.h>
  73 #include <trace-seq.h>
  74 ...
  75 struct tep_handle *tep = tep_alloc();
  76 ...
  77 int timer_expire_handler(struct trace_seq *s, struct tep_record *record,
  78                          struct tep_event *event, void *context)
  79 {
  80         trace_seq_printf(s, "hrtimer=");
  81
  82         if (tep_print_num_field(s, "0x%llx", event, "timer", record, 0) == -1)
  83                 tep_print_num_field(s, "0x%llx", event, "hrtimer", record, 1);
  84
  85         trace_seq_printf(s, " now=");
  86
  87         tep_print_num_field(s, "%llu", event, "now", record, 1);
  88
  89         tep_print_func_field(s, " function=%s", event, "function", record, 0);
  90
  91         return 0;
  92 }
  93 ...
  94         int ret;
  95
  96         ret = tep_register_event_handler(tep, -1, "timer", "hrtimer_expire_entry",
  97                                          timer_expire_handler, NULL);
  98         if (ret < 0) {
  99                 char buf[32];
 100
 101                 tep_strerror(tep, ret, buf, 32)
 102                 printf("Failed to register handler for hrtimer_expire_entry: %s\n", buf);
 103         } else {
 104                 switch (ret) {
 105                 case TEP_REGISTER_SUCCESS:
 106                         printf ("Registered handler for hrtimer_expire_entry\n");
 107                         break;
 108                 case TEP_REGISTER_SUCCESS_OVERWRITE:
 109                         printf ("Overwrote handler for hrtimer_expire_entry\n");
 110                         break;
 111                 }
 112         }
 113 ...
 114         ret = tep_unregister_event_handler(tep, -1, "timer", "hrtimer_expire_entry",
 115                                            timer_expire_handler, NULL);
 116         if ( ret )
 117                 printf ("Failed to unregister handler for hrtimer_expire_entry\n");
 118
 119 --
 120
 121 FILES
 122 -----
 123 [verse]
 124 --
 125 *event-parse.h*
 126         Header file to include in order to have access to the library APIs.
 127 *trace-seq.h*
 128         Header file to include in order to have access to trace sequences
 129         related APIs. Trace sequences are used to allow a function to call
 130         several other functions to create a string of data to use.
 131 *-ltraceevent*
 132         Linker switch to add when building a program that uses the library.
 133 --
 134
 135 SEE ALSO
 136 --------
 137 _libtraceevent(3)_, _trace-cmd(1)_
 138
 139 AUTHOR
 140 ------
 141 [verse]
 142 --
 143 *Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
 144 *Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
 145 --
 146 REPORTING BUGS
 147 --------------
 148 Report bugs to  <linux-trace-devel@vger.kernel.org>
 149
 150 LICENSE
 151 -------
 152 libtraceevent is Free Software licensed under the GNU LGPL 2.1
 153
 154 RESOURCES
 155 ---------
 156 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git