libtracefs(3)
=============

NAME
----
tracefs_event_systems, tracefs_system_events, tracefs_event_enable, tracefs_event_disable,
tracefs_iterate_raw_events, tracefs_iterate_stop - Work with trace systems and events.

SYNOPSIS
--------
[verse]
--
*#include <tracefs.h>*

char pass:[*]pass:[*]*tracefs_event_systems*(const char pass:[*]_tracing_dir_);
char pass:[*]pass:[*]*tracefs_system_events*(const char pass:[*]_tracing_dir_, const char pass:[*]_system_);
int *tracefs_event_enable*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_,
			   const char pass:[*]_event_);
int *tracefs_event_disable*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_,
			    const char pass:[*]_event_);
int *tracefs_iterate_raw_events*(struct tep_handle pass:[*]_tep_, struct tracefs_instance pass:[*]_instance_,
				 cpu_set_t pass:[*]_cpus_, int _cpu_size_,
				 int (pass:[*]_callback_)(struct tep_event pass:[*], struct tep_record pass:[*], int, void pass:[*]),
				 void pass:[*]_callback_context_);
void *tracefs_iterate_stop*(struct tracefs_instance pass:[*]_instance_);

--

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_iterate_raw_events()* function will read the tracefs raw
data buffers and call the specified _callback_ function for every event it
encounters. Events are iterated in sorted order: oldest first. An initialized
_tep_ handler is required (See *tracefs_local_events*(3)). If _instance_ is
NULL, then the toplevel tracefs buffer is used, otherwise the buffer for
the corresponding _instance_ is read. To filter only on a subset of CPUs,
_cpus_ and _cpu_size_ may be set to only call _callback_ with events that
occurred on the CPUs specified, otherwise if _cpus_ is NULL then the _callback_
function will be called for all events, and _cpu_size_ is ignored. The
_callback_ function will be called with the following parameters: A
pointer to a struct tep_event that corresponds to the type of event the
record is; The record representing the event; The CPU that the event
occurred on; and a pointer to user specified _callback_context_. If the _callback_
returns non-zero, the iteration stops.

Use *tracefs_iterate_stop()* to force a executing *tracefs_iterate_raw_events()*
to halt. This can be called from either a callback that is called by
the iterator (even though a return of non-zero will stop it), or from another
thread.

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_iterate_raw_events()* function returns -1 in case of an error or
0 otherwise.

EXAMPLE
-------
[source,c]
--
#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
-----
[verse]
--
*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.
--

SEE ALSO
--------
*libtracefs*(3),
*libtraceevent*(3),
*trace-cmd*(1)

AUTHOR
------
[verse]
--
*Steven Rostedt* <rostedt@goodmis.org>
*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>
--
REPORTING BUGS
--------------
Report bugs to  <linux-trace-devel@vger.kernel.org>

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