1libtracecmd(3) 2============= 3 4NAME 5---- 6tracecmd_read_cpu_first, tracecmd_read_data, tracecmd_read_at, 7tracecmd_free_record, tracecmd_get_tep - Read recorded events from a trace file. 8 9SYNOPSIS 10-------- 11[verse] 12-- 13*#include <trace-cmd.h>* 14 15struct tep_record pass:[*]*tracecmd_read_cpu_first*(struct tracecmd_input pass:[*]_handle_, int _cpu_); 16struct tep_record pass:[*]*tracecmd_read_data*(struct tracecmd_input pass:[*]_handle_, int _cpu_); 17struct tep_record pass:[*]*tracecmd_read_at*(struct tracecmd_input pass:[*]_handle_, unsigned long long _offset_, int pass:[*]_cpu_); 18void *tracecmd_free_record*(struct tep_record pass:[*]_record_); 19struct tep_handle pass:[*]*tracecmd_get_tep*(struct tracecmd_input pass:[*]_handle_); 20-- 21 22DESCRIPTION 23----------- 24This set of APIs can be used to read tracing data from a trace file opened 25with *tracecmd_open()(3)*, *tracecmd_open_fd()(3)* or *tracecmd_open_head()(3)*. 26 27The *tracecmd_read_cpu_first()* function reads the first trace record 28for a given _cpu_ from a trace file associated with _handle_. The returned 29record must be freed with *tracecmd_free_record()*. 30 31The *tracecmd_read_data()* function reads the next trace record for 32a given _cpu_ from a trace file associated with _handle_ and increments 33the read location pointer, so that the next call to *tracecmd_read_data()* 34will not read the same record again. The returned record must be freed 35with *tracecmd_free_record()*. 36 37The *tracecmd_read_at()* function reads a trace record from a specific 38_offset_ within the file associated with _handle_. The CPU on which the 39recorded event occurred is stored in the _cpu_. The function does not 40change the current read location pointer. The returned record must be 41freed with *tracecmd_free_record()*. 42 43The *tracecmd_free_record()* function frees a _record_ returned by any 44of the _tracecmd_read__ APIs. 45 46The *tracecmd_get_tep()* function returns a tep context for a given 47_handle_. 48 49RETURN VALUE 50------------ 51The *tracecmd_read_cpu_first()*, *tracecmd_read_data()* and 52*tracecmd_read_at()* functions return a pointer to struct tep_record or 53NULL in case of an error.The returned record must be freed with 54*tracecmd_free_record()*. 55 56The *tracecmd_get_tep()* function returns a pointer to tep context or 57NULL if there is no tep context for the given _handle_. The returned 58tep pointer must *not* be freed. 59 60EXAMPLE 61------- 62[source,c] 63-- 64#include <trace-cmd.h> 65... 66struct tracecmd_input *handle = tracecmd_open("trace.dat"); 67 if (!handle) { 68 /* Failed to open trace.dat file */ 69 } 70... 71unsigned long long offset = 0; 72struct tep_record *rec; 73int cpu = 0; 74 rec = tracecmd_read_cpu_first(handle, cpu); 75 while (rec) { 76 ... 77 if ( /* some interesting record noticed */) { 78 /* store the offset of the interesting record */ 79 offset = rec->offset; 80 } 81 ... 82 tracecmd_free_record(rec); 83 rec = tracecmd_read_data(handle, cpu); 84 } 85 ... 86 if (offset) { 87 rec = tracecmd_read_at(handle, offset, &cpu); 88 if (rec) { 89 /* Got record at offset on cpu */ 90 ... 91 tracecmd_free_record(rec); 92 } 93 } 94 95... 96 tracecmd_close(hadle); 97 98-- 99FILES 100----- 101[verse] 102-- 103*trace-cmd.h* 104 Header file to include in order to have access to the library APIs. 105*-ltracecmd* 106 Linker switch to add when building a program that uses the library. 107-- 108 109SEE ALSO 110-------- 111*libtracefs(3)*, 112*libtraceevent(3)*, 113*trace-cmd(1)* 114*trace-cmd.dat(5)* 115 116AUTHOR 117------ 118[verse] 119-- 120*Steven Rostedt* <rostedt@goodmis.org> 121*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com> 122-- 123REPORTING BUGS 124-------------- 125Report bugs to <linux-trace-devel@vger.kernel.org> 126 127LICENSE 128------- 129libtracecmd is Free Software licensed under the GNU LGPL 2.1 130 131RESOURCES 132--------- 133https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ 134 135COPYING 136------- 137Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under 138the terms of the GNU Public License (GPL). 139