1libtracefs(3) 2============= 3 4NAME 5---- 6tracefs_instance_get_name, tracefs_instance_get_trace_dir, tracefs_instances_walk, tracefs_instance_exists, 7tracefs_instance_get_buffer_size, tracefs_instance_set_buffer_size - Helper functions for working with tracing instances. 8 9SYNOPSIS 10-------- 11[verse] 12-- 13*#include <tracefs.h>* 14 15const char pass:[*]*tracefs_instance_get_name*(struct tracefs_instance pass:[*]_instance_); 16const char pass:[*]*tracefs_instance_get_trace_dir*(struct tracefs_instance pass:[*]_instance_); 17int *tracefs_instances_walk*(int (pass:[*]_callback_)(const char pass:[*], void pass:[*]), void pass:[*]_context)_; 18bool *tracefs_instance_exists*(const char pass:[*]_name_); 19size_t *tracefs_instance_get_buffer_size*(struct tracefs_instance pass:[*]_instance_, int _cpu_); 20int *tracefs_instance_set_buffer_size*(struct tracefs_instance pass:[*]_instance_, size_t _size_, int _cpu_); 21-- 22 23DESCRIPTION 24----------- 25Helper functions for working with trace instances. 26 27The *tracefs_instance_get_name()* function returns the name of the given _instance_. 28Note that the top instance has no name, the function returns NULL for it. 29 30The *tracefs_instance_get_trace_dir()* function returns the tracing directory, where 31the given _instance_ is configured. 32 33The *tracefs_instances_walk()* function walks through all configured tracing 34instances in the system and calls _callback_ for each one of them. The _context_ 35argument is passed to the _callback_, together with the instance name. If the 36_callback_ returns non-zero, the iteration stops. Note, the _callback_ is not 37called for the top top instance. 38 39The *tracefs_instance_exists()* function checks if an instance with the given 40_name_ exists in the system. 41 42The *tracefs_instace_get_buffer_size()* returns the size of the ring buffer. If _cpu_ 43is negative, it returns the total size of all the per CPU ring buffers, otherwise 44it returns the size of the per CPU ring buffer for _cpu_. 45 46The *tracefs_instance_set_buffer_size()* function sets the size of the ring buffer. 47If _cpu_ is negative, then it sets all the per CPU ring buffers to _size_ (note 48the total size is the number of CPUs * _size_). If _cpu_ is specified, then it only 49sets the size of the per CPU ring buffer. 50 51RETURN VALUE 52------------ 53The *tracefs_instance_get_name()* returns a string or NULL in case of the top 54instance. The returned string must _not_ be freed. 55 56The *tracefs_instance_get_trace_dir()* returns a string or NULL in case of an error. 57The returned string must _not_ be freed. 58 59The *tracefs_instances_walk()* function returns 0, if all instances were iterated, 1 60if the iteration was stopped by the _callback_, or -1 in case of an error. 61 62The *tracefs_instance_exists()* returns true if an instance with the given _name_ 63exists in the system or false otherwise. 64 65The *tracefs_instance_get_buffer_size()* returns the size of the ring buffer depending on 66the _cpu_ value passed in, or -1 on error. 67 68The *tracefs_instance_set_buffer_size()* returns zero on success and -1 on error. 69 70EXAMPLE 71------- 72[source,c] 73-- 74#include <tracefs.h> 75 76struct tracefs_instance *inst; 77.... 78char *name = tracefs_instance_get_name(inst); 79 if(name) { 80 /* Got name of the instance */ 81 } 82char *dir = tracefs_instance_get_trace_dir(inst); 83 if(dir) { 84 /* Got tracing directory of the instance */ 85 } 86... 87static int instance_walk(char *name, void *context) 88{ 89 /* Got instance with name */ 90 return 0; 91} 92... 93 if (tracefs_instances_walk(instance_walk, NULL) < 0) { 94 /* Error walking through the instances */ 95 } 96... 97 if (tracefs_instance_exists("foo")) { 98 /* There is instance with name foo in the system */ 99 } else { 100 /* There is no instance with name foo in the system */ 101 } 102-- 103FILES 104----- 105[verse] 106-- 107*tracefs.h* 108 Header file to include in order to have access to the library APIs. 109*-ltracefs* 110 Linker switch to add when building a program that uses the library. 111-- 112 113SEE ALSO 114-------- 115*libtracefs*(3), 116*libtraceevent*(3), 117*trace-cmd*(1) 118 119AUTHOR 120------ 121[verse] 122-- 123*Steven Rostedt* <[email protected]> 124*Tzvetomir Stoyanov* <[email protected]> 125-- 126REPORTING BUGS 127-------------- 128Report bugs to <[email protected]> 129 130LICENSE 131------- 132libtracefs is Free Software licensed under the GNU LGPL 2.1 133 134RESOURCES 135--------- 136https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ 137 138COPYING 139------- 140Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under 141the terms of the GNU Public License (GPL). 142