tracefs_tracers(3) — Linux manual page

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

LIBTRACEFS(3)               libtracefs Manual              LIBTRACEFS(3)

NAME         top

       tracefs_tracers, tracefs_tracer_available, tracefs_get_clock,
       tracefs_list_free, tracefs_list_add, tracefs_list_size - Helper
       functions for working with trace file system.

SYNOPSIS         top

       #include <tracefs.h>

       char **tracefs_tracers(const char *tracing_dir);
       bool tracefs_tracer_available(const char *tracing_dir, const char *tracer);
       char *tracefs_get_clock(struct tracefs_instance *instance);
       void tracefs_list_free(char **list);
       char **tracefs_list_add(char *list, const char *string);
       int *tracefs_list_size(char **list);

DESCRIPTION         top

       Various useful functions for working with trace file system.

       The tracefs_tracers() function returns array of strings with the
       names of supported tracer plugins, located in the given
       tracing_dir directory. This could be NULL or the location of the
       tracefs mount point for the trace systems of the local machine,
       or it may be a path to a copy of the tracefs directory from
       another machine. The last entry in the array as a NULL pointer.
       The array must be freed with tracefs_list_free() API.

       The tracefs_tracer_available() returns true if the tracer is
       available in the given tracing_dir_director, and false otherwise.

       The tracefs_get_clock() function returns name of the current
       trace clock, used in the given instance. If instance is NULL, the
       clock of the main trace instance is returned. The returned string
       must be freed with free().

       The tracefs_list_free() function frees an array of strings,
       returned by tracefs_event_systems(), tracefs_system_events() and
       tracefs_tracers() APIs.

       The tracefs_list_add() function adds string to the string list.
       If list is NULL, then a new list is created with the first
       element a copy of string, and the second element will be a NULL
       pointer. If list is not NULL, then it is reallocated to include a
       new element and a NULL terminator, and the new allocated array is
       returned. The list passed in should be ignored, as it wil be
       freed if a new one was allocated.

       The tracefs_list_size() is a fast way to find out the number of
       elements in a string array that is to be freed with
       tracefs_list_free(). Note, this depends on meta data that is
       created for these lists and will not work on normal string arrays
       like argv.

RETURN VALUE         top

       The tracefs_tracers() returns array of strings. The last element
       in that array is a NULL pointer. The array must be freed with
       tracefs_list_free() API. In case of an error, NULL is returned.

       The tracefs_tracer_available() returns true if the tracer is
       available, and false otherwise.

       The tracefs_get_clock() returns string, that must be freed with
       free(), or NULL in case of an error.

       The tracefs_list_add() returns an allocated string array that
       must be freed with tracefs_list_free() on success or NULL on
       error. If NULL is returned, then the passed in list is untouched.
       Thus, tracefs_list_add() should be treated similarly to
       realloc(3).

       The tracefs_list_size() returns the number of strings in the
       list. The passed in list must be one that is to be freed with
       tracefs_list_free() as the list has meta data that is used to
       determine the size and this does not work on any normal string
       array like argv.

EXAMPLE         top

           #include <tracefs.h>

           char **tracers = tracefs_tracers(NULL);

                   if (tracers) {
                           /* Got tracer plugins from the top trace instance */
                           ...
                           tracefs_list_free(tracers);
                   }
           ....
           char *clock = tracefs_get_clock(NULL);

                   if (clock) {
                           /* Got current trace clock of the top trace instance */
                           ...
                           free(clock);
                   }

FILES         top

           tracefs.h
                   Header file to include in order to have access to the library APIs.
           -ltracefs
                   Linker switch to add when building a program that uses the library.

SEE ALSO         top

       libtracefs(3), libtraceevent(3), trace-cmd(1)

AUTHOR         top

           Steven Rostedt <rostedt@goodmis.org[1]>
           Tzvetomir Stoyanov <tz.stoyanov@gmail.com[2]>

REPORTING BUGS         top

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

LICENSE         top

       libtracefs is Free Software licensed under the GNU LGPL 2.1

RESOURCES         top

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

COPYING         top

       Copyright (C) 2020 VMware, Inc. Free use of this software is
       granted under the terms of the GNU Public License (GPL).

NOTES         top

        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

COLOPHON         top

       This page is part of the libtracefs (Linux kernel trace file
       system 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/libtracefs.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 man-pages@man7.org

libtracefs 1.7.0               12/22/2023                  LIBTRACEFS(3)

Pages that refer to this page: tracefs_instance_create(3)