plucky (3) tracefs_list_free.3.gz

NAME

       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

       #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

       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

       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

           #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

           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

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

AUTHOR

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

REPORTING BUGS

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

LICENSE

       libtracefs is Free Software licensed under the GNU LGPL 2.1

RESOURCES

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

COPYING

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

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