1libtracecmd(3) 2============= 3 4NAME 5---- 6tracecmd_buffer_instances, tracecmd_buffer_instance_name, tracecmd_buffer_instance_handle 7- Read tracing instances from a trace file. 8 9SYNOPSIS 10-------- 11[verse] 12-- 13*#include <trace-cmd.h>* 14 15int *tracecmd_buffer_instances*(struct tracecmd_input pass:[*]_handle_); 16const char pass:[*]*tracecmd_buffer_instance_name*(struct tracecmd_input pass:[*]_handle_, int _indx_); 17struct tracecmd_input pass:[*]*tracecmd_buffer_instance_handle*(struct tracecmd_input pass:[*]_handle_, int _indx_); 18-- 19 20DESCRIPTION 21----------- 22This set of APIs can be used to get information and read tracing data 23from tracing instances stored in a trace file. 24 25The _tracecmd_buffer_instances()_ function gets the number of tracing 26instances recorded in a trace file. The top instance is not counted. 27The _handle_ is a tracecmd_input handler returned by 28_tracecmd_open_head()_. 29 30The _tracecmd_buffer_instance_name()_ function gets the name of the 31tracing instance with given index _indx_, recorded in a trace file. 32The _indx_ is a number in the interval [0 .. count-1], where count 33is the number returned by _tracecmd_buffer_instances()_. The _handle_ 34is a tracecmd_input handler returned by _tracecmd_open_head()_. 35 36The _tracecmd_buffer_instance_handle()_ allocates and initializes a 37tracecmd_input handle, associated with trace instance with index 38_indx_ from a trace file. The _handle_ is a tracecmd_input handler 39returned by _tracecmd_open_head()_. The _indx_ is a number in the 40interval [0 .. count-1], where count is the number returned by 41_tracecmd_buffer_instances()_. 42 43RETURN VALUE 44------------ 45The _tracecmd_buffer_instances()_ function returns the number of tracing 46instances recorded in a trace file. 47 48The _tracecmd_buffer_instance_name()_ function returns a string, the name 49of a tracing instance, or NULL in case of an error The string must *not* 50be freed. 51 52The _tracecmd_buffer_instance_handle()_ function returns a pointer to 53newly allocated tracecmd_input handler or NULL in case if an error. The 54returned handler must be closed by _tracecmd_close()(3)_ 55 56EXAMPLE 57------- 58[source,c] 59-- 60#include <trace-cmd.h> 61... 62struct tracecmd_input *handle = tracecmd_open_head("trace.dat"); 63 if (!handle) { 64 /* Failed to open trace.dat file */ 65 } 66... 67int num = tracecmd_buffer_instances(handle); 68 69 while(num) { 70 struct tracecmd_input *h; 71 char *name; 72 73 name = tracecmd_buffer_instance_name(handle, num); 74 if (!name) { 75 /* Failed to get name of instance num */ 76 } 77 h = tracecmd_buffer_instance_handle(handle, num); 78 if (!h) { 79 /* Failed to initialize handler for instance num */ 80 } 81 82 ... 83 tracecmd_close(h); 84 num--; 85 } 86... 87 tracecmd_close(handle); 88 89-- 90FILES 91----- 92[verse] 93-- 94*trace-cmd.h* 95 Header file to include in order to have access to the library APIs. 96*-ltracecmd* 97 Linker switch to add when building a program that uses the library. 98-- 99 100SEE ALSO 101-------- 102_libtracefs(3)_, 103_libtraceevent(3)_, 104_trace-cmd(1)_ 105_trace-cmd.dat(5)_ 106 107AUTHOR 108------ 109[verse] 110-- 111*Steven Rostedt* <[email protected]> 112*Tzvetomir Stoyanov* <[email protected]> 113-- 114REPORTING BUGS 115-------------- 116Report bugs to <[email protected]> 117 118LICENSE 119------- 120libtracecmd is Free Software licensed under the GNU LGPL 2.1 121 122RESOURCES 123--------- 124https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ 125 126COPYING 127------- 128Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under 129the terms of the GNU Public License (GPL). 130