1libtracefs(3) 2============= 3 4NAME 5---- 6tracefs_hist_start, tracefs_hist_destroy, tracefs_hist_pause, 7tracefs_hist_continue, tracefs_hist_reset - Pause, continue, or clear an existing histogram 8 9SYNOPSIS 10-------- 11[verse] 12-- 13*#include <tracefs.h>* 14 15int *tracefs_hist_start*(struct tracefs_instance pass:[*]_instance_, struct tracefs_hist pass:[*]_hist_); 16int *tracefs_hist_destroy*(struct tracefs_instance pass:[*]_instance_, struct tracefs_hist pass:[*]_hist_); 17int *tracefs_hist_pause*(struct tracefs_instance pass:[*]_instance_, struct tracefs_hist pass:[*]_hist_); 18int *tracefs_hist_continue*(struct tracefs_instance pass:[*]_instance_, struct tracefs_hist pass:[*]_hist_); 19int *tracefs_hist_reset*(struct tracefs_instance pass:[*]_instance_, struct tracefs_hist pass:[*]_hist_); 20 21-- 22 23DESCRIPTION 24----------- 25 26*tracefs_hist_start()* is called to actually start the histogram _hist_. 27The _instance_ is the instance to start the histogram in, NULL if it 28should start at the top level. 29 30*tracefs_hist_pause()* is called to pause the histogram _hist_. 31The _instance_ is the instance to pause the histogram in, NULL if it 32is in the top level. 33 34*tracefs_hist_continue()* is called to continue a paused histogram _hist_. 35The _instance_ is the instance to continue the histogram, NULL if it 36is in the top level. 37 38*tracefs_hist_reset()* is called to clear / reset the histogram _hist_. 39The _instance_ is the instance to clear the histogram, NULL if it 40is in the top level. 41 42*tracefs_hist_destroy()* is called to delete the histogram where it will no longer 43exist. The _instance_ is the instance to delete the histogram from, NULL if it 44is in the top level. 45 46RETURN VALUE 47------------ 48All the return zero on success or -1 on error. 49 50EXAMPLE 51------- 52[source,c] 53-- 54#include <stdlib.h> 55#include <tracefs.h> 56 57enum commands { 58 START, 59 PAUSE, 60 CONT, 61 RESET, 62 DELETE, 63 SHOW, 64}; 65 66int main (int argc, char **argv, char **env) 67{ 68 struct tracefs_instance *instance; 69 struct tracefs_hist *hist; 70 struct tep_handle *tep; 71 enum commands cmd; 72 char *cmd_str; 73 int ret; 74 75 if (argc < 2) { 76 fprintf(stderr, "usage: %s command\n", argv[0]); 77 exit(-1); 78 } 79 80 cmd_str = argv[1]; 81 82 if (!strcmp(cmd_str, "start")) 83 cmd = START; 84 else if (!strcmp(cmd_str, "pause")) 85 cmd = PAUSE; 86 else if (!strcmp(cmd_str, "cont")) 87 cmd = CONT; 88 else if (!strcmp(cmd_str, "reset")) 89 cmd = RESET; 90 else if (!strcmp(cmd_str, "delete")) 91 cmd = DELETE; 92 else if (!strcmp(cmd_str, "show")) 93 cmd = SHOW; 94 else { 95 fprintf(stderr, "Unknown command %s\n", cmd_str); 96 exit(-1); 97 } 98 99 tep = tracefs_local_events(NULL); 100 if (!tep) { 101 perror("Reading tracefs"); 102 exit(-1); 103 } 104 105 instance = tracefs_instance_create("hist_test"); 106 if (!instance) { 107 fprintf(stderr, "Failed instance create\n"); 108 exit(-1); 109 } 110 111 hist = tracefs_hist_alloc_2d(tep, "kmem", "kmalloc", 112 "call_site",TRACEFS_HIST_KEY_SYM, 113 "bytes_req", 0); 114 if (!hist) { 115 fprintf(stderr, "Failed hist create\n"); 116 exit(-1); 117 } 118 119 ret = tracefs_hist_add_value(hist, "bytes_alloc"); 120 ret |= tracefs_hist_add_sort_key(hist, "bytes_req"); 121 ret |= tracefs_hist_add_sort_key(hist, "bytes_alloc"); 122 123 ret |= tracefs_hist_sort_key_direction(hist, "bytes_alloc", 124 TRACEFS_HIST_SORT_DESCENDING); 125 if (ret) { 126 fprintf(stderr, "Failed modifying histogram\n"); 127 exit(-1); 128 } 129 130 tracefs_error_clear(instance); 131 132 switch (cmd) { 133 case START: 134 ret = tracefs_hist_start(instance, hist); 135 if (ret) { 136 char *err = tracefs_error_last(instance); 137 if (err) 138 fprintf(stderr, "\n%s\n", err); 139 } 140 break; 141 case PAUSE: 142 ret = tracefs_hist_pause(instance, hist); 143 break; 144 case CONT: 145 ret = tracefs_hist_continue(instance, hist); 146 break; 147 case RESET: 148 ret = tracefs_hist_reset(instance, hist); 149 break; 150 case DELETE: 151 ret = tracefs_hist_destroy(instance, hist); 152 break; 153 case SHOW: { 154 char *content; 155 content = tracefs_event_file_read(instance, "kmem", "kmalloc", 156 "hist", NULL); 157 ret = content ? 0 : -1; 158 if (content) { 159 printf("%s\n", content); 160 free(content); 161 } 162 break; 163 } 164 } 165 if (ret) 166 fprintf(stderr, "Failed: command\n"); 167 exit(ret); 168} 169 170-- 171 172FILES 173----- 174[verse] 175-- 176*tracefs.h* 177 Header file to include in order to have access to the library APIs. 178*-ltracefs* 179 Linker switch to add when building a program that uses the library. 180-- 181 182SEE ALSO 183-------- 184*libtracefs*(3), 185*libtraceevent*(3), 186*trace-cmd*(1), 187*tracefs_hist_alloc*(3), 188*tracefs_hist_alloc_2d*(3), 189*tracefs_hist_alloc_nd*(3), 190*tracefs_hist_free*(3), 191*tracefs_hist_add_key*(3), 192*tracefs_hist_add_value*(3), 193*tracefs_hist_add_name*(3), 194*tracefs_hist_start*(3), 195*tracefs_hist_destory*(3), 196*tracefs_hist_add_sort_key*(3), 197*tracefs_hist_sort_key_direction*(3) 198 199AUTHOR 200------ 201[verse] 202-- 203*Steven Rostedt* <[email protected]> 204*Tzvetomir Stoyanov* <[email protected]> 205*sameeruddin shaik* <[email protected]> 206-- 207REPORTING BUGS 208-------------- 209Report bugs to <[email protected]> 210 211LICENSE 212------- 213libtracefs is Free Software licensed under the GNU LGPL 2.1 214 215RESOURCES 216--------- 217https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ 218 219COPYING 220------- 221Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under 222the terms of the GNU Public License (GPL). 223