--- name: "tep_register_event_handler" section: "3" platform: "linux" package: "libtraceevent" version: "1:1.9.1-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/tep_register_event_handler" --- # tep\_register\_event\_handler(3) Register / unregisters a callback function to parse an event information. ## NAME tep\_register\_event\_handler, tep\_unregister\_event\_handler - Register / unregisters a callback function to parse an event information. ## SYNOPSIS ``` #include 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 #include ... 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)](/libtraceevent/3.md), [**trace-cmd**(1)](/trace-cmd/1.md) ## AUTHOR ``` Steven Rostedt , author of libtraceevent. Tzvetomir Stoyanov , author of this man page. ``` ## REPORTING BUGS Report bugs to \<**linux-trace-devel@vger.kernel.org**\[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\. 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