'\" 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_cpu_read_buf, tracefs_cpu_buffered_read_buf, tracefs_cpu_flush_buf \- Reading trace_pipe_raw data returning a kbuffer
.SH "SYNOPSIS"
.sp
.nf
\fB#include <tracefs\&.h>\fR

struct kbuffer *\fBtracefs_cpu_read_buf\fR(struct tracefs_cpu *\fItcpu\fR, bool \fInonblock\fR);
struct kbuffer *\fBtracefs_cpu_buffered_read_buf\fR(struct tracefs_cpu *\fItcpu\fR, bool \fInonblock\fR);
struct kbuffer *\fBtracefs_cpu_flush_buf\fR(struct tracefs_cpu *\fItcpu\fR);
.fi
.SH "DESCRIPTION"
.sp
This set of APIs can be used to read the raw data from the trace_pipe_raw files in the tracefs file system and return a kbuffer structure to read it with\&.
.sp
The \fBtracefs_cpu_read_buf()\fR reads the trace_pipe_raw files associated to \fItcpu\fR and returns a kbuffer structure that can be used to iterate the events\&. If \fInonblock\fR is set, and there\(cqs no data available, it will return immediately\&. Otherwise depending on how \fItcpu\fR was opened, it will block\&. If \fItcpu\fR was opened with nonblock set, then this \fInonblock\fR will make no difference\&.
.sp
The \fBtracefs_cpu_buffered_read_buf()\fR is basically the same as \fBtracefs_cpu_read_buf()\fR except that it uses a pipe through splice to buffer reads\&. This will batch reads keeping the reading from the ring buffer less intrusive to the system, as just reading all the time can cause quite a disturbance\&. Note, one difference between this and \fBtracefs_cpu_read()\fR is that it will read only in sub buffer pages\&. If the ring buffer has not filled a page, then it will not return anything, even with \fInonblock\fR set\&. Calls to \fBtracefs_cpu_flush_buf()\fR or \fBtracefs_cpu_flush()\fR should be done to read the rest of the file at the end of the trace\&.
.sp
The \fBtracefs_cpu_flush_buf()\fR reads the trace_pipe_raw file associated by the \fItcpu\fR and puts it into \fIbuffer\fR, which must be the size of the sub buffer which is retrieved\&. This should be called at the end of tracing to get the rest of the data\&. This call will convert the file descriptor of trace_pipe_raw into non\-blocking mode\&.
.SH "RETURN VALUE"
.sp
The functions \fBtracefs_cpu_read_buf()\fR, tracefs_cpu_buffered_read_buf()* and \fBtracefs_cpu_flush()\fR returns a kbuffer descriptor that can be iterated over to find the events\&. Note, this descriptor is part of the tracefs_cpu structure and should not be freed\&. It will be freed\&. It returns NULL on error or if nonblock is set and there are no events available\&. In the case of no events, errno will be set with EAGAIN\&.
.SH "EXAMPLE"
.sp
.if n \{\
.RS 4
.\}
.nf
#include <stdlib\&.h>
#include <ctype\&.h>
#include <tracefs\&.h>

static void read_page(struct tep_handle *tep, struct kbuffer *kbuf)
{
        static struct trace_seq seq;
        struct tep_record record;

        if (seq\&.buffer)
                trace_seq_reset(&seq);
        else
                trace_seq_init(&seq);

        while ((record\&.data = kbuffer_read_event(kbuf, &record\&.ts))) {
                record\&.size = kbuffer_event_size(kbuf);
                kbuffer_next_event(kbuf, NULL);
                tep_print_event(tep, &seq, &record,
                                "%s\-%d %9d\et%s: %s\en",
                                TEP_PRINT_COMM,
                                TEP_PRINT_PID,
                                TEP_PRINT_TIME,
                                TEP_PRINT_NAME,
                                TEP_PRINT_INFO);
                trace_seq_do_printf(&seq);
                trace_seq_reset(&seq);
        }
}

int main (int argc, char **argv)
{
        struct tracefs_cpu *tcpu;
        struct tep_handle *tep;
        struct kbuffer *kbuf;
        int cpu;

        if (argc < 2 || !isdigit(argv[1][0])) {
                printf("usage: %s cpu\en\en", argv[0]);
                exit(\-1);
        }

        cpu = atoi(argv[1]);

        tep = tracefs_local_events(NULL);
        if (!tep) {
                perror("Reading trace event formats");
                exit(\-1);
        }

        tcpu = tracefs_cpu_open(NULL, cpu, 0);
        if (!tcpu) {
                perror("Open CPU 0 file");
                exit(\-1);
        }

        while ((kbuf = tracefs_cpu_buffered_read_buf(tcpu, true))) {
                read_page(tep, kbuf);
        }

        kbuf = tracefs_cpu_flush_buf(tcpu);
        if (kbuf)
                read_page(tep, kbuf);

        tracefs_cpu_close(tcpu);
        tep_free(tep);

        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
\fBtracefs_cpu_open\fR(3) \fBtracefs_cpu_close\fR(3) \fBtracefs_cpu_read\fR(3) \fBtracefs_cpu_buffered_read\fR(3) \fBtracefs_cpu_flush\fR(3) \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) 2022 Google, 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