# libtraceevent(3) Manual Page

## 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

## 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 <rostedt@goodmis.org>, author of libtraceevent.
    Tzvetomir Stoyanov <tz.stoyanov@gmail.com>, author of this man page.

## REPORTING BUGS

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

## LICENSE

libtraceevent is Free Software licensed under the GNU LGPL 2.1

## RESOURCES

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