1LIBTRACEEVENT(3)             libtraceevent Manual             LIBTRACEEVENT(3)
2
3
4

NAME

6       kbuffer_read_event, kbuffer_next_event, kbuffer_missed_events,
7       kbuffer_event_size, kbuffer_curr_size, kbuffer_curr_offset,
8       kbuffer_curr_index - Functions to read through the kbuffer sub buffer.
9

SYNOPSIS

11       #include <kbuffer.h>
12
13       void *kbuffer_read_event(struct kbuffer *kbuf, unsigned long long *ts);
14       void *kbuffer_next_event(struct kbuffer *kbuf, unsigned long long *ts);
15       void *kbuffer_read_at_offset(struct kbuffer *kbuf, int offset, unsigned long long *ts);
16       int kbuffer_missed_events(struct kbuffer *kbuf);
17       int kbuffer_event_size(struct kbuffer *kbuf);
18       int kbuffer_curr_size(struct kbuffer *kbuf);
19       int kbuffer_curr_offset(struct kbuffer *kbuf);
20       int kbuffer_curr_index(struct kbuffer *kbuf);
21

DESCRIPTION

23       The function kbuffer_read_event() reads the next event in the kbuf
24       descriptor and if ts is non NULL, will place its timestamp into it.
25       This does not modify the kbuf descriptor, and calling this function
26       mulitple times will return the same result.
27
28       The function kbuffer_next_event() will return the next event in the
29       kbuf descriptor. It will also set the ts to the timestamp of the
30       returned event. NULL is returned if there are no more events and ts
31       will be undefined. Note, if this is called directly after a
32       kbuffer_load_subbuffer() then it will likely give an unexpected result,
33       as it will return the second event and not the first event. Usually
34       this function is only used to move to the next event and to know if
35       there’s any more events to read, and kbuffer_read_event() is always
36       called first.
37
38       The function kbuffer_read_at_offset() returns the event located at a
39       given offset from the beginning of the sub-buffer. This offset can be
40       retrieved by kbuffer_curr_offset(). If ts points to an unsigned long
41       long, then it will be set to the event at the given offset’s timestamp.
42
43       If the sub-buffer had missed events before it, then
44       kbuffer_missed_events() will return the non zero. If it returns -1,
45       that means there were missed events, but the exact number of missed
46       events is unknown. If it returns a positive number, then the number of
47       missed events is the return value.
48
49       The kbuffer_event_size() function returns the size of the data portion
50       of the current event (the one that would be returned by
51       kbuffer_read_event().
52
53       The kbuffer_curr_size() function returns the entire record size of the
54       current event (the one that would be returned by kbuffer_read_event().
55       The difference here is that the return value includes the size of the
56       event record meta data that is not part of what is returned by
57       kbuffer_read_event().
58
59       The kbuffer_curr_offset() function returns the offset from the
60       beginning of the sub-buffer of where the current event’s meta data for
61       the record begins. The first event will not be at offset zero. This
62       offset can be used to retrieve the event with kbuffer_read_at_offset().
63
64       The kbuffer_curr_index() function returns the index from the beginning
65       of the data portion of the sub-buffer where the current evnet’s meta
66       data is located. The first event will likely be zero, but may not be if
67       there’s a timestamp attached to it.
68

RETURN VALUE

70       kbuffer_read_event() returns the event that the kbuf descriptor is
71       currently at, or NULL if the last event was passed (by
72       kbuffer_next_event()).
73
74       kbuffer_next_event() returns the next event after the current event or
75       NULL if there are no more events.
76
77       kbuffer_read_at_offset() returns the event at a given offset from the
78       start of the sub-buffer stored in kbuf, or NULL if there exists no
79       event. Note, offset only needs to be an offset that lands on the
80       record, or is at the start of it. It does not need to be exactly at the
81       beginning of the record.
82
83       kbuffer_missed_events() returns 0 if there were no missed events before
84       loaded sub-buffer. Returns -1 if there were an unknown number of missed
85       events, or if the number of missed events is known, that number will be
86       returned.
87
88       kbuffer_event_size() returns the size of the data payload of the
89       current event of kbuf.
90
91       kbuffer_curr_size() returns the size of the entire record of the
92       current event of kbuf. This includes the size of the meta data for that
93       record.
94
95       kbuf_curr_offset() returns the offset of the current record from the
96       beginning of the kbuf sub-buffer.
97
98       kbuf_curr_index() returns the index of the current record from the
99       beginning of the kbuf data section.
100

EXAMPLE

102           #include <stdio.h>
103           #include <stdlib.h>
104           #include <fcntl.h>
105           #include <unistd.h>
106           #include <sys/stat.h>
107
108           #include <kbuffer.h>
109
110           int main (int argc, char **argv)
111           {
112                   unsigned long long ts;
113                   struct kbuffer *kbuf;
114                   struct stat st;
115                   char *buf;
116                   void *event;
117                   int save_offset = -1;
118                   int record_size;
119                   int offset;
120                   int index;
121                   int size;
122                   int ret;
123                   int fd;
124                   int i = 0;
125
126                   if (argc < 2) {
127                           printf("usage: %s raw-subbuffer-page\n", argv[0]);
128                           printf(" Try: dd count=1 bs=4096 if=/sys/kernel/tracing/per_cpu/cpu0/trace_pipe_raw of=/tmp/file\n");
129                           exit(0);
130                   }
131
132                   if (stat(argv[1], &st) < 0) {
133                           perror("stat");
134                           exit(-1);
135                   }
136
137                   buf = malloc(st.st_size);
138                   if (!buf) {
139                           perror("Allocating buffer");
140                           exit(-1);
141                   }
142
143                   fd = open(argv[1], O_RDONLY);
144                   if (fd < 0) {
145                           perror(argv[1]);
146                           exit(-1);
147                   }
148
149                   ret = read(fd, buf, st.st_size);
150                   if (ret < 0) {
151                           perror("Reading buffer");
152                           exit(-1);
153                   }
154                   close(fd);
155
156                   kbuf = kbuffer_alloc(KBUFFER_ENDIAN_SAME_AS_HOST,
157                                        KBUFFER_LSIZE_SAME_AS_HOST);
158                   if (!kbuf) {
159                           perror("Creating kbuffer");
160                           exit(-1);
161                   }
162                   ret = kbuffer_load_subbuffer(kbuf, buf);
163                   if (ret < 0) {
164                           perror("Loading sub bufer");
165                           exit(-1);
166                   }
167
168                   if (kbuffer_subbuffer_size(kbuf) > st.st_size) {
169                           fprintf(stderr, "kbuffer is bigger than raw size %d > %ld\n",
170                                   kbuffer_subbuffer_size(kbuf), st.st_size);
171                           exit(-1);
172                   }
173
174                   ret = kbuffer_missed_events(kbuf);
175                   if (ret) {
176                           if (ret > 0)
177                                   printf("Missed %d events before this buffer\n", ret);
178                           else
179                                   printf("Missed unknown number of events before this buffer\n");
180                   }
181                   do {
182                           event = kbuffer_read_event(kbuf, &ts);
183                           if (event) {
184                                   record_size = kbuffer_curr_size(kbuf);
185                                   offset = kbuffer_curr_offset(kbuf);
186                                   index = kbuffer_curr_index(kbuf);
187                                   size = kbuffer_event_size(kbuf);
188
189                                   if (i == 20)
190                                           save_offset = offset;
191                                   printf(" event %3d ts:%lld\trecord_size:%d size:%d\tindex:%d offset:%d\n",
192                                          i++, ts, record_size, size, index, offset);
193                                   event = kbuffer_next_event(kbuf, NULL);
194                           }
195                   } while (event);
196
197                   if (!event)
198                           printf("Finished sub buffer\n");
199
200                   if (save_offset > 0) {
201                           event = kbuffer_read_at_offset(kbuf, save_offset, &ts);
202                           if (!event) {
203                                   fprintf(stderr, "Funny, can't find event 20 at offset %d\n", save_offset);
204                                   exit(-1);
205                           }
206                           record_size = kbuffer_curr_size(kbuf);
207                           offset = kbuffer_curr_offset(kbuf);
208                           index = kbuffer_curr_index(kbuf);
209                           size = kbuffer_event_size(kbuf);
210
211                           printf("\n saved event 20 ts:%lld\trecord_size:%d size:%d\tindex:%d offset:%d\n\n",
212                                  ts, record_size, size, index, offset);
213                   }
214                   kbuffer_free(kbuf);
215
216                   return 0;
217           }
218

FILES

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

SEE ALSO

226       libtraceevent(3), trace-cmd(1)
227

AUTHOR

229           Steven Rostedt <rostedt@goodmis.org[1]>, author of libtraceevent.
230

REPORTING BUGS

232       Report bugs to <linux-trace-devel@vger.kernel.org[2]>
233

LICENSE

235       libtraceevent is Free Software licensed under the GNU LGPL 2.1
236

RESOURCES

238       https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/
239

NOTES

241        1. rostedt@goodmis.org
242           mailto:rostedt@goodmis.org
243
244        2. linux-trace-devel@vger.kernel.org
245           mailto:linux-trace-devel@vger.kernel.org
246
247
248
249libtraceevent 1.7.2               07/20/2023                  LIBTRACEEVENT(3)
Impressum