# tracefs_event_systems

## NAME



           tracefs_event_systems, tracefs_system_events,
           tracefs_event_enable, tracefs_event_disable,
           tracefs_event_is_enabled - Work with trace systems and events.
    


## SYNOPSIS



           **#include <tracefs.h>**
    
           enum tracefs_event_state {
                   TRACEFS_ERROR = -1,
                   TRACEFS_ALL_DISABLED = 0,
                   TRACEFS_ALL_ENABLED = 1,
                   TRACEFS_SOME_ENABLED = 2,
           };
    
           char ** **tracefs_event_systems**(const char *_tracing_dir_);
           char ** **tracefs_system_events**(const char *_tracing_dir_ , const char *_system_);
           int **tracefs_event_enable**(struct tracefs_instance *_instance_ , const char *_system_ ,
                                      const char *_event_);
           int **tracefs_event_disable**(struct tracefs_instance *_instance_ , const char *_system_ ,
                                       const char *_event_);
           enum tracefs_enable_state **tracefs_event_is_enabled**(struct tracefs_instance *_instance_ ,
                                    const char *_system_ , const char *_event_);
    


## DESCRIPTION



           Trace systems and events related APIs.
    
           The **tracefs_event_systems()** function returns array of strings with
           the names of all registered trace systems, 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 is a NULL pointer. The array
           must be freed with **tracefs_list_free()** API.
    
           The **tracefs_system_events()** function returns array of strings with
           the names of all registered trace events for given trace system
           specified by _system_ , 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_event_enable()** function enables a given event based on
           the _system_ and _event_ passed in for the given _instance_. If _instance_
           is NULL, then the top level tracing directory is used. If _system_
           and _event_ are both NULL, then all events are enabled for the
           _instance_. If _event_ is NULL then all events within the _system_ are
           enabled. If _system_ is NULL, then all systems are searched and any
           event within a system that matches _event_ is enabled. Both _system_
           and _event_ may be regular expressions as defined by regex(3).
    
           The **tracefs_event_disable()** function disables the events that
           match the _system_ and _event_ parameters for the given _instance_. What
           events are disable follow the same rules as **tracefs_event_enable()**
           for matching events. That is, if _instance_ is NULL, then the top
           level tracing directory is used. If both _system_ and _event_ are NULL
           then all events are disabled for the given _instance_ , and so on.
    
           The **tracefs_event_is_enabled()** returns if an event is enabled, a
           set of events are enabled, a system is enabled, or all events are
           enabled. If both _system_ and _event_ are NULL, then it returns the
           enable state of all events. If _system_ is not NULL and _event_ is
           NULL, then it will check if all the events in all the systems that
           _system_ and return the enable state of those events. If _system_ is
           NULL and _event_ is not NULL, then it will match all the events in
           all systems that match _event_ and return their enabled state. If
           both _system_ and _event_ are not NULL, then it will return the
           enabled state of all matching events. The enabled state is defined
           as:
    
           **TRACEFS_ERROR** - An error occurred including no event were matched.
    
           **TRACEFS_ALL_DISABLED** - All matching events are disabled.
    
           **TRACEFS_ALL_ENABLED** - All matching events are enabled.
    
           **TRACEFS_SOME_ENABLED** - Some matching events were enabled while
           others were not.
    


## RETURN VALUE



           The **tracefs_event_systems()** and **tracefs_system_events()** functions
           return an 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.
    
           Both **tracefs_event_enable()** and **tracefs_event_disable()** return 0
           if they found any matching events (Note it does not check the
           previous status of the event. If **tracefs_event_enable()** finds an
           event that is already enabled, and there are no other errors, then
           it will return 0). If an error occurs, even if other events were
           found, it will return -1 and errno will be set. If no errors
           occur, but no events are found that match the _system_ and _event_
           parameters, then -1 is returned and errno is not set.
    
           The **tracefs_event_is_enabled()** returns the enabled status of the
           matching events or TRACEFS_ERROR on error.
    


## EXAMPLE



               #include <tracefs.h>
    
               char **systems = tracefs_event_systems(NULL);
    
                       if (systems) {
                               int i = 0;
                               /* Got registered trace systems from the top trace instance */
                               while (systems[i]) {
                                       char **events = tracefs_system_events(NULL, systems[i]);
                                       if (events) {
                                               /* Got registered events in system[i] from the top trace instance */
                                               int j = 0;
    
                                               while (events[j]) {
                                                       /* Got event[j] in system[i] from the top trace instance */
                                                       j++;
                                               }
                                               tracefs_list_free(events);
                                       }
                                       i++;
                               }
                               tracefs_list_free(systems);
                       }
               ....
               static int records_walk(struct tep_event *tep, struct tep_record *record, int cpu, void *context)
               {
                       /* Got recorded event on cpu */
                       return 0;
               }
               ...
               struct tep_handle *tep = tracefs_local_events(NULL);
    
                       if (!tep) {
                               /* Failed to initialise tep handler with local events */
                               ...
                       }
    
                       errno = 0;
                       ret = tracefs_event_enable(NULL, "sched", NULL);
                       if (ret < 0 && !errno)
                               printf("Could not find 'sched' events\n");
                       tracefs_event_enable(NULL, "irq", "irq_handler_\(enter\|exit\)");
    
                       if (tracefs_iterate_raw_events(tep, NULL, NULL, 0, records_walk, NULL) < 0) {
                               /* Error walking through the recorded raw events */
                       }
    
                       /* Disable all events */
                       tracefs_event_disable(NULL, NULL, NULL);
                       tep_free(tep);
    


## 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.
    


## 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
    


* * *