'\" t
.\" Title: libtracefs
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 01/16/2024
.\" Manual: libtracefs Manual
.\" Source: libtracefs 1.8.0
.\" Language: English
.\"
.TH "LIBTRACEFS" "3" "01/16/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_iterate_raw_events, tracefs_iterate_stop, tracefs_follow_event, tracefs_follow_missed_events, tracefs_follow_event_clear, tracefs_follow_missed_events_clear, tracefs_iterate_snapshot_events \- Iterate over events in the ring buffer
.SH "SYNOPSIS"
.sp
.nf
\fB#include \fR
int \fBtracefs_iterate_raw_events\fR(struct tep_handle *\fItep\fR, struct tracefs_instance *\fIinstance\fR,
cpu_set_t *\fIcpus\fR, int \fIcpu_size\fR,
int (*\fIcallback\fR)(struct tep_event *, struct tep_record *, int, void *),
void *\fIcallback_context\fR);
void \fBtracefs_iterate_stop\fR(struct tracefs_instance *\fIinstance\fR);
int \fBtracefs_follow_event\fR(struct tep_handle *\fItep\fR, struct tracefs_instance *\fIinstance\fR,
const char *\fIsystem\fR, const char *\fIevent_name\fR,
int (*\fIcallback\fR)(struct tep_event *,
struct tep_record *,
int, void *),
void *\fIcallback_data\fR);
int \fBtracefs_follow_missed_events\fR(struct tracefs_instance *\fIinstance\fR,
int (*\fIcallback\fR)(struct tep_event *,
struct tep_record *,
int, void *),
void *\fIcallback_data\fR);
int \fBtracefs_follow_event_clear\fR(struct tracefs_instance *\fIinstance\fR,
const char *\fIsystem\fR, const char *\fIevent_name\fR);
int \fBtracefs_follow_missed_events_clear\fR(struct tracefs_instance *\fIinstance\fR);
int \fBtracefs_iterate_snapshot_events\fR(struct tep_handle *\fItep\fR, struct tracefs_instance *\fIinstance\fR,
cpu_set_t *\fIcpus\fR, int \fIcpu_size\fR,
int (*\fIcallback\fR)(struct tep_event *, struct tep_record *, int, void *),
void *\fIcallback_context\fR);
.fi
.SH "DESCRIPTION"
.sp
Trace iterator over raw events\&.
.sp
The \fBtracefs_iterate_raw_events()\fR function will read the tracefs raw data buffers and call the specified \fIcallback\fR function for every event it encounters\&. Events are iterated in sorted order: oldest first\&. An initialized \fItep\fR handler is required (See \fBtracefs_local_events\fR(3))\&. If \fIinstance\fR is NULL, then the toplevel tracefs buffer is used, otherwise the buffer for the corresponding \fIinstance\fR is read\&. To filter only on a subset of CPUs, \fIcpus\fR and \fIcpu_size\fR may be set to only call \fIcallback\fR with events that occurred on the CPUs specified, otherwise if \fIcpus\fR is NULL then the \fIcallback\fR function will be called for all events, and \fIcpu_size\fR is ignored\&. The \fIcallback\fR 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 \fIcallback_context\fR\&. If the \fIcallback\fR returns non\-zero, the iteration stops\&.
.sp
The \fBtracefs_iterate_snapshot_events()\fR works the same as \fBtracefs_iterate_raw_events()\fR except that it works on the snapshot buffer\&.
.sp
Use \fBtracefs_iterate_stop()\fR to force a executing \fBtracefs_iterate_raw_events()\fR 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\&.
.sp
The \fBtracefs_follow_event()\fR is used with \fBtracefs_iterate_raw_events()\fR but intead of the callback being called for every event, it is only called for the specified \fIsystem\fR / \fIevent_name\fR given to the function\&. The \fIcallback\fR is the same as for \fBtracefs_iterate_raw_events()\fR, and the passed in \fIcallback_context\fR will be passed to the \fIcallback\fR as well\&. Note, if it returns something other than 0, it will stop the loop before the \fIcallback\fR of \fBtracefs_iterate_raw_events()\fR is called\&.
.sp
The \fBtracefs_follow_missed_events()\fR will call the \fIcallback\fR when missed events are detected\&. It will set the \fIrecord\fR parameter of the callback to the record that came after the missed events and \fIevent\fR will be of the type of event \fIrecord\fR is\&. \fIcpu\fR will be set to the CPU that missed the events, and \fIcallback_data\fR will be the content that was passed in to the function\&.
.sp
The \fBtracefs_follow_event_clear()\fR will remove followers from \fIinstance\fR that match \fIsystem\fR and \fIevent_name\fR\&. If \fIsystem\fR and \fIevent_name\fR are both NULL, then it will remove all event followers associated to \fIinstance\fR\&. If just \fIsystem\fR is NULL, then it will remove all followers that follow events that match \fIevent_name\fR\&. If just \fIevent_name\fR is NULL, then it will remove all followers that are attached to events that are apart of a system that matches \fIsystem\fR\&.
.sp
The \fBtracefs_follow_missed_events_clear()\fR will remove all followers for missed events\&.
.SH "RETURN VALUE"
.sp
The \fBtracefs_iterate_raw_events()\fR function returns \-1 in case of an error or 0 otherwise\&.
.sp
Both \fBtracefs_follow_event_clear()\fR and \fBtracefs_follow_missed_events_clear()\fR return 0 on success and \-1 on error, or if it found no followers that match and should be removed\&.
.SH "EXAMPLE"
.sp
.if n \{\
.RS 4
.\}
.nf
#include
#include
#include
#include
struct my_struct {
bool stopped;
};
#define MAX_COUNT 500000
static int counter;
static int callback(struct tep_event *event, struct tep_record *record,
int cpu, void *data)
{
struct my_struct *my_data = data;
static struct trace_seq seq;
if (counter++ > MAX_COUNT) {
my_data\->stopped = true;
return 1;
}
if (!seq\&.buffer)
trace_seq_init(&seq);
tep_print_event(event\->tep, &seq, record, "%16s\-%\-5d [%03d] %6\&.1000d %s: %s\en",
TEP_PRINT_COMM, TEP_PRINT_PID, TEP_PRINT_CPU,
TEP_PRINT_TIME, TEP_PRINT_NAME, TEP_PRINT_INFO);
trace_seq_terminate(&seq);
trace_seq_do_printf(&seq);
trace_seq_reset(&seq);
return 0;
}
static int sched_callback(struct tep_event *event, struct tep_record *record,
int cpu, void *data)
{
static struct tep_format_field *prev_pid;
static struct tep_format_field *next_pid;
unsigned long long pid;
int this_pid = *(int *)data;
if (!prev_pid) {
prev_pid = tep_find_field(event, "prev_pid");
next_pid = tep_find_field(event, "next_pid");
if (!prev_pid || !next_pid) {
fprintf(stderr, "No pid fields??\en");
return \-1;
}
}
tep_read_number_field(prev_pid, record\->data, &pid);
if (pid == this_pid)
printf("WE ARE LEAVING!\en");
tep_read_number_field(next_pid, record\->data, &pid);
if (pid == this_pid)
printf("WE ARE ARRIVING!\en");
return 0;
}
static int missed_callback(struct tep_event *event, struct tep_record *record,
int cpu, void *data)
{
printf("OOPS! cpu %d dropped ", cpu);
if (record\->missed_events > 0)
printf("%lld ", record\->missed_events);
printf("events\en");
return 0;
}
static struct tracefs_instance *instance;
static struct my_struct my_data;
static void sig(int s)
{
tracefs_iterate_stop(instance);
my_data\&.stopped = true;
}
int main (int argc, char **argv, char **env)
{
struct tep_handle *tep;
int this_pid = getpid();
instance = tracefs_instance_create("my\-buffer");
if (!instance)
return \-1;
signal(SIGINT, sig);
tracefs_event_enable(instance, NULL, NULL);
sleep(1);
tracefs_event_disable(instance, NULL, NULL);
tep = tracefs_local_events(NULL);
tep_load_plugins(tep);
tracefs_follow_missed_events(instance, missed_callback, NULL);
tracefs_follow_event(tep, instance, "sched", "sched_switch", sched_callback, &this_pid);
tracefs_iterate_raw_events(tep, instance, NULL, 0, callback, &my_data);
/* Note, the clear here is to show how to clear all followers
* in case tracefs_iterate_raw_events() is called again, but
* does not want to include the followers\&. It\*(Aqs not needed
* here because tracefs_instance_free() will clean them up\&.
*/
tracefs_follow_event_clear(instance, NULL, NULL);
tracefs_follow_missed_events_clear(instance);
tracefs_instance_destroy(instance);
tracefs_instance_free(instance);
if (my_data\&.stopped) {
if (counter > MAX_COUNT)
printf("Finished max count\en");
else
printf("Finished via signal\en");
}
return 0;
}
.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