1libtracefs(3) 2============= 3 4NAME 5---- 6tracefs_tracers, tracefs_tracer_available, tracefs_get_clock, tracefs_list_free, 7tracefs_list_add, tracefs_list_size - Helper functions for working with trace file system. 8 9SYNOPSIS 10-------- 11[verse] 12-- 13*#include <tracefs.h>* 14 15char pass:[*]pass:[*]*tracefs_tracers*(const char pass:[*]_tracing_dir_); 16bool *tracefs_tracer_available*(const char pass:[*]_tracing_dir_, const char pass:[*]_tracer_); 17char pass:[*]*tracefs_get_clock*(struct tracefs_instance pass:[*]_instance_); 18void *tracefs_list_free*(char pass:[*]pass:[*]_list_); 19char pass:[**]*tracefs_list_add*(char **_list_, const char *_string_); 20int *tracefs_list_size*(char pass:[**]_list_); 21-- 22 23DESCRIPTION 24----------- 25Various useful functions for working with trace file system. 26 27The *tracefs_tracers()* function returns array of strings with the 28names of supported tracer plugins, located in the given _tracing_dir_ 29directory. This could be NULL or the location of the tracefs mount point 30for the trace systems of the local machine, or it may be a path to a copy 31of the tracefs directory from another machine. The last entry in the array 32as a NULL pointer. The array must be freed with *tracefs_list_free()* API. 33 34The *tracefs_tracer_available()* returns true if the _tracer_ is available 35in the given _tracing_dir_director_, and false otherwise. 36 37The *tracefs_get_clock()* function returns name of the current trace clock, 38used in the given _instance_. If _instance_ is NULL, the clock of the main 39trace instance is returned. The returned string must be freed with free(). 40 41The *tracefs_list_free()* function frees an array of strings, returned by 42*tracefs_event_systems()*, *tracefs_system_events()* and *tracefs_tracers()* 43APIs. 44 45The *tracefs_list_add()* function adds _string_ to the string _list_. If 46_list_ is NULL, then a new list is created with the first element a copy 47of _string_, and the second element will be a NULL pointer. If _list_ is 48not NULL, then it is reallocated to include a new element and a NULL terminator, 49and the new allocated array is returned. The list passed in should be ignored, 50as it wil be freed if a new one was allocated. 51 52The *tracefs_list_size()* is a fast way to find out the number of elements 53in a string array that is to be freed with *tracefs_list_free()*. Note, this 54depends on meta data that is created for these lists and will not work on 55normal string arrays like argv. 56 57RETURN VALUE 58------------ 59The *tracefs_tracers()* returns array of strings. The last element in that 60array is a NULL pointer. The array must be freed with *tracefs_list_free()* API. 61In case of an error, NULL is returned. 62 63The *tracefs_tracer_available()* returns true if the _tracer_ is available, 64and false otherwise. 65 66The *tracefs_get_clock()* returns string, that must be freed with free(), or NULL 67in case of an error. 68 69The *tracefs_list_add()* returns an allocated string array that must be freed 70with *tracefs_list_free()* on success or NULL on error. If NULL is returned, 71then the passed in _list_ is untouched. Thus, *tracefs_list_add()* should be 72treated similarly to *realloc*(3). 73 74The *tracefs_list_size()* returns the number of strings in the _list_. The 75passed in list must be one that is to be freed with *tracefs_list_free()* 76as the list has meta data that is used to determine the size and this does 77not work on any normal string array like argv. 78 79EXAMPLE 80------- 81[source,c] 82-- 83#include <tracefs.h> 84 85char **tracers = tracefs_tracers(NULL); 86 87 if (tracers) { 88 /* Got tracer plugins from the top trace instance */ 89 ... 90 tracefs_list_free(tracers); 91 } 92.... 93char *clock = tracefs_get_clock(NULL); 94 95 if (clock) { 96 /* Got current trace clock of the top trace instance */ 97 ... 98 free(clock); 99 } 100-- 101FILES 102----- 103[verse] 104-- 105*tracefs.h* 106 Header file to include in order to have access to the library APIs. 107*-ltracefs* 108 Linker switch to add when building a program that uses the library. 109-- 110 111SEE ALSO 112-------- 113*libtracefs*(3), 114*libtraceevent*(3), 115*trace-cmd*(1) 116 117AUTHOR 118------ 119[verse] 120-- 121*Steven Rostedt* <[email protected]> 122*Tzvetomir Stoyanov* <[email protected]> 123-- 124REPORTING BUGS 125-------------- 126Report bugs to <[email protected]> 127 128LICENSE 129------- 130libtracefs is Free Software licensed under the GNU LGPL 2.1 131 132RESOURCES 133--------- 134https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ 135 136COPYING 137------- 138Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under 139the terms of the GNU Public License (GPL). 140