1libtracefs(3) 2============= 3 4NAME 5---- 6tracefs_cpu_read_buf, tracefs_cpu_buffered_read_buf, tracefs_cpu_flush_buf 7- Reading trace_pipe_raw data returning a kbuffer 8 9SYNOPSIS 10-------- 11[verse] 12-- 13*#include <tracefs.h>* 14 15struct kbuffer pass:[*]*tracefs_cpu_read_buf*(struct tracefs_cpu pass:[*]_tcpu_, bool _nonblock_); 16struct kbuffer pass:[*]*tracefs_cpu_buffered_read_buf*(struct tracefs_cpu pass:[*]_tcpu_, bool _nonblock_); 17struct kbuffer pass:[*]*tracefs_cpu_flush_buf*(struct tracefs_cpu pass:[*]_tcpu_); 18-- 19 20DESCRIPTION 21----------- 22This set of APIs can be used to read the raw data from the trace_pipe_raw 23files in the tracefs file system and return a kbuffer structure to read it with. 24 25The *tracefs_cpu_read_buf()* reads the trace_pipe_raw files associated to _tcpu_ 26and returns a kbuffer structure that can be used to iterate the events. 27If _nonblock_ is set, and there's no data available, it will return immediately. 28Otherwise depending on how _tcpu_ was opened, it will block. If _tcpu_ was 29opened with nonblock set, then this _nonblock_ will make no difference. 30 31The *tracefs_cpu_buffered_read_buf()* is basically the same as *tracefs_cpu_read_buf()* 32except that it uses a pipe through splice to buffer reads. This will batch 33reads keeping the reading from the ring buffer less intrusive to the system, 34as just reading all the time can cause quite a disturbance. Note, one 35difference between this and *tracefs_cpu_read()* is that it will read only in 36sub buffer pages. If the ring buffer has not filled a page, then it will not 37return anything, even with _nonblock_ set. Calls to *tracefs_cpu_flush_buf()* 38or *tracefs_cpu_flush()* should be done to read the rest of the file at the 39end of the trace. 40 41The *tracefs_cpu_flush_buf()* reads the trace_pipe_raw file associated by the 42_tcpu_ and puts it into _buffer_, which must be the size of the sub buffer 43which is retrieved. This should be called at the end of tracing 44to get the rest of the data. This call will convert the file descriptor of 45trace_pipe_raw into non-blocking mode. 46 47RETURN VALUE 48------------ 49The functions *tracefs_cpu_read_buf()*, tracefs_cpu_buffered_read_buf()* and 50*tracefs_cpu_flush()* returns a kbuffer descriptor that can be iterated 51over to find the events. Note, this descriptor is part of the tracefs_cpu structure 52and should not be freed. It will be freed. It returns NULL on error or if nonblock 53is set and there are no events available. In the case of no events, errno will be 54set with EAGAIN. 55 56EXAMPLE 57------- 58[source,c] 59-- 60#include <stdlib.h> 61#include <ctype.h> 62#include <tracefs.h> 63 64static void read_page(struct tep_handle *tep, struct kbuffer *kbuf) 65{ 66 static struct trace_seq seq; 67 struct tep_record record; 68 69 if (seq.buffer) 70 trace_seq_reset(&seq); 71 else 72 trace_seq_init(&seq); 73 74 while ((record.data = kbuffer_read_event(kbuf, &record.ts))) { 75 record.size = kbuffer_event_size(kbuf); 76 kbuffer_next_event(kbuf, NULL); 77 tep_print_event(tep, &seq, &record, 78 "%s-%d %9d\t%s: %s\n", 79 TEP_PRINT_COMM, 80 TEP_PRINT_PID, 81 TEP_PRINT_TIME, 82 TEP_PRINT_NAME, 83 TEP_PRINT_INFO); 84 trace_seq_do_printf(&seq); 85 trace_seq_reset(&seq); 86 } 87} 88 89int main (int argc, char **argv) 90{ 91 struct tracefs_cpu *tcpu; 92 struct tep_handle *tep; 93 struct kbuffer *kbuf; 94 int cpu; 95 96 if (argc < 2 || !isdigit(argv[1][0])) { 97 printf("usage: %s cpu\n\n", argv[0]); 98 exit(-1); 99 } 100 101 cpu = atoi(argv[1]); 102 103 tep = tracefs_local_events(NULL); 104 if (!tep) { 105 perror("Reading trace event formats"); 106 exit(-1); 107 } 108 109 tcpu = tracefs_cpu_open(NULL, cpu, 0); 110 if (!tcpu) { 111 perror("Open CPU 0 file"); 112 exit(-1); 113 } 114 115 while ((kbuf = tracefs_cpu_buffered_read_buf(tcpu, true))) { 116 read_page(tep, kbuf); 117 } 118 119 kbuf = tracefs_cpu_flush_buf(tcpu); 120 if (kbuf) 121 read_page(tep, kbuf); 122 123 tracefs_cpu_close(tcpu); 124 tep_free(tep); 125 126 return 0; 127} 128-- 129FILES 130----- 131[verse] 132-- 133*tracefs.h* 134 Header file to include in order to have access to the library APIs. 135*-ltracefs* 136 Linker switch to add when building a program that uses the library. 137-- 138 139SEE ALSO 140-------- 141*tracefs_cpu_open*(3) 142*tracefs_cpu_close*(3) 143*tracefs_cpu_read*(3) 144*tracefs_cpu_buffered_read*(3) 145*tracefs_cpu_flush*(3) 146*libtracefs*(3), 147*libtraceevent*(3), 148*trace-cmd*(1) 149 150AUTHOR 151------ 152[verse] 153-- 154*Steven Rostedt* <rostedt@goodmis.org> 155-- 156REPORTING BUGS 157-------------- 158Report bugs to <linux-trace-devel@vger.kernel.org> 159 160LICENSE 161------- 162libtracefs is Free Software licensed under the GNU LGPL 2.1 163 164RESOURCES 165--------- 166https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ 167 168COPYING 169------- 170Copyright \(C) 2022 Google, Inc. Free use of this software is granted under 171the terms of the GNU Public License (GPL). 172