1libtraceevent(3) 2================ 3 4NAME 5---- 6kbuffer_read_event, kbuffer_next_event, kbuffer_missed_events, kbuffer_event_size, kbuffer_curr_size, 7kbuffer_curr_offset, kbuffer_curr_index - 8Functions to read through the kbuffer sub buffer. 9 10SYNOPSIS 11-------- 12[verse] 13-- 14*#include <kbuffer.h>* 15 16void pass:[*]*kbuffer_read_event*(struct kbuffer pass:[*]_kbuf_, unsigned long long pass:[*]_ts_); 17void pass:[*]*kbuffer_next_event*(struct kbuffer pass:[*]_kbuf_, unsigned long long pass:[*]_ts_); 18void pass:[*]*kbuffer_read_at_offset*(struct kbuffer pass:[*]_kbuf_, int _offset_, unsigned long long pass:[*]_ts_); 19int *kbuffer_missed_events*(struct kbuffer pass:[*]_kbuf_); 20int *kbuffer_event_size*(struct kbuffer pass:[*]_kbuf_); 21int *kbuffer_curr_size*(struct kbuffer pass:[*]_kbuf_); 22int *kbuffer_curr_offset*(struct kbuffer pass:[*]_kbuf_); 23int *kbuffer_curr_index*(struct kbuffer pass:[*]_kbuf_); 24-- 25 26DESCRIPTION 27----------- 28The function *kbuffer_read_event()* reads the next event in the _kbuf_ descriptor 29and if _ts_ is non NULL, will place its timestamp into it. This does not modify the _kbuf_ 30descriptor, and calling this function mulitple times will return the same result. 31 32The function *kbuffer_next_event()* will return the next event in the _kbuf_ descriptor. 33It will also set the _ts_ to the timestamp of the returned event. NULL is returned 34if there are no more events and _ts_ will be undefined. Note, if this is called directly 35after a *kbuffer_load_subbuffer()* then it will likely give an unexpected result, as it 36will return the second event and not the first event. Usually this function is only used 37to move to the next event and to know if there's any more events to read, and 38*kbuffer_read_event()* is always called first. 39 40The function *kbuffer_read_at_offset()* returns the event located at a given _offset_ from 41the beginning of the sub-buffer. This offset can be retrieved by *kbuffer_curr_offset()*. 42If _ts_ points to an unsigned long long, then it will be set to the event at the given 43offset's timestamp. 44 45If the sub-buffer had missed events before it, then *kbuffer_missed_events()* will return 46the non zero. If it returns -1, that means there were missed events, but the exact number 47of missed events is unknown. If it returns a positive number, then the number of missed events 48is the return value. 49 50The *kbuffer_event_size()* function returns the size of the data portion of the current event 51(the one that would be returned by *kbuffer_read_event()*. 52 53The *kbuffer_curr_size()* function returns the entire record size of the current event 54(the one that would be returned by *kbuffer_read_event()*. The difference here is that the 55return value includes the size of the event record meta data that is not part of what 56is returned by *kbuffer_read_event()*. 57 58The *kbuffer_curr_offset()* function returns the offset from the beginning of the sub-buffer 59of where the current event's meta data for the record begins. The first event will 60not be at offset zero. This offset can be used to retrieve the event with 61*kbuffer_read_at_offset()*. 62 63The *kbuffer_curr_index()* function returns the index from the beginning of the data 64portion of the sub-buffer where the current evnet's meta data is located. 65The first event will likely be zero, but may not be if there's a timestamp attached to it. 66 67RETURN VALUE 68------------ 69*kbuffer_read_event()* returns the event that the _kbuf_ descriptor is currently at, 70or NULL if the last event was passed (by *kbuffer_next_event()*). 71 72*kbuffer_next_event()* returns the next event after the current event or NULL if there 73are no more events. 74 75*kbuffer_read_at_offset()* returns the event at a given _offset_ from the start of 76the sub-buffer stored in _kbuf_, or NULL if there exists no event. Note, _offset_ 77only needs to be an offset that lands on the record, or is at the start of it. It does 78not need to be exactly at the beginning of the record. 79 80*kbuffer_missed_events()* returns 0 if there were no missed events before loaded sub-buffer. 81Returns -1 if there were an unknown number of missed events, or if the number of missed events 82is known, that number will be returned. 83 84*kbuffer_event_size()* returns the size of the data payload of the current event of _kbuf_. 85 86*kbuffer_curr_size()* returns the size of the entire record of the current event of _kbuf_. 87This includes the size of the meta data for that record. 88 89*kbuf_curr_offset()* returns the offset of the current record from the beginning of the _kbuf_ 90sub-buffer. 91 92*kbuf_curr_index()* returns the index of the current record from the beginning of the _kbuf_ 93data section. 94 95EXAMPLE 96------- 97[source,c] 98-- 99#include <stdio.h> 100#include <stdlib.h> 101#include <fcntl.h> 102#include <unistd.h> 103#include <sys/stat.h> 104 105#include <kbuffer.h> 106 107int main (int argc, char **argv) 108{ 109 unsigned long long ts; 110 struct kbuffer *kbuf; 111 struct stat st; 112 char *buf; 113 void *event; 114 int save_offset = -1; 115 int record_size; 116 int offset; 117 int index; 118 int size; 119 int ret; 120 int fd; 121 int i = 0; 122 123 if (argc < 2) { 124 printf("usage: %s raw-subbuffer-page\n", argv[0]); 125 printf(" Try: dd count=1 bs=4096 if=/sys/kernel/tracing/per_cpu/cpu0/trace_pipe_raw of=/tmp/file\n"); 126 exit(0); 127 } 128 129 if (stat(argv[1], &st) < 0) { 130 perror("stat"); 131 exit(-1); 132 } 133 134 buf = malloc(st.st_size); 135 if (!buf) { 136 perror("Allocating buffer"); 137 exit(-1); 138 } 139 140 fd = open(argv[1], O_RDONLY); 141 if (fd < 0) { 142 perror(argv[1]); 143 exit(-1); 144 } 145 146 ret = read(fd, buf, st.st_size); 147 if (ret < 0) { 148 perror("Reading buffer"); 149 exit(-1); 150 } 151 close(fd); 152 153 kbuf = kbuffer_alloc(KBUFFER_ENDIAN_SAME_AS_HOST, 154 KBUFFER_LSIZE_SAME_AS_HOST); 155 if (!kbuf) { 156 perror("Creating kbuffer"); 157 exit(-1); 158 } 159 ret = kbuffer_load_subbuffer(kbuf, buf); 160 if (ret < 0) { 161 perror("Loading sub bufer"); 162 exit(-1); 163 } 164 165 if (kbuffer_subbuffer_size(kbuf) > st.st_size) { 166 fprintf(stderr, "kbuffer is bigger than raw size %d > %ld\n", 167 kbuffer_subbuffer_size(kbuf), st.st_size); 168 exit(-1); 169 } 170 171 ret = kbuffer_missed_events(kbuf); 172 if (ret) { 173 if (ret > 0) 174 printf("Missed %d events before this buffer\n", ret); 175 else 176 printf("Missed unknown number of events before this buffer\n"); 177 } 178 do { 179 event = kbuffer_read_event(kbuf, &ts); 180 if (event) { 181 record_size = kbuffer_curr_size(kbuf); 182 offset = kbuffer_curr_offset(kbuf); 183 index = kbuffer_curr_index(kbuf); 184 size = kbuffer_event_size(kbuf); 185 186 if (i == 20) 187 save_offset = offset; 188 printf(" event %3d ts:%lld\trecord_size:%d size:%d\tindex:%d offset:%d\n", 189 i++, ts, record_size, size, index, offset); 190 event = kbuffer_next_event(kbuf, NULL); 191 } 192 } while (event); 193 194 if (!event) 195 printf("Finished sub buffer\n"); 196 197 if (save_offset > 0) { 198 event = kbuffer_read_at_offset(kbuf, save_offset, &ts); 199 if (!event) { 200 fprintf(stderr, "Funny, can't find event 20 at offset %d\n", save_offset); 201 exit(-1); 202 } 203 record_size = kbuffer_curr_size(kbuf); 204 offset = kbuffer_curr_offset(kbuf); 205 index = kbuffer_curr_index(kbuf); 206 size = kbuffer_event_size(kbuf); 207 208 printf("\n saved event 20 ts:%lld\trecord_size:%d size:%d\tindex:%d offset:%d\n\n", 209 ts, record_size, size, index, offset); 210 } 211 kbuffer_free(kbuf); 212 213 return 0; 214} 215-- 216FILES 217----- 218[verse] 219-- 220*event-parse.h* 221 Header file to include in order to have access to the library APIs. 222*-ltraceevent* 223 Linker switch to add when building a program that uses the library. 224-- 225 226SEE ALSO 227-------- 228*libtraceevent*(3), *trace-cmd*(1) 229 230AUTHOR 231------ 232[verse] 233-- 234*Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*. 235-- 236REPORTING BUGS 237-------------- 238Report bugs to <linux-trace-devel@vger.kernel.org> 239 240LICENSE 241------- 242libtraceevent is Free Software licensed under the GNU LGPL 2.1 243 244RESOURCES 245--------- 246https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/ 247