1LIBTRACEEVENT(3)             libtraceevent Manual             LIBTRACEEVENT(3)
2
3
4

NAME

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

SYNOPSIS

10       #include <event-parse.h>
11
12       enum tep_reg_handler {
13               TEP_REGISTER_SUCCESS,
14               TEP_REGISTER_SUCCESS_OVERWRITE,
15       };
16
17       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);
18       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);
19
20       typedef int (*tep_event_handler_func)(struct trace_seq *s, struct tep_record *record, struct tep_event *event, void *context);
21

DESCRIPTION

23       The tep_register_event_handler() function registers a handler function,
24       which is going to be called to parse the information for a given event.
25       The tep argument is the trace event parser context. The id argument is
26       the id of the event. The sys_name argument is the name of the system,
27       the event belongs to. The event_name argument is the name of the event.
28       If id is >= 0, it is used to find the event, otherwise sys_name and
29       event_name are used. The func is a pointer to the function, which is
30       going to be called to parse the event information. The context argument
31       is a pointer to the context data, which will be passed to the func. If
32       a handler function for the same event is already registered, it will be
33       overridden with the new one. This mechanism allows a developer to
34       override the parsing of a given event. If for some reason the default
35       print format is not sufficient, the developer can register a function
36       for an event to be used to parse the data instead.
37
38       The tep_unregister_event_handler() function unregisters the handler
39       function, previously registered with tep_register_event_handler(). The
40       tep argument is the trace event parser context. The id, sys_name,
41       event_name, func, and context are the same arguments, as when the
42       callback function func was registered.
43
44       The tep_event_handler_func is the type of the custom event handler
45       function. The s argument is the trace sequence, it can be used to
46       create a custom string, describing the event. A record to get the event
47       from is passed as input parameter and also the event - the handle to
48       the record’s event. The context is custom context, set when the custom
49       event handler is registered.
50

RETURN VALUE

52       The tep_register_event_handler() function returns TEP_REGISTER_SUCCESS
53       if the new handler is registered successfully or
54       TEP_REGISTER_SUCCESS_OVERWRITE if an existing handler is overwritten.
55       If there is not enough memory to complete the registration,
56       TEP_ERRNO__MEM_ALLOC_FAILED is returned.
57
58       The tep_unregister_event_handler() function returns 0 if func was
59       removed successful or, -1 if the event was not found.
60
61       The tep_event_handler_func should return -1 in case of an error, or 0
62       otherwise.
63

EXAMPLE

65           #include <event-parse.h>
66           #include <trace-seq.h>
67           ...
68           struct tep_handle *tep = tep_alloc();
69           ...
70           int timer_expire_handler(struct trace_seq *s, struct tep_record *record,
71                                    struct tep_event *event, void *context)
72           {
73                   trace_seq_printf(s, "hrtimer=");
74
75                   if (tep_print_num_field(s, "0x%llx", event, "timer", record, 0) == -1)
76                           tep_print_num_field(s, "0x%llx", event, "hrtimer", record, 1);
77
78                   trace_seq_printf(s, " now=");
79
80                   tep_print_num_field(s, "%llu", event, "now", record, 1);
81
82                   tep_print_func_field(s, " function=%s", event, "function", record, 0);
83
84                   return 0;
85           }
86           ...
87                   int ret;
88
89                   ret = tep_register_event_handler(tep, -1, "timer", "hrtimer_expire_entry",
90                                                    timer_expire_handler, NULL);
91                   if (ret < 0) {
92                           char buf[32];
93
94                           tep_strerror(tep, ret, buf, 32)
95                           printf("Failed to register handler for hrtimer_expire_entry: %s\n", buf);
96                   } else {
97                           switch (ret) {
98                           case TEP_REGISTER_SUCCESS:
99                                   printf ("Registered handler for hrtimer_expire_entry\n");
100                                   break;
101                           case TEP_REGISTER_SUCCESS_OVERWRITE:
102                                   printf ("Overwrote handler for hrtimer_expire_entry\n");
103                                   break;
104                           }
105                   }
106           ...
107                   ret = tep_unregister_event_handler(tep, -1, "timer", "hrtimer_expire_entry",
108                                                      timer_expire_handler, NULL);
109                   if ( ret )
110                           printf ("Failed to unregister handler for hrtimer_expire_entry\n");
111

FILES

113           event-parse.h
114                   Header file to include in order to have access to the library APIs.
115           trace-seq.h
116                   Header file to include in order to have access to trace sequences
117                   related APIs. Trace sequences are used to allow a function to call
118                   several other functions to create a string of data to use.
119           -ltraceevent
120                   Linker switch to add when building a program that uses the library.
121

SEE ALSO

123       libtraceevent(3), trace-cmd(1)
124

AUTHOR

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

REPORTING BUGS

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

LICENSE

133       libtraceevent is Free Software licensed under the GNU LGPL 2.1
134

RESOURCES

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

NOTES

139        1. rostedt@goodmis.org
140           mailto:rostedt@goodmis.org
141
142        2. tz.stoyanov@gmail.com
143           mailto:tz.stoyanov@gmail.com
144
145        3. linux-trace-devel@vger.kernel.org
146           mailto:linux-trace-devel@vger.kernel.org
147
148
149
150libtraceevent 1.1.1               02/08/2021                  LIBTRACEEVENT(3)
Impressum