tep_register_event_handler(3) — Linux manual page
LIBTRACEEVENT(3) libtraceevent Manual LIBTRACEEVENT(3)
NAME
tep_register_event_handler, tep_unregister_event_handler -
Register / unregisters a callback function to parse an event
information.
SYNOPSIS
#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
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
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
#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
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
libtraceevent(3), trace-cmd(1)
AUTHOR
Steven Rostedt <[email protected][1]>, author of libtraceevent.
Tzvetomir Stoyanov <[email protected][2]>, author of this man page.
REPORTING BUGS
Report bugs to <[email protected][3]>
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. [email protected]
mailto:[email protected]
2. [email protected]
mailto:[email protected]
3. [email protected]
mailto:[email protected]
COLOPHON
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 [email protected]