# tep_set_function_resolver

## NAME



           tep_set_function_resolver, tep_reset_function_resolver,
           tep_register_function, tep_register_print_string,
           tep_get_function_count - function related tep APIs
    


## SYNOPSIS



           **#include <event-parse.h>**
    
           typedef char *(**tep_func_resolver_t**)(void *_priv_ , unsigned long long *_addrp_ , char **_modp_);
           int **tep_set_function_resolver**(struct tep_handle *_tep_ , tep_func_resolver_t *_func_ , void *_priv_);
           void **tep_reset_function_resolver**(struct tep_handle *_tep_);
           int **tep_register_function**(struct tep_handle *_tep_ , char *_name_ , unsigned long long _addr_ , char *_mod_);
           int **tep_register_print_string**(struct tep_handle *_tep_ , const char *_fmt_ , unsigned long long _addr_);
           int **tep_get_function_count**(struct tep_handle *_tep_)
    


## DESCRIPTION



           Some tools may have already a way to resolve the kernel functions.
           These APIs allow them to keep using it instead of duplicating all
           the entries inside.
    
           The _tep_func_resolver_t_ type is the prototype of the alternative
           kernel functions resolver. This function receives a pointer to its
           custom context (set with the **tep_set_function_resolver()** call )
           and the address of a kernel function, which has to be resolved. In
           case of success, it should return the name of the function and its
           module (if any) in _modp_.
    
           The **tep_set_function_resolver()** function registers _func_ as an
           alternative kernel functions resolver. The _tep_ argument is trace
           event parser context. The _priv_ argument is a custom context of the
           _func_ function. The function resolver is used by the APIs
           tep_find_function(3), tep_find_function_address(3), and
           **tep_print_func_field()** to resolve a function address to a function
           name.
    
           The **tep_reset_function_resolver()** function resets the kernel
           functions resolver to the default function. The _tep_ argument is
           trace event parser context.
    
           These APIs can be used to find function name and start address, by
           given address. The given address does not have to be exact, it
           will select the function that would contain it.
    
           The **tep_register_function()** function registers a function name
           mapped to an address and (optional) module. This mapping is used
           in case the function tracer or events have "%pS" parameter in its
           format string. It is common to pass in the kallsyms function names
           with their corresponding addresses with this function. The _tep_
           argument is the trace event parser context. The _name_ is the name
           of the function, the string is copied internally. The _addr_ is the
           start address of the function. The _mod_ is the kernel module the
           function may be in (NULL for none).
    
           The **tep_register_print_string()** function registers a string by the
           address it was stored in the kernel. Some strings internal to the
           kernel with static address are passed to certain events. The "%s"
           in the event’s format field which has an address needs to know
           what string would be at that address. The
           tep_register_print_string() supplies the parsing with the mapping
           between kernel addresses and those strings. The _tep_ argument is
           the trace event parser context. The _fmt_ is the string to register,
           it is copied internally. The _addr_ is the address the string was
           located at.
    
           **tep_get_function_count**() returns the number of registered
           functions in a tep handler.
    


## RETURN VALUE



           The **tep_set_function_resolver()** function returns 0 in case of
           success, or -1 in case of an error.
    
           The **tep_register_function()** function returns 0 in case of success.
           In case of an error -1 is returned, and errno is set to the
           appropriate error number.
    
           The **tep_register_print_string()** function returns 0 in case of
           success. In case of an error -1 is returned, and errno is set to
           the appropriate error number.
    


## EXAMPLE



               #include <event-parse.h>
               ...
               struct tep_handle *tep = tep_alloc();
               ...
               char *my_resolve_kernel_addr(void *context,
                                            unsigned long long *addrp, char **modp)
               {
                       struct db *function_database = context;
                       struct symbol *sym = sql_lookup(function_database, *addrp);
    
                       if (!sym)
                               return NULL;
    
                       *modp = sym->module_name;
                       return sym->name;
               }
    
               void show_function( unsigned long long addr)
               {
                       unsigned long long fstart;
                       const char *fname;
    
                       if (tep_set_function_resolver(tep, my_resolve_kernel_addr,
                                                     function_database) != 0) {
                               /* failed to register my_resolve_kernel_addr */
                       }
    
                       /* These APIs use my_resolve_kernel_addr() to resolve the addr */
                       fname = tep_find_function(tep, addr);
                       fstart = tep_find_function_address(tep, addr);
    
                       /*
                          addr is in function named fname, starting at fstart address,
                          at offset (addr - fstart)
                       */
    
                       tep_reset_function_resolver(tep);
    
               }
               ...
                       if (tep_register_function(tep, "kvm_exit",
                                               (unsigned long long) 0x12345678, "kvm") != 0) {
                               /* Failed to register kvm_exit address mapping */
                       }
               ...
                       if (tep_register_print_string(tep, "print string",
                                               (unsigned long long) 0x87654321, NULL) != 0) {
                               /* Failed to register "print string" address mapping */
                       }
               ...
    


## FILES



               **event-parse.h**
                       Header file to include in order to have access to the library APIs.
               **-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
    


* * *