'\" t
.\"     Title: libtracefs
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 01/13/2024
.\"    Manual: libtracefs Manual
.\"    Source: libtracefs 1.8.0
.\"  Language: English
.\"
.TH "LIBTRACEFS" "3" "01/13/2024" "libtracefs 1\&.8\&.0" "libtracefs Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
tracefs_event_systems, tracefs_system_events, tracefs_event_enable, tracefs_event_disable, tracefs_event_is_enabled \- Work with trace systems and events\&.
.SH "SYNOPSIS"
.sp
.nf
\fB#include <tracefs\&.h>\fR

enum tracefs_event_state {
        TRACEFS_ERROR = \-1,
        TRACEFS_ALL_DISABLED = 0,
        TRACEFS_ALL_ENABLED = 1,
        TRACEFS_SOME_ENABLED = 2,
};

char **\fBtracefs_event_systems\fR(const char *\fItracing_dir\fR);
char **\fBtracefs_system_events\fR(const char *\fItracing_dir\fR, const char *\fIsystem\fR);
int \fBtracefs_event_enable\fR(struct tracefs_instance *\fIinstance\fR, const char *\fIsystem\fR,
                           const char *\fIevent\fR);
int \fBtracefs_event_disable\fR(struct tracefs_instance *\fIinstance\fR, const char *\fIsystem\fR,
                            const char *\fIevent\fR);
enum tracefs_enable_state \fBtracefs_event_is_enabled\fR(struct tracefs_instance *\fIinstance\fR,
                         const char *\fIsystem\fR, const char *\fIevent\fR);
.fi
.SH "DESCRIPTION"
.sp
Trace systems and events related APIs\&.
.sp
The \fBtracefs_event_systems()\fR function returns array of strings with the names of all registered trace systems, located in the given \fItracing_dir\fR 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 \fBtracefs_list_free()\fR API\&.
.sp
The \fBtracefs_system_events()\fR function returns array of strings with the names of all registered trace events for given trace system specified by \fIsystem\fR, located in the given \fItracing_dir\fR 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 \fBtracefs_list_free()\fR API\&.
.sp
The \fBtracefs_event_enable()\fR function enables a given event based on the \fIsystem\fR and \fIevent\fR passed in for the given \fIinstance\fR\&. If \fIinstance\fR is NULL, then the top level tracing directory is used\&. If \fIsystem\fR and \fIevent\fR are both NULL, then all events are enabled for the \fIinstance\fR\&. If \fIevent\fR is NULL then all events within the \fIsystem\fR are enabled\&. If \fIsystem\fR is NULL, then all systems are searched and any event within a system that matches \fIevent\fR is enabled\&. Both \fIsystem\fR and \fIevent\fR may be regular expressions as defined by \fBregex\fR(3)\&.
.sp
The \fBtracefs_event_disable()\fR function disables the events that match the \fIsystem\fR and \fIevent\fR parameters for the given \fIinstance\fR\&. What events are disable follow the same rules as \fBtracefs_event_enable()\fR for matching events\&. That is, if \fIinstance\fR is NULL, then the top level tracing directory is used\&. If both \fIsystem\fR and \fIevent\fR are NULL then all events are disabled for the given \fIinstance\fR, and so on\&.
.sp
The \fBtracefs_event_is_enabled()\fR returns if an event is enabled, a set of events are enabled, a system is enabled, or all events are enabled\&. If both \fIsystem\fR and \fIevent\fR are NULL, then it returns the enable state of all events\&. If \fIsystem\fR is not NULL and \fIevent\fR is NULL, then it will check if all the events in all the systems that \fIsystem\fR and return the enable state of those events\&. If \fIsystem\fR is NULL and \fIevent\fR is not NULL, then it will match all the events in all systems that match \fIevent\fR and return their enabled state\&. If both \fIsystem\fR and \fIevent\fR are not NULL, then it will return the enabled state of all matching events\&. The enabled state is defined as:
.sp
\fBTRACEFS_ERROR\fR \- An error occurred including no event were matched\&.
.sp
\fBTRACEFS_ALL_DISABLED\fR \- All matching events are disabled\&.
.sp
\fBTRACEFS_ALL_ENABLED\fR \- All matching events are enabled\&.
.sp
\fBTRACEFS_SOME_ENABLED\fR \- Some matching events were enabled while others were not\&.
.SH "RETURN VALUE"
.sp
The \fBtracefs_event_systems()\fR and \fBtracefs_system_events()\fR functions return an array of strings\&. The last element in that array is a NULL pointer\&. The array must be freed with \fBtracefs_list_free()\fR API\&. In case of an error, NULL is returned\&.
.sp
Both \fBtracefs_event_enable()\fR and \fBtracefs_event_disable()\fR return 0 if they found any matching events (Note it does not check the previous status of the event\&. If \fBtracefs_event_enable()\fR 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 \fIsystem\fR and \fIevent\fR parameters, then \-1 is returned and errno is not set\&.
.sp
The \fBtracefs_event_is_enabled()\fR returns the enabled status of the matching events or TRACEFS_ERROR on error\&.
.SH "EXAMPLE"
.sp
.if n \{\
.RS 4
.\}
.nf
#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 \*(Aqsched\*(Aq events\en");
        tracefs_event_enable(NULL, "irq", "irq_handler_\e(enter\e|exit\e)");

        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);
.fi
.if n \{\
.RE
.\}
.SH "FILES"
.sp
.if n \{\
.RS 4
.\}
.nf
\fBtracefs\&.h\fR
        Header file to include in order to have access to the library APIs\&.
\fB\-ltracefs\fR
        Linker switch to add when building a program that uses the library\&.
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
\fBlibtracefs\fR(3), \fBlibtraceevent\fR(3), \fBtrace\-cmd\fR(1)
.SH "AUTHOR"
.sp
.if n \{\
.RS 4
.\}
.nf
\fBSteven Rostedt\fR <\m[blue]\fBrostedt@goodmis\&.org\fR\m[]\&\s-2\u[1]\d\s+2>
\fBTzvetomir Stoyanov\fR <\m[blue]\fBtz\&.stoyanov@gmail\&.com\fR\m[]\&\s-2\u[2]\d\s+2>
.fi
.if n \{\
.RE
.\}
.SH "REPORTING BUGS"
.sp
Report bugs to <\m[blue]\fBlinux\-trace\-devel@vger\&.kernel\&.org\fR\m[]\&\s-2\u[3]\d\s+2>
.SH "LICENSE"
.sp
libtracefs is Free Software licensed under the GNU LGPL 2\&.1
.SH "RESOURCES"
.sp
\m[blue]\fBhttps://git\&.kernel\&.org/pub/scm/libs/libtrace/libtracefs\&.git/\fR\m[]
.SH "COPYING"
.sp
Copyright (C) 2020 VMware, Inc\&. Free use of this software is granted under the terms of the GNU Public License (GPL)\&.
.SH "NOTES"
.IP " 1." 4
rostedt@goodmis.org
.RS 4
\%mailto:rostedt@goodmis.org
.RE
.IP " 2." 4
tz.stoyanov@gmail.com
.RS 4
\%mailto:tz.stoyanov@gmail.com
.RE
.IP " 3." 4
linux-trace-devel@vger.kernel.org
.RS 4
\%mailto:linux-trace-devel@vger.kernel.org
.RE