1libtracefs(3) 2============= 3 4NAME 5---- 6tracefs_event_systems, tracefs_system_events, tracefs_event_enable, tracefs_event_disable, 7tracefs_event_is_enabled - Work with trace systems and events. 8 9SYNOPSIS 10-------- 11[verse] 12-- 13*#include <tracefs.h>* 14 15enum tracefs_event_state { 16 TRACEFS_ERROR = -1, 17 TRACEFS_ALL_DISABLED = 0, 18 TRACEFS_ALL_ENABLED = 1, 19 TRACEFS_SOME_ENABLED = 2, 20}; 21 22char pass:[*]pass:[*]*tracefs_event_systems*(const char pass:[*]_tracing_dir_); 23char pass:[*]pass:[*]*tracefs_system_events*(const char pass:[*]_tracing_dir_, const char pass:[*]_system_); 24int *tracefs_event_enable*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, 25 const char pass:[*]_event_); 26int *tracefs_event_disable*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, 27 const char pass:[*]_event_); 28enum tracefs_enable_state *tracefs_event_is_enabled*(struct tracefs_instance pass:[*]_instance_, 29 const char pass:[*]_system_, const char pass:[*]_event_); 30-- 31 32DESCRIPTION 33----------- 34Trace systems and events related APIs. 35 36The *tracefs_event_systems()* function returns array of strings with the 37names of all registered trace systems, located in the given _tracing_dir_ 38directory. This could be NULL or the location of the tracefs mount point 39for the trace systems of the local machine, or it may be a path to a copy 40of the tracefs directory from another machine. The last entry in the array 41is a NULL pointer. The array must be freed with *tracefs_list_free()* API. 42 43The *tracefs_system_events()* function returns array of strings with the 44names of all registered trace events for given trace system specified by 45_system_, located in the given _tracing_dir_ directory. This could be NULL 46or the location of the tracefs mount point for the trace systems of the 47local machine, or it may be a path to a copy of the tracefs directory 48from another machine. The last entry in the array as a NULL pointer. 49The array must be freed with *tracefs_list_free()* API. 50 51The *tracefs_event_enable()* function enables a given event based on 52the _system_ and _event_ passed in for the given _instance_. If _instance_ 53is NULL, then the top level tracing directory is used. If _system_ 54and _event_ are both NULL, then all events are enabled for the _instance_. 55If _event_ is NULL then all events within the _system_ are enabled. 56If _system_ is NULL, then all systems are searched and any event within 57a system that matches _event_ is enabled. Both _system_ and _event_ may 58be regular expressions as defined by *regex*(3). 59 60The *tracefs_event_disable()* function disables the events that match 61the _system_ and _event_ parameters for the given _instance_. What events 62are disable follow the same rules as *tracefs_event_enable()* for matching 63events. That is, if _instance_ is NULL, then the top level tracing directory 64is used. If both _system_ and _event_ are NULL then all events are disabled 65for the given _instance_, and so on. 66 67The *tracefs_event_is_enabled()* returns if an event is enabled, a set of 68events are enabled, a system is enabled, or all events are enabled. If both 69_system_ and _event_ are NULL, then it returns the enable state of all events. 70If _system_ is not NULL and _event_ is NULL, then it will check if all the events 71in all the systems that _system_ and return the enable state of those events. 72If _system_ is NULL and _event_ is not NULL, then it will match all the events 73in all systems that match _event_ and return their enabled state. If both _system_ 74and _event_ are not NULL, then it will return the enabled state of all matching 75events. The enabled state is defined as: 76 77*TRACEFS_ERROR* - An error occurred including no event were matched. 78 79*TRACEFS_ALL_DISABLED* - All matching events are disabled. 80 81*TRACEFS_ALL_ENABLED* - All matching events are enabled. 82 83*TRACEFS_SOME_ENABLED* - Some matching events were enabled while others were not. 84 85RETURN VALUE 86------------ 87The *tracefs_event_systems()* and *tracefs_system_events()* functions return 88an array of strings. The last element in that array is a NULL pointer. The array 89must be freed with *tracefs_list_free()* API. In case of an error, NULL is returned. 90 91Both *tracefs_event_enable()* and *tracefs_event_disable()* return 0 if they found 92any matching events (Note it does not check the previous status of the event. If 93*tracefs_event_enable()* finds an event that is already enabled, and there are no 94other errors, then it will return 0). If an error occurs, even if other events were 95found, it will return -1 and errno will be set. If no errors occur, but no events 96are found that match the _system_ and _event_ parameters, then -1 is returned 97and errno is not set. 98 99The *tracefs_event_is_enabled()* returns the enabled status of the matching events 100or TRACEFS_ERROR on error. 101 102EXAMPLE 103------- 104[source,c] 105-- 106#include <tracefs.h> 107 108char **systems = tracefs_event_systems(NULL); 109 110 if (systems) { 111 int i = 0; 112 /* Got registered trace systems from the top trace instance */ 113 while (systems[i]) { 114 char **events = tracefs_system_events(NULL, systems[i]); 115 if (events) { 116 /* Got registered events in system[i] from the top trace instance */ 117 int j = 0; 118 119 while (events[j]) { 120 /* Got event[j] in system[i] from the top trace instance */ 121 j++; 122 } 123 tracefs_list_free(events); 124 } 125 i++; 126 } 127 tracefs_list_free(systems); 128 } 129.... 130static int records_walk(struct tep_event *tep, struct tep_record *record, int cpu, void *context) 131{ 132 /* Got recorded event on cpu */ 133 return 0; 134} 135... 136struct tep_handle *tep = tracefs_local_events(NULL); 137 138 if (!tep) { 139 /* Failed to initialise tep handler with local events */ 140 ... 141 } 142 143 errno = 0; 144 ret = tracefs_event_enable(NULL, "sched", NULL); 145 if (ret < 0 && !errno) 146 printf("Could not find 'sched' events\n"); 147 tracefs_event_enable(NULL, "irq", "irq_handler_\(enter\|exit\)"); 148 149 if (tracefs_iterate_raw_events(tep, NULL, NULL, 0, records_walk, NULL) < 0) { 150 /* Error walking through the recorded raw events */ 151 } 152 153 /* Disable all events */ 154 tracefs_event_disable(NULL, NULL, NULL); 155 tep_free(tep); 156-- 157FILES 158----- 159[verse] 160-- 161*tracefs.h* 162 Header file to include in order to have access to the library APIs. 163*-ltracefs* 164 Linker switch to add when building a program that uses the library. 165-- 166 167SEE ALSO 168-------- 169*libtracefs*(3), 170*libtraceevent*(3), 171*trace-cmd*(1) 172 173AUTHOR 174------ 175[verse] 176-- 177*Steven Rostedt* <[email protected]> 178*Tzvetomir Stoyanov* <[email protected]> 179-- 180REPORTING BUGS 181-------------- 182Report bugs to <[email protected]> 183 184LICENSE 185------- 186libtracefs is Free Software licensed under the GNU LGPL 2.1 187 188RESOURCES 189--------- 190https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ 191 192COPYING 193------- 194Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under 195the terms of the GNU Public License (GPL). 196