'\" t
.\" Title: libtracefs
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" 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_instance_get_stat, tracefs_instance_put_stat, tracefs_buffer_stat_entries, tracefs_buffer_stat_overrun, tracefs_buffer_stat_commit_overrun, tracefs_buffer_stat_bytes, tracefs_buffer_stat_event_timestamp, tracefs_buffer_stat_timestamp, tracefs_buffer_stat_dropped_events, tracefs_buffer_stat_read_events \- Handling tracing buffer stats
.SH "SYNOPSIS"
.sp
.nf
\fB#include \fR
struct tracefs_buffer_stat *\fBtracefs_instance_get_stat\fR(struct tracefs_instance *\fIinstance\fR, int \fIcpu\fR);
void \fBtracefs_instance_put_stat\fR(struct tracefs_buffer_stat *\fItstat\fR);
ssize_t \fBtracefs_buffer_stat_entries\fR(struct tracefs_buffer_stat *\fItstat\fR);
ssize_t \fBtracefs_buffer_stat_overrun\fR(struct tracefs_buffer_stat *\fItstat\fR);
ssize_t \fBtracefs_buffer_stat_commit_overrun\fR(struct tracefs_buffer_stat *\fItstat\fR);
ssize_t \fBtracefs_buffer_stat_bytes\fR(struct tracefs_buffer_stat *\fItstat\fR);
long long \fBtracefs_buffer_stat_event_timestamp\fR(struct tracefs_buffer_stat *\fItstat\fR);
long long \fBtracefs_buffer_stat_timestamp\fR(struct tracefs_buffer_stat *\fItstat\fR);
ssize_t \fBtracefs_buffer_stat_dropped_events\fR(struct tracefs_buffer_stat *\fItstat\fR);
ssize_t \fBtracefs_buffer_stat_read_events\fR(struct tracefs_buffer_stat *\fItstat\fR);
.fi
.SH "DESCRIPTION"
.sp
This set of functions read and parse the tracefs/per_cpu/cpuX/stats file\&. These files hold the statistics of the per CPU ring buffer, such as how many events are in the ring buffer, how many have been read and so on\&.
.sp
The \fBtracefs_instance_get_stat()\fR function will read and parse a given statistics file for a given \fIinstance\fR and \fIcpu\fR\&. As the ring buffer is split into per_cpu buffers, the information is only associated to the given \fIcpu\fR\&. The returned tracefs_buffer_stat pointer can be used with the other \fBtracefs_buffer_stat\fR functions and must be freed with \fBtracefs_instance_put_stat()\fR\&.
.sp
The \fBtracefs_instance_put_stat()\fR will free the resources allocated for the given \fIstat\fR that was created by \fBtracefs_instance_get_stat()\fR\&.
.sp
The \fBtracefs_buffer_stat_entries()\fR returns the number of events that are currently in the ring buffer associated with \fItstat\fR\&.
.sp
The \fBtracefs_buffer_stat_overrun()\fR returns the number of events that were lost by the ring buffer writer overrunning the reader\&.
.sp
The \fBtracefs_buffer_stat_commit_overrun()\fR returns the number of events that were lost because the ring buffer was too small and an interrupt interrupted a lower context event being recorded and it added more events than the ring buffer could hold\&. Note this is not a common occurrence and when it happens it means that something was not set up properly\&.
.sp
The \fBtracefs_buffer_stat_bytes()\fR returns the number of bytes that the current events take up\&. Note, it includes the meta data for the events, but does not include the meta data for the sub\-buffers\&.
.sp
The \fBtracefs_buffer_stat_event_timestamp()\fR returns the timestamp of the last event in the ring buffer\&.
.sp
The \fBtracefs_buffer_stat_timestamp()\fR returns the current timestamp of the ring buffer\&. Note, it is only read when \fBtracefs_instance_get_stat()\fR is called\&. It will have the timestamp of the ring buffer when that function was called\&.
.sp
The \fBtracefs_buffer_stat_dropped_events()\fR returns the number of events that were dropped if overwrite mode is disabled\&. It will show the events that were lost because the writer caught up to the reader and could not write any more events\&.
.sp
The \fBtracefs_buffer_stat_read_events()\fR returns the number of events that were consumed by a reader\&.
.SH "RETURN VALUE"
.sp
The \fBtracefs_instance_get_stat()\fR returns a tracefs_buffer_stat structure that can be used to retrieve the statistics via the other functions\&. It must be freed with \fBtracefs_instance_put_stat()\fR\&.
.sp
The other functions that return different values from the tracefs_buffer_stat structure all return the value, or \-1 if the value was not found\&.
.SH "EXAMPLE"
.sp
.if n \{\
.RS 4
.\}
.nf
#include
#include
#include
int main(int argc, char **argv)
{
char *trace;
char buf[1000];
int ret;
int i;
for (i = 0; i < sizeof(buf) \- 1; i++) {
buf[i] = \*(Aq0\*(Aq + i % 10;
}
buf[i] = \*(Aq\e0\*(Aq;
tracefs_instance_clear(NULL);
for (i = 0; i < 4; i++) {
ret = tracefs_printf(NULL, "%s\en", buf);
if (ret < 0)
perror("write");
}
trace = tracefs_instance_file_read(NULL, "trace", NULL);
printf("%s\en", trace);
free(trace);
for (i = 0; i < sysconf(_SC_NPROCESSORS_CONF); i++) {
struct tracefs_buffer_stat *tstat;
ssize_t entries, eread;
tstat = tracefs_instance_get_stat(NULL, i);
if (!tstat)
continue;
entries = tracefs_buffer_stat_entries(tstat);
eread = tracefs_buffer_stat_read_events(tstat);
if (!entries && !eread) {
tracefs_instance_put_stat(tstat);
continue;
}
printf("CPU: %d\en", i);;
printf("\etentries: %zd\en", entries);
printf("\etoverrun: %zd\en", tracefs_buffer_stat_overrun(tstat));
printf("\etcommit_overrun: %zd\en", tracefs_buffer_stat_commit_overrun(tstat));
printf("\etbytes: %zd\en", tracefs_buffer_stat_bytes(tstat));
printf("\etevent_timestamp: %lld\en", tracefs_buffer_stat_event_timestamp(tstat));
printf("\ettimestamp: %lld\en", tracefs_buffer_stat_timestamp(tstat));
printf("\etdropped_events: %zd\en", tracefs_buffer_stat_dropped_events(tstat));
printf("\etread_events: %zd\en", eread);
tracefs_instance_put_stat(tstat);
}
}
.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>
.fi
.if n \{\
.RE
.\}
.SH "REPORTING BUGS"
.sp
Report bugs to <\m[blue]\fBlinux\-trace\-devel@vger\&.kernel\&.org\fR\m[]\&\s-2\u[2]\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
linux-trace-devel@vger.kernel.org
.RS 4
\%mailto:linux-trace-devel@vger.kernel.org
.RE