tep_set_function_resolver(3) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | EXAMPLE | FILES | SEE ALSO | AUTHOR | REPORTING BUGS | LICENSE | RESOURCES | NOTES | COLOPHON

LIBTRACEEVENT(3)          libtraceevent Manual          LIBTRACEEVENT(3)

NAME         top

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

SYNOPSIS         top

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

       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         top

       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         top

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

           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.

SEE ALSO         top

       libtraceevent(3), trace-cmd(1)

AUTHOR         top

           Steven Rostedt <[email protected][1]>, author of libtraceevent.
           Tzvetomir Stoyanov <[email protected][2]>, author of this man page.

REPORTING BUGS         top

       Report bugs to <[email protected][3]>

LICENSE         top

       libtraceevent is Free Software licensed under the GNU LGPL 2.1

RESOURCES         top

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

NOTES         top

        1. [email protected]
           mailto:[email protected]

        2. [email protected]
           mailto:[email protected]

        3. [email protected]
           mailto:[email protected]

COLOPHON         top

       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]

libtraceevent 1.7.3            09/24/2023               LIBTRACEEVENT(3)

Pages that refer to this page: tep_parse_saved_cmdlines(3)