'\" t
.\"     Title: libtraceevent
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 01/13/2024
.\"    Manual: libtraceevent Manual
.\"    Source: libtraceevent
.\"  Language: English
.\"
.TH "LIBTRACEEVENT" "3" "01/13/2024" "libtraceevent" "libtraceevent 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"
kbuffer_timestamp, kbuffer_subbuf_timestamp \- Functions that read various data of a kbuffer descriptor
.SH "SYNOPSIS"
.sp
.nf
\fB#include <kbuffer\&.h>\fR

unsigned long long \fBkbuffer_timestamp\fR(struct kbuffer *\fIkbuf\fR);
unsigned long long \fBkbuffer_subbuf_timestamp\fR(struct kbuffer *\fIkbuf\fR, void *\fIsubbuf\fR);
.fi
.SH "DESCRIPTION"
.sp
The function \fBkbuffer_timestamp()\fR returns the timestamp of the current event of \fIkbuf\fR\&.
.sp
The function \fBkbuffer_subbuf_timestamp()\fR returns the timestamp for the sub\-buffer that was loaded in \fIkbuf\fR\&. This usually is (but not guaranteed to be) the timestamp of the first event on the sub\-buffer\&.
.sp
The function \fBkbuffer_start_of_data()\fR returns the offset of where the delta
.SH "RETURN VALUE"
.sp
\fBkbuffer_read_event()\fR returns the event that the \fIkbuf\fR descriptor is currently at, or NULL if the last event was passed (by \fBkbuffer_next_event()\fR)\&.
.sp
\fBkbuffer_next_event()\fR returns the next event after the current event or NULL if there are no more events\&.
.sp
\fBkbuffer_read_at_offset()\fR returns the event at a given \fIoffset\fR from the start of the sub\-buffer stored in \fIkbuf\fR, or NULL if there exists no event\&. Note, \fIoffset\fR only needs to be an offset that lands on the record, or is at the start of it\&. It does not need to be exactly at the beginning of the record\&.
.sp
\fBkbuffer_missed_events()\fR returns 0 if there were no missed events before loaded sub\-buffer\&. Returns \-1 if there were an unknown number of missed events, or if the number of missed events is known, that number will be returned\&.
.sp
\fBkbuffer_event_size()\fR returns the size of the data payload of the current event of \fIkbuf\fR\&.
.sp
\fBkbuffer_curr_size()\fR returns the size of the entire record of the current event of \fIkbuf\fR\&. This includes the size of the meta data for that record\&.
.sp
\fBkbuf_curr_offset()\fR returns the offset of the current record from the beginning of the \fIkbuf\fR sub\-buffer\&.
.sp
\fBkbuf_curr_index()\fR returns the index of the current record from the beginning of the \fIkbuf\fR data section\&.
.SH "EXAMPLE"
.sp
.if n \{\
.RS 4
.\}
.nf
#include <stdio\&.h>
#include <stdlib\&.h>
#include <fcntl\&.h>
#include <unistd\&.h>
#include <sys/stat\&.h>

#include <kbuffer\&.h>

int main (int argc, char **argv)
{
        unsigned long long ts;
        struct kbuffer *kbuf;
        struct stat st;
        char *buf;
        void *event;
        int save_offset = \-1;
        int record_size;
        int offset;
        int index;
        int size;
        int ret;
        int fd;
        int i = 0;

        if (argc < 2) {
                printf("usage: %s raw\-subbuffer\-page\en", argv[0]);
                printf(" Try: dd count=1 bs=4096 if=/sys/kernel/tracing/per_cpu/cpu0/trace_pipe_raw of=/tmp/file\en");
                exit(0);
        }

        if (stat(argv[1], &st) < 0) {
                perror("stat");
                exit(\-1);
        }

        buf = malloc(st\&.st_size);
        if (!buf) {
                perror("Allocating buffer");
                exit(\-1);
        }

        fd = open(argv[1], O_RDONLY);
        if (fd < 0) {
                perror(argv[1]);
                exit(\-1);
        }

        ret = read(fd, buf, st\&.st_size);
        if (ret < 0) {
                perror("Reading buffer");
                exit(\-1);
        }
        close(fd);

        kbuf = kbuffer_alloc(KBUFFER_ENDIAN_SAME_AS_HOST,
                             KBUFFER_LSIZE_SAME_AS_HOST);
        if (!kbuf) {
                perror("Creating kbuffer");
                exit(\-1);
        }
        ret = kbuffer_load_subbuffer(kbuf, buf);
        if (ret < 0) {
                perror("Loading sub bufer");
                exit(\-1);
        }

        if (kbuffer_subbuffer_size(kbuf) > st\&.st_size) {
                fprintf(stderr, "kbuffer is bigger than raw size %d > %ld\en",
                        kbuffer_subbuffer_size(kbuf), st\&.st_size);
                exit(\-1);
        }

        ret = kbuffer_missed_events(kbuf);
        if (ret) {
                if (ret > 0)
                        printf("Missed %d events before this buffer\en", ret);
                else
                        printf("Missed unknown number of events before this buffer\en");
        }
        do {
                event = kbuffer_read_event(kbuf, &ts);
                if (event) {
                        record_size = kbuffer_curr_size(kbuf);
                        offset = kbuffer_curr_offset(kbuf);
                        index = kbuffer_curr_index(kbuf);
                        size = kbuffer_event_size(kbuf);

                        if (i == 20)
                                save_offset = offset;
                        printf(" event %3d ts:%lld\etrecord_size:%d size:%d\etindex:%d offset:%d\en",
                               i++, ts, record_size, size, index, offset);
                        event = kbuffer_next_event(kbuf, NULL);
                }
        } while (event);

        if (!event)
                printf("Finished sub buffer\en");

        if (save_offset > 0) {
                event = kbuffer_read_at_offset(kbuf, save_offset, &ts);
                if (!event) {
                        fprintf(stderr, "Funny, can\*(Aqt find event 20 at offset %d\en", save_offset);
                        exit(\-1);
                }
                record_size = kbuffer_curr_size(kbuf);
                offset = kbuffer_curr_offset(kbuf);
                index = kbuffer_curr_index(kbuf);
                size = kbuffer_event_size(kbuf);

                printf("\en saved event 20 ts:%lld\etrecord_size:%d size:%d\etindex:%d offset:%d\en\en",
                       ts, record_size, size, index, offset);
        }
        kbuffer_free(kbuf);

        return 0;
}
.fi
.if n \{\
.RE
.\}
.SH "FILES"
.sp
.if n \{\
.RS 4
.\}
.nf
\fBevent\-parse\&.h\fR
        Header file to include in order to have access to the library APIs\&.
\fB\-ltraceevent\fR
        Linker switch to add when building a program that uses the library\&.
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
\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>, author of \fBlibtraceevent\fR\&.
.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
libtraceevent is Free Software licensed under the GNU LGPL 2\&.1
.SH "RESOURCES"
.sp
\m[blue]\fBhttps://git\&.kernel\&.org/pub/scm/libs/libtrace/libtraceevent\&.git/\fR\m[]
.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