'\" 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_get_first_ts, tracecmd_add_ts_offset, tracecmd_get_tsc2nsec \- Handle time stamps from a trace file\&.
.SH "SYNOPSIS"
.sp
.nf
\fB#include <trace\-cmd\&.h>\fR

unsigned long long \fBtracecmd_get_first_ts\fR(struct tracecmd_input *\fIhandle\fR);
void \fBtracecmd_add_ts_offset\fR(struct tracecmd_input *\fIhandle\fR, long long \fIoffset\fR);
int \fBtracecmd_get_tsc2nsec\fR(struct tracecmd_input *\fIhandle\fR, int *\fImult\fR, int pass[*]\fIshift\fR, unsigned long long *\fIoffset\fR);
.fi
.SH "DESCRIPTION"
.sp
This set of APIs can be used to read tracing data from a trace file opened with \fItracecmd_open()(3)\fR, \fItracecmd_open_fd()(3)\fR or \fItracecmd_open_head()(3)\fR\&.
.sp
The \fBtracecmd_get_first_ts()\fR function returns the time stamp of the first record in the \fIhandle\fR\&.
.sp
The \fBtracecmd_add_ts_offset()\fR function adds an offset to each of the records in the \fIhandle\fR that represents a trace file\&. This is useful for associating two different tracing files by their offset (for example a trace file from a host and a trace file from a guest that were not synchronized when created)\&.
.sp
The \fBtracecmd_get_tsc2nsec\fR returns the calculation values that convert the raw timestamp into nanoseconds\&. The parameters are pointers to the storage to save the values, or NULL to ignore them\&. The multiplier will be saved in \fImult\fR, the shift value will be saved in \fIshift\fR, and the offset value will be saved in \fIoffset\fR, if the corresponding parameters are not NULL\&.
.SH "RETURN VALUE"
.sp
The \fBtracecmd_get_first_ts()\fR function returns the timestamp of the first record in a trace file for the given \fIhandle\fR\&.
.sp
The \fBtracecmd_get_tsc2nsec\fR() returns 0 if the tracing clock supports the shift values and \-1 otherwise\&. Note, that if the trace file has the TSC2NSEC option, the values returned in the parameters may still be valid even if the function itself returns \-1\&. The return value only notes if the values will be used in the calculations of the given clock\&.
.SH "EXAMPLE"
.sp
.if n \{\
.RS 4
.\}
.nf
#include <stdlib\&.h>
#include <trace\-cmd\&.h>

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);
        const char *file = tracecmd_get_private(handle);

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

        trace_seq_reset(&seq);
        trace_seq_printf(&seq, "%s: ", 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;
}

int main(int argc, char **argv)
{
        struct tracecmd_input **handles = NULL;
        unsigned long long ts, first_ts = 0;
        unsigned long long offset;
        int multi;
        int shift;
        int nr_handles = 0;
        int ret;
        int i;

        if (argc < 2) {
                printf("usage: %s trace\&.dat [trace\&.dat \&.\&.\&.]\en", argv[0]);
                exit(\-1);
        }

        for (i = 1; 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])
                        exit(\-1);

                ret = tracecmd_get_tsc2nsec(handles[nr_handles], &multi, &shift, &offset);
                if (!ret)
                        printf(" %s has tsc2nsec calculations of mult:%d shift:%d offset:%lld\en",
                                argv[i], multi, shift, offset);
                tracecmd_set_private(handles[nr_handles], argv[i]);
                ts = tracecmd_get_first_ts(handles[nr_handles]);
                if (!first_ts || ts < first_ts)
                        first_ts = ts;
                nr_handles++;
        }

        /* Set the time stamp to start at the first record found */
        for (i = 0; i < nr_handles; i++)
                tracecmd_add_ts_offset(handles[i], \-first_ts);

        tracecmd_iterate_events_multi(handles, nr_handles, print_events, NULL);

        for (i = 0; i < nr_handles; i++)
                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
\fIlibtracefs(3)\fR, \fIlibtraceevent(3)\fR, \fItrace\-cmd(1)\fR \fItrace\-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