'\" t
.\"     Title: libtracecmd
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 02/10/2024
.\"    Manual: libtracefs Manual
.\"    Source: libtracefs
.\"  Language: English
.\"
.TH "LIBTRACECMD" "3" "02/10/2024" "libtracefs" "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"
tracecmd_iterate_events, tracecmd_iterate_events_multi, tracecmd_follow_event, tracecmd_follow_missed_events, tracecmd_filter_add \- Read events from a trace file
.SH "SYNOPSIS"
.sp
.nf
\fB#include <trace\-cmd\&.h>\fR

int \fBtracecmd_iterate_events\fR(struct tracecmd_input *\fIhandle\fR,
                            cpu_set_t *\fIcpus\fR, int \fIcpu_size\fR,
                            int (*\fIcallback\fR)(struct tracecmd_input *,
                                            struct tep_record *,
                                            int, void *),
                            void *\fIcallback_data\fR);
int \fBtracecmd_iterate_events_multi\fR(struct tracecmd_input **\fIhandles\fR,
                                  int \fInr_handles\fR,
                                  int (*\fIcallback\fR)(struct tracecmd_input *,
                                                           struct tep_record *,
                                                           int, void *),
                                  void *\fIcallback_data\fR);
int \fBtracecmd_follow_event\fR(struct tracecmd_input *\fIhandle\fR,
                          const char *\fIsystem\fR, const char *\fIevent_name\fR,
                          int (*\fIcallback\fR)(struct tracecmd_input *,
                                          struct tep_event *,
                                          struct tep_record *,
                                          int, void *),
                          void *\fIcallback_data\fR);
int \fBtracecmd_follow_missed_events\fR(struct tracecmd_input *\fIhandle\fR,
                                   int (*\fIcallback\fR)(struct tracecmd_input *,
                                                   struct tep_event *,
                                                   struct tep_record *,
                                                   int, void *),
                                   void *\fIcallback_data\fR);
struct tracecmd_filter *\fBtracecmd_filter_add\fR(struct tracecmd_input *\fIhandle\fR,
                                            const char *\fIfilter_str\fR, bool \fIneg\fR);
.fi
.SH "DESCRIPTION"
.sp
This set of APIs can be used to iterate over events after opening a trace file using one of the open functions like \fBtracecmd_open(3)\fR or \fBtracecmd_open_fd(3)\fR\&.
.sp
The function \fBtracecmd_iterate_events()\fR will iterate through all the events in the trace file defined by \fIhandle\fR, where \fIhandle\fR is returned from one of the \fBtracecmd_open(3)\fR functions\&. It will call the \fIcallback\fR() function on the events on the CPUs defined by \fIcpus\fR\&. The \fIcpu_size\fR must be the size of \fIcpus\fR (see \fBCPU_SET(3)\fR)\&. If \fIcpus\fR is NULL, then \fIcpu_size\fR is ignored and \fIcallback()\fR will be called for all events on all CPUs in the trace file\&. The \fIcallback_data\fR is passed to the \fIcallback()\fR as its last parameter\&. \fIcallback\fR may be NULL, which is useful if \fBtracecmd_follow_event()\fR is used, but note if \fIcallback\fR is NULL, then \fIcallback_data\fR is ignored and not sent to the \fIcallback\fR of \fBtracecmd_follow_event()\fR\&.
.sp
The function \fBtracecmd_iterate_events_multi()\fR is similar to \fBtracecmd_iterate_events()\fR except that it allows to iterate over more than one trace file\&. If \fBtracecmd agent(1)\fR is used to get a trace file for both the host and guest, make sure that the host trace file is the first entry in \fIhandles\fR and \fBtracecmd_iterate_events_multi()\fR will do the synchronization of the meta data for the guest files that come later in \fIhandles\fR\&. \fIhandles\fR is an array of trace file descriptors that were opened by \fBtracecmd_open(3)\fR and friends\&. Note, unlike \fBtracecmd_iterate_events()\fR, \fBtracecmd_iterate_events_multi()\fR does not filter on CPUs, as it will cause the API to become too complex in knowing which handle to filter the CPUs on\&. If CPU filtering is desired, then the \fIcallback\fR should check the \fIrecord\fR\(->cpu to and return 0 if it is not the desired CPU to process\&. \fInr_handles\fR denotes the number of elements in \fIhandles\fR\&. The \fIcallback_data\fR is passed to the \fIcallback\fR as its last parameter\&. \fIcallback\fR may be NULL, which is useful if \fBtracecmd_follow_event()\fR is used, but note if \fIcallback\fR is NULL, then \fIcallback_data\fR is ignored and not sent to the \fIcallback\fR of \fBtracecmd_follow_event()\fR\&.
.sp
The \fIcallback()\fR for both \fBtracecmd_iterate_events()\fR and \fBtracecmd_iterate_events_multi()\fR is of the prototype:
.sp
int \fIcallback()\fR(struct tracecmd_input *\fIhandle\fR, struct tep_record *\fIrecord\fR, int \fIcpu\fR, void *\fIdata\fR);
.sp
The \fIhandle\fR is the same \fIhandle\fR passed to \fBtracecmd_iterate_events()\fR or the current handle of \fIhandles\fR passed to \fBtracecmd_iterate_events_multi()\fR that the \fIrecord\fR belongs to\&. The \fIrecord\fR is the current event record\&. The \fIcpu\fR is the current CPU being processed\&. Note, for \fBtracecmd_iterate_events_multi()\fR it may not be the actual CPU of the file, but the nth CPU of all the \fIhandles\fR put together\&. Use \fIrecord\fR\(->cpu to get the actual CPU that the event is on\&.
.sp
The \fBtracecmd_follow_event()\fR function will attach to a trace file descriptor \fIhandle\fR and call the \fIcallback\fR when the event described by \fIsystem\fR and \fIname\fR matches an event in the iteration of \fBtracecmd_iterate_events()\fR or \fBtracecmd_iterate_events_multi()\fR\&. Note, the \fIcpu\fR is the nth CPU for both \fBtracecmd_iterate_events()\fR and \fBtracecmd_iterate_events_multi()\fR\&. If the actual CPU of the \fIrecord\fR is needed, use \fIrecord\fR\(->cpu\&. For \fBtracecmd_iterate_events_multi()\fR, the \fIcallback\fR is only called if the \fIhandle\fR matches the current trace file descriptor within \fIhandles\fR\&. The \fIcallback_data\fR is passed as the last parameter to the \fIcallback()\fR function\&. Note, this \fIcallback()\fR function will be called before the \fIcallback()\fR function of either \fBtracecmd_iterate_events()\fR or \fBtracecmd_iterate_events_multi()\fR\&.
.sp
The \fIcallback()\fR prototype for *tracecmd_follow_event()_ is:
.sp
int \fIcallback()\fR(struct tracecmd_input *\fIhandle\fR, struct tep_event *\fIevent, struct tep_record *_record\fR, int \fIcpu\fR, void *\fIdata\fR);
.sp
The \fBtracecmd_follow_missed_events()\fR function will attach to a trace file descriptor \fIhandle\fR and call the \fIcallback\fR when missed events are detected\&. The \fIevent\fR will hold the type of event that the \fIrecord\fR is\&. The \fIrecord\fR will hold the information of the missed events\&. The \fIcpu\fR is the nth CPU for both \fBtracecmd_iterate_events()\fR and \fBtracecmd_iterate_events_multi()\fR\&. If the CPU that the missed events are for is needed, use \fIrecord\fR\(->cpu\&. If \fIrecord\fR\(->missed_events is a positive number, then it holds the number of missed events since the last event on its CPU, otherwise it will be negative, and that will mean that the number of missed events is unknown but missed events exist since the last event on the CPU\&. The \fIcallback\fR and \fIcallback_data\fR is the same format as \fBtracecmd_follow_event()\fR above\&. The missed events \fIcallback\fR is called before any of the other \fIcallbacks\fR and any filters that were added by \fBtracecmd_filter_add()\fR are ignored\&. If \fIcallback\fR returns a non zero, it will stop the iterator before it calls any of the other iterator callbacks for the given record\&.
.sp
The \fBtracecmd_filter_add()\fR function, adds a filter to \fIhandle\fR that affects both \fBtracecmd_iterate_events()\fR and \fBtracecmd_iterate_events_multi()\fR\&. The \fIfilter_str\fR is a character string defining a filter in a format that is defined by \fBtep_filter_add_filter_str(3)\fR\&. If \fIneg\fR is true, then the events that match the filter will be skipped, otherwise the events that match will execute the \fIcallback()\fR function in the iterators\&.
.SH "RETURN VALUE"
.sp
Both \fBtracecmd_iterate_events()\fR and \fBtracecmd_iterate_events_multi()\fR return zero if they successfully iterated all events (handling the follow and filters appropriately)\&. Or an error value, which can include returning a non\-zero result from the \fIcallback()\fR function\&.
.SH "EXAMPLE"
.sp
.if n \{\
.RS 4
.\}
.nf
#define _GNU_SOURCE
#include <sched\&.h>
#include <stdlib\&.h>
#include <getopt\&.h>
#include <trace\-cmd\&.h>

struct private_data {
        int             cpu;
        const char      *file;
};

static int print_events(struct tracecmd_input *handle, struct tep_record *record, int cpu, void *data)
{
        static struct trace_seq seq;
        struct tep_handle *tep = tracecmd_get_tep(handle);
        struct private_data *pdata = tracecmd_get_private(handle);

        /* For multi handles we need this */
        if (pdata\->cpu >= 0 && pdata\->cpu != record\->cpu)
                return 0;

        if (!seq\&.buffer)
                trace_seq_init(&seq);

        trace_seq_reset(&seq);
        trace_seq_printf(&seq, "%s: ", pdata\->file);
        tep_print_event(tep, &seq, record, "%6\&.1000d [%03d] %s\-%d %s: %s\en",
                        TEP_PRINT_TIME, TEP_PRINT_CPU, TEP_PRINT_COMM, TEP_PRINT_PID,
                        TEP_PRINT_NAME, TEP_PRINT_INFO);
        trace_seq_terminate(&seq);
        trace_seq_do_printf(&seq);
        return 0;
}

static int print_event(struct tracecmd_input *handle, struct tep_event *event,
                       struct tep_record *record, int cpu, void *data)
{
        return print_events(handle, record, cpu, data);
}

static int missed_events(struct tracecmd_input *handle, struct tep_event *event,
                         struct tep_record *record, int cpu, void *data)
{
        if (record\->missed_events > 0)
                printf("CPU [%03d] has %d missed events\en",
                         record\->cpu, record\->missed_events);
        else
                printf("CPU [%03d] has missed events\en", record\->cpu);
        return 0;
}

static void usage(const char *argv0)
{
        printf("usage: [\-c cpu][\-f filter][\-e event] %s trace\&.dat [trace\&.dat \&.\&.\&.]\en",
               argv0);
        exit(\-1);
}

int main(int argc, char **argv)
{
        struct tracecmd_input **handles = NULL;
        const char *filter_str = NULL;
        const char *argv0 = argv[0];
        struct private_data *priv;
        cpu_set_t *cpuset = NULL;
        char *event = NULL;
        size_t cpusize = 0;
        int nr_handles = 0;
        int cpu = \-1;
        int i;
        int c;

        while ((c = getopt(argc, argv, "c:f:e:")) >= 0) {
                switch (c) {
                case \*(Aqc\*(Aq:
                        /* filter all trace data to this one CPU\&. */
                        cpu = atoi(optarg);
                        break;
                case \*(Aqf\*(Aq:
                        filter_str = optarg;
                        break;
                case \*(Aqe\*(Aq:
                        event = optarg;
                        break;
                default:
                        usage(argv0);
                }
        }
        argc \-= optind;
        argv += optind;

        if (argc == 0)
                usage(argv0);

        for (i = 0; i < argc; i++) {
                handles = realloc(handles, sizeof(*handles) * (nr_handles + 1));
                if (!handles)
                        exit(\-1);
                handles[nr_handles] = tracecmd_open(argv[i], 0);
                if (!handles[nr_handles]) {
                        perror(argv[i]);
                        exit(\-1);
                }
                if (filter_str) {
                        if (tracecmd_filter_add(handles[nr_handles], filter_str, false) == NULL) {
                                perror("adding filter");
                                exit(\-1);
                        }
                }
                priv = calloc(1, sizeof(*priv));
                if (!priv)
                        exit(\-1);
                priv\->file = argv[i];
                priv\->cpu = cpu;
                tracecmd_set_private(handles[nr_handles], priv);
                if (event) {
                        if (tracecmd_follow_event(handles[nr_handles], NULL, event, print_event, NULL) < 0) {
                                printf("Could not follow event %s for file %s\en", event, argv[i]);
                                exit(\-1);
                        }
                }
                tracecmd_follow_missed_events(handles[nr_handles], missed_events, NULL);
                nr_handles++;
        }

        /* Shortcut */
        if (nr_handles == 1) {
                if (cpu >= 0) {
                        cpuset = CPU_ALLOC(cpu + 1);
                        if (!cpuset)
                                exit(\-1);
                        cpusize = CPU_ALLOC_SIZE(cpu + 1);
                        CPU_SET_S(cpu, cpusize, cpuset);
                }
                if (event)
                        tracecmd_iterate_events(handles[0], cpuset, cpusize, NULL, NULL);
                else
                        tracecmd_iterate_events(handles[0], cpuset, cpusize, print_events, NULL);
        } else {
                if (event)
                        tracecmd_iterate_events_multi(handles, nr_handles, NULL, NULL);
                else
                        tracecmd_iterate_events_multi(handles, nr_handles, print_events, NULL);
        }

        for (i = 0; i < nr_handles; i++) {
                priv = tracecmd_get_private(handles[i]);
                free(priv);
                tracecmd_close(handles[i]);
        }
        free(handles);
}
.fi
.if n \{\
.RE
.\}
.SH "FILES"
.sp
.if n \{\
.RS 4
.\}
.nf
\fBtrace\-cmd\&.h\fR
        Header file to include in order to have access to the library APIs\&.
\fB\-ltracecmd\fR
        Linker switch to add when building a program that uses the library\&.
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
\fBlibtracefs(3)\fR, \fBlibtraceevent(3)\fR, \fBtrace\-cmd(1)\fR \fBtrace\-cmd\&.dat(5)\fR
.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
libtracecmd is Free Software licensed under the GNU LGPL 2\&.1
.SH "RESOURCES"
.sp
\m[blue]\fBhttps://git\&.kernel\&.org/pub/scm/utils/trace\-cmd/trace\-cmd\&.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