1libtracecmd(3) 2============= 3 4NAME 5---- 6tracecmd_get_first_ts, tracecmd_add_ts_offset, tracecmd_get_tsc2nsec - Handle time stamps from a trace file. 7 8SYNOPSIS 9-------- 10[verse] 11-- 12*#include <trace-cmd.h>* 13 14unsigned long long *tracecmd_get_first_ts*(struct tracecmd_input pass:[*]_handle_); 15void *tracecmd_add_ts_offset*(struct tracecmd_input pass:[*]_handle_, long long _offset_); 16int *tracecmd_get_tsc2nsec*(struct tracecmd_input pass:[*]_handle_, int pass:[*]_mult_, int pass[*]_shift_, unsigned long long pass:[*]_offset_); 17-- 18 19DESCRIPTION 20----------- 21This set of APIs can be used to read tracing data from a trace file opened 22with _tracecmd_open()(3)_, _tracecmd_open_fd()(3)_ or _tracecmd_open_head()(3)_. 23 24The *tracecmd_get_first_ts()* function returns the time stamp of the first 25record in the _handle_. 26 27The *tracecmd_add_ts_offset()* function adds an offset to each of the records 28in the _handle_ that represents a trace file. This is useful for associating two 29different tracing files by their offset (for example a trace file from a host 30and a trace file from a guest that were not synchronized when created). 31 32The *tracecmd_get_tsc2nsec* returns the calculation values that convert the 33raw timestamp into nanoseconds. The parameters are pointers to the storage to save 34the values, or NULL to ignore them. The multiplier will be saved in _mult_, the 35shift value will be saved in _shift_, and the offset value will be saved in 36_offset_, if the corresponding parameters are not NULL. 37 38RETURN VALUE 39------------ 40The *tracecmd_get_first_ts()* function returns the timestamp of the first 41record in a trace file for the given _handle_. 42 43The *tracecmd_get_tsc2nsec*() returns 0 if the tracing clock supports the 44shift values and -1 otherwise. Note, that if the trace file has the TSC2NSEC 45option, the values returned in the parameters may still be valid even if the 46function itself returns -1. The return value only notes if the values will 47be used in the calculations of the given clock. 48 49EXAMPLE 50------- 51[source,c] 52-- 53#include <stdlib.h> 54#include <trace-cmd.h> 55 56static int print_events(struct tracecmd_input *handle, struct tep_record *record, int cpu, void *data) 57{ 58 static struct trace_seq seq; 59 struct tep_handle *tep = tracecmd_get_tep(handle); 60 const char *file = tracecmd_get_private(handle); 61 62 if (!seq.buffer) 63 trace_seq_init(&seq); 64 65 trace_seq_reset(&seq); 66 trace_seq_printf(&seq, "%s: ", file); 67 tep_print_event(tep, &seq, record, "%6.1000d [%03d] %s-%d %s: %s\n", 68 TEP_PRINT_TIME, TEP_PRINT_CPU, TEP_PRINT_COMM, TEP_PRINT_PID, 69 TEP_PRINT_NAME, TEP_PRINT_INFO); 70 trace_seq_terminate(&seq); 71 trace_seq_do_printf(&seq); 72 return 0; 73} 74 75int main(int argc, char **argv) 76{ 77 struct tracecmd_input **handles = NULL; 78 unsigned long long ts, first_ts = 0; 79 unsigned long long offset; 80 int multi; 81 int shift; 82 int nr_handles = 0; 83 int ret; 84 int i; 85 86 if (argc < 2) { 87 printf("usage: %s trace.dat [trace.dat ...]\n", argv[0]); 88 exit(-1); 89 } 90 91 for (i = 1; i < argc; i++) { 92 handles = realloc(handles, sizeof(*handles) * (nr_handles + 1)); 93 if (!handles) 94 exit(-1); 95 handles[nr_handles] = tracecmd_open(argv[i], 0); 96 if (!handles[nr_handles]) 97 exit(-1); 98 99 ret = tracecmd_get_tsc2nsec(handles[nr_handles], &multi, &shift, &offset); 100 if (!ret) 101 printf(" %s has tsc2nsec calculations of mult:%d shift:%d offset:%lld\n", 102 argv[i], multi, shift, offset); 103 tracecmd_set_private(handles[nr_handles], argv[i]); 104 ts = tracecmd_get_first_ts(handles[nr_handles]); 105 if (!first_ts || ts < first_ts) 106 first_ts = ts; 107 nr_handles++; 108 } 109 110 /* Set the time stamp to start at the first record found */ 111 for (i = 0; i < nr_handles; i++) 112 tracecmd_add_ts_offset(handles[i], -first_ts); 113 114 tracecmd_iterate_events_multi(handles, nr_handles, print_events, NULL); 115 116 for (i = 0; i < nr_handles; i++) 117 tracecmd_close(handles[i]); 118 free(handles); 119} 120-- 121FILES 122----- 123[verse] 124-- 125*trace-cmd.h* 126 Header file to include in order to have access to the library APIs. 127*-ltracecmd* 128 Linker switch to add when building a program that uses the library. 129-- 130 131SEE ALSO 132-------- 133_libtracefs(3)_, 134_libtraceevent(3)_, 135_trace-cmd(1)_ 136_trace-cmd.dat(5)_ 137 138AUTHOR 139------ 140[verse] 141-- 142*Steven Rostedt* <rostedt@goodmis.org> 143*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com> 144-- 145REPORTING BUGS 146-------------- 147Report bugs to <linux-trace-devel@vger.kernel.org> 148 149LICENSE 150------- 151libtracecmd is Free Software licensed under the GNU LGPL 2.1 152 153RESOURCES 154--------- 155https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ 156 157COPYING 158------- 159Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under 160the terms of the GNU Public License (GPL). 161