1libtracecmd(3) 2============= 3 4NAME 5---- 6tracecmd_open, tracecmd_open_fd, tracecmd_open_head, tracecmd_init_data, 7tracecmd_close - Open and close a trace file. 8 9SYNOPSIS 10-------- 11[verse] 12-- 13*#include <trace-cmd.h>* 14 15struct tracecmd_input pass:[*]*tracecmd_open*(const char pass:[*]_file_, int _flags_); 16struct tracecmd_input pass:[*]*tracecmd_open_fd*(int _fd_, int _flags_); 17struct tracecmd_input pass:[*]*tracecmd_open_head*(const char pass:[*]_file_, int _flags_); 18int *tracecmd_init_data*(struct tracecmd_input pass:[*]_handle_); 19void *tracecmd_close*(struct tracecmd_input pass:[*]_handle_); 20-- 21 22DESCRIPTION 23----------- 24This set of APIs can be used to open and close a trace file recorded by 25_trace-cmd(1)_ and containing tracing information from ftrace, the official 26Linux kernel tracer. The opened file is represented by a _tracecmd_input_ 27structure, all other library APIs that work with the file require a pointer 28to the structure. The APIs for opening a trace file have a _flag_ input 29parameter, which controls how the file will be opened and parsed. The _flag_ 30is a combination of these options: 31 32 TRACECMD_FL_LOAD_NO_PLUGINS - Do not load any plugins 33 TRACECMD_FL_LOAD_NO_SYSTEM_PLUGINS - Do not load system wide plugins, load only "local only" 34 plugins from user's home directory. 35 36The _tracecmd_open()_ function opens a given trace _file_, parses the 37metadata headers from the file, allocates and initializes а _tracecmd_input_ 38handler structure representing the file. It also initializes the handler 39for reading trace data from the file. The returned handler is ready to be 40used with _tracecmd_read__ APIs. 41 42The _tracecmd_open_fd()_ function does the same as _tracecmd_open()_, but 43works with a file descriptor to a trace file, opened for reading. 44 45The _tracecmd_open_head()_ function is the same as _tracecmd_open()_, but 46does not initialize the handler for reading trace data. It reads and parses 47the metadata headers only. The _tracecmd_init_data()_ should be used before 48using the _tracecmd_read__ APIs. 49 50The _tracecmd_init_data()_ function initializes a _handle_, allocated with 51_tracecmd_open_head()_, for reading trace data from the file associated with 52it. This API must be called before any of the _tracecmd_read__ APIs. 53 54The _tracecmd_close()_ function frees a _handle_, pointer to tracecmd_input 55structure, previously allocated with _tracecmd_open()_, _tracecmd_open_fd()_ 56or _tracecmd_open_head()_ APIs. 57 58RETURN VALUE 59------------ 60The _tracecmd_open()_, _tracecmd_open_fd()_ and _tracecmd_open_head()_ 61functions return a pointer to tracecmd_input structure or NULL in case of 62an error. The returned structure must be free with _tracecmd_close()_. 63Note that if _tracecmd_open_fd()_ is used to allocate a tracecmd_input handler, 64when _tracecmd_close()_ is called to close it, that fd will be closed also. 65 66The _tracecmd_init_data()_ function returns -1 in case of an error or 670 otherwise. 68 69EXAMPLE 70------- 71[source,c] 72-- 73The are two different use patterns for opening and reading trace data from 74a trace file, which can be used depending on the use case. 75 761. Open and initialise the trace file in а single step: 77 78#include <trace-cmd.h> 79... 80struct tracecmd_input *handle = tracecmd_open("trace.dat"); 81 if (!handle) { 82 /* Failed to open trace.dat file */ 83 } 84... 85 /* Read tracing data from the file, using the handle */ 86... 87 tracecmd_close(handle); 88... 89int fd; 90 fd = = open("trace.dat", O_RDONLY); 91 if (fd < 0) { 92 /* Failed to open trace file for reading */ 93 } 94 handle = tracecmd_open_fd(fd); 95 if (!handle) { 96 close(fd); 97 /* Failed to initialise handler for reading the trace file */ 98 } 99... 100 /* Read tracing data from the file, using the handle */ 101... 102 tracecmd_close(handle); 103... 104 1052. Open and initialise the trace file in two steps. This allows to perform 106some processing based on metadata, read from the file, before initialising 107the trace data for reading. Example for such use case is when opening multiple 108trace files recorded in a same trace session. In that case timestamps of all 109trace events must be adjusted based on the information from the file's metadata 110and before reading the trace data. 111 112#include <trace-cmd.h> 113... 114struct tracecmd_input *handle = tracecmd_open_head("trace.dat"); 115 if (!handle) { 116 /* Failed to open trace.dat file */ 117 } 118... 119 /* do some processing, before initialising the trace data for reading */ 120... 121 if (tracecmd_init_data(handle) < 0) { 122 /* Failed to initialize hadle for reading the trace data */ 123 } 124... 125 /* Read tracing data from the file, using the handle */ 126... 127 tracecmd_close(handle); 128... 129-- 130FILES 131----- 132[verse] 133-- 134*trace-cmd.h* 135 Header file to include in order to have access to the library APIs. 136*-ltracecmd* 137 Linker switch to add when building a program that uses the library. 138-- 139 140SEE ALSO 141-------- 142_libtracefs(3)_, 143_libtraceevent(3)_, 144_trace-cmd(1)_ 145_trace-cmd.dat(5)_ 146 147AUTHOR 148------ 149[verse] 150-- 151*Steven Rostedt* <[email protected]> 152*Tzvetomir Stoyanov* <[email protected]> 153-- 154REPORTING BUGS 155-------------- 156Report bugs to <[email protected]> 157 158LICENSE 159------- 160libtracecmd is Free Software licensed under the GNU LGPL 2.1 161 162RESOURCES 163--------- 164https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ 165 166COPYING 167------- 168Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under 169the terms of the GNU Public License (GPL). 170