# tep_register_print_function

## NAME



           tep_register_print_function, tep_unregister_print_function -
           Registers / Unregisters a helper function.
    


## SYNOPSIS



           **#include <event-parse.h>**
    
           enum **tep_func_arg_type**{
                   TEP_FUNC_ARG_VOID,
                   TEP_FUNC_ARG_INT,
                   TEP_FUNC_ARG_LONG,
                   TEP_FUNC_ARG_STRING,
                   TEP_FUNC_ARG_PTR,
                   TEP_FUNC_ARG_MAX_TYPES
           };
    
           typedef unsigned long long (***tep_func_handler**)(struct trace_seq *s, unsigned long long *args);
    
           int **tep_register_print_function**(struct tep_handle *_tep_ , tep_func_handler _func_ , enum tep_func_arg_type _ret_type_ , char *_name_ , _..._);
           int **tep_unregister_print_function**(struct tep_handle *_tep_ , tep_func_handler _func_ , char *_name_);
    


## DESCRIPTION



           Some events may have helper functions in the print format
           arguments. This allows a plugin to dynamically create a way to
           process one of these functions.
    
           The **tep_register_print_function()** registers such helper function.
           The _tep_ argument is the trace event parser context. The _func_
           argument is a pointer to the helper function. The _ret_type_
           argument is the return type of the helper function, value from the
           _tep_func_arg_type_ enum. The _name_ is the name of the helper
           function, as seen in the print format arguments. The _..._ is a
           variable list of _tep_func_arg_type_ enums, the _func_ function
           arguments. This list must end with _TEP_FUNC_ARG_VOID_. See _EXAMPLE_
           section.
    
           The **tep_unregister_print_function()** unregisters a helper function,
           previously registered with **tep_register_print_function()**. The _tep_
           argument is the trace event parser context. The _func_ and _name_
           arguments are the same, used when the helper function was
           registered.
    
           The _tep_func_handler_ is the type of the helper function. The _s_
           argument is the trace sequence, it can be used to create a custom
           string. The _args_ is a list of arguments, defined when the helper
           function was registered.
    


## RETURN VALUE



           The **tep_register_print_function()** function returns 0 in case of
           success. In case of an error, TEP_ERRNO_... code is returned.
    
           The **tep_unregister_print_function()** returns 0 in case of success,
           or -1 in case of an error.
    


## EXAMPLE



           Some events have internal functions calls, that appear in the
           print format output. For example
           "tracefs/events/i915/g4x_wm/format" has:
    
               print fmt: "pipe %c, frame=%u, scanline=%u, wm %d/%d/%d, sr %s/%d/%d/%d, hpll %s/%d/%d/%d, fbc %s",
                           ((REC->pipe) + 'A'), REC->frame, REC->scanline, REC->primary,
                           REC->sprite, REC->cursor, yesno(REC->cxsr), REC->sr_plane,
                           REC->sr_cursor, REC->sr_fbc, yesno(REC->hpll), REC->hpll_plane,
                           REC->hpll_cursor, REC->hpll_fbc, yesno(REC->fbc)
    
           Notice the call to function **yesno()** in the print arguments. In the
           kernel context, this function has the following implementation:
    
               static const char *yesno(int x)
               {
                       static const char *yes = "yes";
                       static const char *no = "no";
    
                       return x ? yes : no;
               }
    
           The user space event parser has no idea how to handle this **yesno()**
           function. The **tep_register_print_function()** API can be used to
           register a user space helper function, mapped to the kernel’s
           **yesno()** :
    
               #include <event-parse.h>
               #include <trace-seq.h>
               ...
               struct tep_handle *tep = tep_alloc();
               ...
               static const char *yes_no_helper(int x)
               {
                       return x ? "yes" : "no";
               }
               ...
                       if ( tep_register_print_function(tep,
                                                   yes_no_helper,
                                                   TEP_FUNC_ARG_STRING,
                                                   "yesno",
                                                   TEP_FUNC_ARG_INT,
                                                   TEP_FUNC_ARG_VOID) != 0) {
                               /* Failed to register yes_no_helper function */
                       }
    
               /*
                  Now, when the event parser encounters this yesno() function, it will know
                  how to handle it.
               */
               ...
                       if (tep_unregister_print_function(tep, yes_no_helper, "yesno") != 0) {
                               /* Failed to unregister yes_no_helper function */
                       }
    


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


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


* * *