1libtracefs(3) 2============= 3 4NAME 5---- 6tracefs_instance_get_subbuf_size, tracefs_instance_set_subbuf_size - Helper functions for working with ring buffer sub buffers. 7 8SYNOPSIS 9-------- 10[verse] 11-- 12*#include <tracefs.h>* 13 14size_t *tracefs_instance_get_subbuf_size*(struct tracefs_instance pass:[*]_instance_); 15int *tracefs_instance_set_subbuf_size*(struct tracefs_instance pass:[*]_instance_, size_t _size_); 16-- 17 18DESCRIPTION 19----------- 20Helper functions for working with the sub-buffers of the tracing ring buffer. 21The tracing ring buffer is broken up into *sub-buffers*. An event can not be 22bigger than the data section of the sub-buffer (see *tep_get_sub_buffer_data_size*(3)). 23By default, the ring buffer uses the architectures *page_size* as the default 24size of the sub-buffer, but this can be limiting if there is a need for large 25events, for example, the application wants to write large strings into 26the trace_marker file. 27 28The *tracefs_instance_get_subbuf_size()* returns the current size in kilobytes 29fo the ring buffer sub-buffers. 30 31The *tracefs_instance_set_subbuf_size()* will write the size in kilobytes of 32what the new sub-buffer size should be. Note, that this is only a hint to what 33the minimum sub-buffer size should be. It also does not take into account the 34meta-data that is used by the sub-buffer, so the size written should be no less 35than 16 bytes more than the maximum event size that will be used. The kernel 36will likely make the sub-buffer size larger than specified, as it may need to 37align the size for implementation purposes. 38 39RETURN VALUE 40------------ 41The *tracefs_instance_get_subbuf_size()* returns the size of the current 42sub-buffer for the given _instance_ ring buffer or -1 on error. 43 44The *tracefs_instance_set_subbuf_size()* will return 0 if it successfully set 45the _instance_ ring buffer sub-buffer size in kilobytes, or -1 on error. 46 47EXAMPLE 48------- 49[source,c] 50-- 51#include <stdlib.h> 52#include <tracefs.h> 53#include <errno.h> 54 55int main(int argc, char **argv) 56{ 57 struct tep_handle *tep; 58 ssize_t save_subsize; 59 ssize_t subsize; 60 char *trace; 61 char buf[3000]; 62 int meta_size; 63 int ret; 64 int i; 65 66 tep = tep_alloc(); 67 ret = tracefs_load_headers(NULL, tep); 68 tep_free(tep); 69 70 if (ret < 0) { 71 perror("reading headers"); 72 exit(-1); 73 } 74 75 meta_size = tep_get_sub_buffer_size(tep) - tep_get_sub_buffer_data_size(tep); 76 77 save_subsize = tracefs_instance_get_subbuf_size(NULL); 78 if (save_subsize < 0) { 79 printf("Changing sub-buffer size not available\n"); 80 exit(-1); 81 } 82 83 subsize = save_subsize * 1024; 84 85 /* Have at least 4 writes fit on a sub-buffer */ 86 if (subsize - meta_size < sizeof(buf) *4 ) { 87 subsize = ((sizeof(buf) * 4 + meta_size) + 1023) / 1024; 88 tracefs_instance_set_subbuf_size(NULL, subsize); 89 } 90 91 for (i = 0; i < sizeof(buf) - 1; i++) { 92 buf[i] = '0' + i % 10; 93 } 94 buf[i] = '\0'; 95 96 tracefs_instance_clear(NULL); 97 98 for (i = 0; i < 4; i++) { 99 ret = tracefs_printf(NULL, "%s\n", buf); 100 if (ret < 0) 101 perror("write"); 102 } 103 104 trace = tracefs_instance_file_read(NULL, "trace", NULL); 105 printf("%s\n", trace); 106 free(trace); 107 108 printf("Buffer size was: %zd * 1024\n", 109 tracefs_instance_get_subbuf_size(NULL)); 110 111 tracefs_instance_set_subbuf_size(NULL, save_subsize); 112} 113-- 114FILES 115----- 116[verse] 117-- 118*tracefs.h* 119 Header file to include in order to have access to the library APIs. 120*-ltracefs* 121 Linker switch to add when building a program that uses the library. 122-- 123 124SEE ALSO 125-------- 126*libtracefs*(3), 127*libtraceevent*(3), 128*trace-cmd*(1) 129 130AUTHOR 131------ 132[verse] 133-- 134*Steven Rostedt* <rostedt@goodmis.org> 135*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com> 136-- 137REPORTING BUGS 138-------------- 139Report bugs to <linux-trace-devel@vger.kernel.org> 140 141LICENSE 142------- 143libtracefs is Free Software licensed under the GNU LGPL 2.1 144 145RESOURCES 146--------- 147https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ 148 149COPYING 150------- 151Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under 152the terms of the GNU Public License (GPL). 153