1LIBTRACECMD(3) libtracefs Manual LIBTRACECMD(3)
2
6 tracecmd_open, tracecmd_open_fd, tracecmd_open_head,
7 tracecmd_init_data, tracecmd_close, tracecmd_set_private,
8 tracecmd_get_private - Open and close a trace file.
9
11 #include <trace-cmd.h>
12 struct tracecmd_input *tracecmd_open(const char *file, int flags);
14 struct tracecmd_input *tracecmd_open_fd(int fd, int flags);
15 struct tracecmd_input *tracecmd_open_head(const char *file, int flags);
16 int tracecmd_init_data(struct tracecmd_input *handle);
17 void tracecmd_close(struct tracecmd_input *handle);
18 void tracecmd_set_private(struct tracecmd_input *handle, void *data);
19 void *tracecmd_get_private(struct tracecmd_input *handle);
20
22 This set of APIs can be used to open and close a trace file recorded by
23 trace-cmd(1) and containing tracing information from ftrace, the
24 official Linux kernel tracer. The opened file is represented by a
25 tracecmd_input structure, all other library APIs that work with the
26 file require a pointer to the structure. The APIs for opening a trace
27 file have a flag input parameter, which controls how the file will be
28 opened and parsed. The flag is a combination of these options:
29 TRACECMD_FL_LOAD_NO_PLUGINS - Do not load any plugins
31 TRACECMD_FL_LOAD_NO_SYSTEM_PLUGINS - Do not load system wide plugins, load only "local only"
32 plugins from user's home directory.
33 The tracecmd_open() function opens a given trace file, parses the
35 metadata headers from the file, allocates and initializes а
36 tracecmd_input handler structure representing the file. It also
37 initializes the handler for reading trace data from the file. The
38 returned handler is ready to be used with tracecmd_read_ APIs.
39 The tracecmd_open_fd() function does the same as tracecmd_open(), but
41 works with a file descriptor to a trace file, opened for reading.
42 The tracecmd_open_head() function is the same as tracecmd_open(), but
44 does not initialize the handler for reading trace data. It reads and
45 parses the metadata headers only. The tracecmd_init_data() should be
46 used before using the tracecmd_read_ APIs.
47 The tracecmd_init_data() function initializes a handle, allocated with
49 tracecmd_open_head(), for reading trace data from the file associated
50 with it. This API must be called before any of the tracecmd_read_ APIs.
51 The tracecmd_close() function frees a handle, pointer to tracecmd_input
53 structure, previously allocated with tracecmd_open(),
54 tracecmd_open_fd() or tracecmd_open_head() APIs.
55 The tracecmd_set_private() function allows to add specific data to the
57 handle that can be retrieved later.
58 The tracecmd_get_private() function will retrieve the data set by
60 tracecmd_set_private() for the given handle.
61
63 The tracecmd_open(), tracecmd_open_fd() and tracecmd_open_head()
64 functions return a pointer to tracecmd_input structure or NULL in case
65 of an error. The returned structure must be free with tracecmd_close().
66 Note that if tracecmd_open_fd() is used to allocate a tracecmd_input
67 handler, when tracecmd_close() is called to close it, that fd will be
68 closed also.
69 The tracecmd_init_data() function returns -1 in case of an error or 0
71 otherwise.
72 The tracecmd_get_private() returns the data set by
74 tracecmd_set_private().
75
77 The are two different use patterns for opening and reading trace data from
78 a trace file, which can be used depending on the use case.
79 1. Open and initialise the trace file in а single step:
81 #include <stdlib.h>
83 #include <trace-cmd.h>
84 static int print_events(struct tracecmd_input *handle, struct tep_record *record, int cpu, void *data)
86 {
87 static struct trace_seq seq;
88 struct tep_handle *tep = tracecmd_get_tep(handle);
89 const char *file = tracecmd_get_private(handle);
90 if (!seq.buffer)
92 trace_seq_init(&seq);
93 trace_seq_reset(&seq);
95 trace_seq_printf(&seq, "%s: ", file);
96 tep_print_event(tep, &seq, record, "%6.1000d [%03d] %s-%d %s: %s\n",
97 TEP_PRINT_TIME, TEP_PRINT_CPU, TEP_PRINT_COMM, TEP_PRINT_PID,
98 TEP_PRINT_NAME, TEP_PRINT_INFO);
99 trace_seq_terminate(&seq);
100 trace_seq_do_printf(&seq);
101 return 0;
102 }
103 int main(int argc, char **argv)
105 {
106 struct tracecmd_input *handle;
107 if (argc < 2) {
109 printf("usage: %s trace.dat\n", argv[0]);
110 exit(-1);
111 }
112 handle = tracecmd_open(argv[i], 0);
114 if (!handle)
115 exit(-1);
116 tracecmd_set_private(handles[nr_handles], argv[i]);
118 tracecmd_iterate_events(handles, NULL, 0, print_events, NULL);
119 tracecmd_close(handle);
121 }
122 2. Open and initialise the trace file in two steps. This allows to perform
124 some processing based on metadata, read from the file, before initialising
125 the trace data for reading. Example for such use case is when opening multiple
126 trace files recorded in a same trace session. In that case timestamps of all
127 trace events must be adjusted based on the information from the file's metadata
128 and before reading the trace data.
129 #include <trace-cmd.h>
131 ...
132 struct tracecmd_input *handle = tracecmd_open_head("trace.dat");
133 if (!handle) {
134 /* Failed to open trace.dat file */
135 }
136 ...
137 /* do some processing, before initialising the trace data for reading */
138 ...
139 if (tracecmd_init_data(handle) < 0) {
140 /* Failed to initialize hadle for reading the trace data */
141 }
142 ...
143 /* Read tracing data from the file, using the handle */
144 ...
145 tracecmd_close(handle);
146 ...
147
149 trace-cmd.h
150 Header file to include in order to have access to the library APIs.
151 -ltracecmd
152 Linker switch to add when building a program that uses the library.
153
155 libtracefs(3), libtraceevent(3), trace-cmd(1) trace-cmd.dat(5)
156
158 Steven Rostedt <rostedt@goodmis.org[1]>
159 Tzvetomir Stoyanov <tz.stoyanov@gmail.com[2]>
160
162 Report bugs to <linux-trace-devel@vger.kernel.org[3]>
163
165 libtracecmd is Free Software licensed under the GNU LGPL 2.1
166
168 https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
169
171 Copyright (C) 2020 VMware, Inc. Free use of this software is granted
172 under the terms of the GNU Public License (GPL).
173
175 1. rostedt@goodmis.org
176 mailto:rostedt@goodmis.org
177 2. tz.stoyanov@gmail.com
179 mailto:tz.stoyanov@gmail.com
180 3. linux-trace-devel@vger.kernel.org
182 mailto:linux-trace-devel@vger.kernel.org
183libtracefs 07/20/2023 LIBTRACECMD(3)