1LIBTRACECMD(3)                 libtracefs Manual                LIBTRACECMD(3)
2
3
4

NAME

6       tracecmd_open, tracecmd_open_fd, tracecmd_open_head,
7       tracecmd_init_data, tracecmd_close - Open and close a trace file.
8

SYNOPSIS

10       #include <trace-cmd.h>
11
12       struct tracecmd_input *tracecmd_open(const char *file, int flags);
13       struct tracecmd_input *tracecmd_open_fd(int fd, int flags);
14       struct tracecmd_input *tracecmd_open_head(const char *file, int flags);
15       int tracecmd_init_data(struct tracecmd_input *handle);
16       void tracecmd_close(struct tracecmd_input *handle);
17

DESCRIPTION

19       This set of APIs can be used to open and close a trace file recorded by
20       trace-cmd(1) and containing tracing information from ftrace, the
21       official Linux kernel tracer. The opened file is represented by a
22       tracecmd_input structure, all other library APIs that work with the
23       file require a pointer to the structure. The APIs for opening a trace
24       file have a flag input parameter, which controls how the file will be
25       opened and parsed. The flag is a combination of these options:
26
27           TRACECMD_FL_LOAD_NO_PLUGINS - Do not load any plugins
28           TRACECMD_FL_LOAD_NO_SYSTEM_PLUGINS - Do not load system wide plugins, load only "local only"
29                                                  plugins from user's home directory.
30
31       The tracecmd_open() function opens a given trace file, parses the
32       metadata headers from the file, allocates and initializes а
33       tracecmd_input handler structure representing the file. It also
34       initializes the handler for reading trace data from the file. The
35       returned handler is ready to be used with tracecmd_read_ APIs.
36
37       The tracecmd_open_fd() function does the same as tracecmd_open(), but
38       works with a file descriptor to a trace file, opened for reading.
39
40       The tracecmd_open_head() function is the same as tracecmd_open(), but
41       does not initialize the handler for reading trace data. It reads and
42       parses the metadata headers only. The tracecmd_init_data() should be
43       used before using the tracecmd_read_ APIs.
44
45       The tracecmd_init_data() function initializes a handle, allocated with
46       tracecmd_open_head(), for reading trace data from the file associated
47       with it. This API must be called before any of the tracecmd_read_ APIs.
48
49       The tracecmd_close() function frees a handle, pointer to tracecmd_input
50       structure, previously allocated with tracecmd_open(),
51       tracecmd_open_fd() or tracecmd_open_head() APIs.
52

RETURN VALUE

54       The tracecmd_open(), tracecmd_open_fd() and tracecmd_open_head()
55       functions return a pointer to tracecmd_input structure or NULL in case
56       of an error. The returned structure must be free with tracecmd_close().
57       Note that if tracecmd_open_fd() is used to allocate a tracecmd_input
58       handler, when tracecmd_close() is called to close it, that fd will be
59       closed also.
60
61       The tracecmd_init_data() function returns -1 in case of an error or 0
62       otherwise.
63

EXAMPLE

65           The are two different use patterns for opening and reading trace data from
66           a trace file, which can be used depending on the use case.
67
68           1. Open and initialise the trace file in а single step:
69
70           #include <trace-cmd.h>
71           ...
72           struct tracecmd_input *handle = tracecmd_open("trace.dat");
73                   if (!handle) {
74                           /* Failed to open trace.dat file */
75                   }
76           ...
77                   /* Read tracing data from the file, using the handle */
78           ...
79                   tracecmd_close(handle);
80           ...
81           int fd;
82                   fd = = open("trace.dat", O_RDONLY);
83                   if (fd < 0) {
84                           /* Failed to open trace file for reading */
85                   }
86                   handle = tracecmd_open_fd(fd);
87                   if (!handle) {
88                           close(fd);
89                           /* Failed to initialise handler for reading the trace file */
90                   }
91           ...
92                   /* Read tracing data from the file, using the handle */
93           ...
94                   tracecmd_close(handle);
95           ...
96
97           2. Open and initialise the trace file in two steps. This allows to perform
98           some processing based on metadata, read from the file, before initialising
99           the trace data for reading. Example for such use case is when opening multiple
100           trace files recorded in a same trace session. In that case timestamps of all
101           trace events must be adjusted based on the information from  the file's metadata
102           and before reading the trace data.
103
104           #include <trace-cmd.h>
105           ...
106           struct tracecmd_input *handle = tracecmd_open_head("trace.dat");
107                   if (!handle) {
108                           /* Failed to open trace.dat file */
109                   }
110           ...
111                   /* do some processing, before initialising the trace data for reading */
112           ...
113                   if (tracecmd_init_data(handle) < 0) {
114                           /* Failed to initialize hadle for reading the trace data */
115                   }
116           ...
117                   /* Read tracing data from the file, using the handle */
118           ...
119                   tracecmd_close(handle);
120           ...
121

FILES

123           trace-cmd.h
124                   Header file to include in order to have access to the library APIs.
125           -ltracecmd
126                   Linker switch to add when building a program that uses the library.
127

SEE ALSO

129       libtracefs(3), libtraceevent(3), trace-cmd(1) trace-cmd.dat(5)
130

AUTHOR

132           Steven Rostedt <rostedt@goodmis.org[1]>
133           Tzvetomir Stoyanov <tz.stoyanov@gmail.com[2]>
134

REPORTING BUGS

136       Report bugs to <linux-trace-devel@vger.kernel.org[3]>
137

LICENSE

139       libtracecmd is Free Software licensed under the GNU LGPL 2.1
140

RESOURCES

142       https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
143

COPYING

145       Copyright (C) 2020 VMware, Inc. Free use of this software is granted
146       under the terms of the GNU Public License (GPL).
147

NOTES

149        1. rostedt@goodmis.org
150           mailto:rostedt@goodmis.org
151
152        2. tz.stoyanov@gmail.com
153           mailto:tz.stoyanov@gmail.com
154
155        3. linux-trace-devel@vger.kernel.org
156           mailto:linux-trace-devel@vger.kernel.org
157
158
159
160libtracefs                        03/29/2021                    LIBTRACECMD(3)
Impressum