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