@@ -3,7 +3,8 @@ libtracecmd(3)
NAME
----
-tracecmd_open_head, tracecmd_close - Open and close a trace file.
+tracecmd_open, tracecmd_open_fd, tracecmd_open_head, tracecmd_init_data,
+tracecmd_close - Open and close a trace file.
SYNOPSIS
--------
@@ -11,7 +12,10 @@ SYNOPSIS
--
*#include <trace-cmd.h>*
+struct tracecmd_input pass:[*]*tracecmd_open*(const char pass:[*]_file_);
+struct tracecmd_input pass:[*]*tracecmd_open_fd*(int _fd_);
struct tracecmd_input pass:[*]*tracecmd_open_head*(const char pass:[*]_file_);
+int *tracecmd_init_data*(struct tracecmd_input pass:[*]_handle_);
void *tracecmd_close*(struct tracecmd_input pass:[*]_handle_);
--
@@ -23,32 +27,99 @@ Linux kernel tracer. The opened file is represented by a _tracecmd_input_
structure, all other library APIs that work with the file require a pointer
to the structure.
-The _tracecmd_open_head()_ function opens a given trace _file_, parses the
-headers from the file, allocates and initializes _tracecmd_input_ structure
-representing the file.
+The _tracecmd_open()_ function opens a given trace _file_, parses the
+metadata headers from the file, allocates and initializes а _tracecmd_input_
+handler structure representing the file. It also initializes the handler
+for reading trace data from the file. The returned handler is ready to be
+used with _tracecmd_read__ APIs.
+
+The _tracecmd_open_fd()_ function does the same as _tracecmd_open()_, but
+works with a file descriptor to a trace file, opened for reading.
+
+The _tracecmd_open_head()_ function is the same as _tracecmd_open()_, but
+does not initialize the handler for reading trace data. It reads and parses
+the metadata headers only. The _tracecmd_init_data()_ should be used before
+using the _tracecmd_read__ APIs.
+
+The _tracecmd_init_data()_ function initializes a _handle_, allocated with
+_tracecmd_open_head()_, for reading trace data from the file associated with
+it. This API must be called before any of the _tracecmd_read__ APIs.
The _tracecmd_close()_ function frees a _handle_, pointer to tracecmd_input
-structure, previously allocated with _tracecmd_open_head()_.
+structure, previously allocated with _tracecmd_open()_, _tracecmd_open_fd()_
+or _tracecmd_open_head()_ APIs.
RETURN VALUE
------------
-The _tracecmd_open_head()_ function returns a pointer to tracecmd_input
-structure or NULL in case of an error. The returned structure must be free
-with _tracecmd_close()_.
+The _tracecmd_open()_, _tracecmd_open_fd()_ and _tracecmd_open_head()_
+functions return a pointer to tracecmd_input structure or NULL in case of
+an error. The returned structure must be free with _tracecmd_close()_.
+Note that if _tracecmd_open_fd()_ is used to allocate a tracecmd_input handler,
+when _tracecmd_close()_ is called to close it, that fd will be closed also.
+
+The _tracecmd_init_data()_ function returns -1 in case of an error or
+0 otherwise.
EXAMPLE
-------
[source,c]
--
+The are two different use patterns for opening and reading trace data from
+a trace file, which can be used depending on the use case.
+
+1. Open and initialise the trace file in а single step:
+
#include <trace-cmd.h>
...
-struct tracecmd_input *handle = tracecmd_open_head("trace.dat");
+struct tracecmd_input *handle = tracecmd_open("trace.dat");
if (!handle) {
/* Failed to open trace.dat file */
}
+...
+ /* Read tracing data from the file, using the handle */
...
tracecmd_close(handle);
+...
+int fd;
+ fd = = open("trace.dat", O_RDONLY);
+ if (fd < 0) {
+ /* Failed to open trace file for reading */
+ }
+ handle = tracecmd_open_fd(fd);
+ if (!handle) {
+ close(fd);
+ /* Failed to initialise handler for reading the trace file */
+ }
+...
+ /* Read tracing data from the file, using the handle */
+...
+ tracecmd_close(handle);
+...
+2. Open and initialise the trace file in two steps. This allows to perform
+some processing based on metadata, read from the file, before initialising
+the trace data for reading. Example for such use case is when opening multiple
+trace files recorded in a same trace session. In that case timestamps of all
+trace events must be adjusted based on the information from the file's metadata
+and before reading the trace data.
+
+#include <trace-cmd.h>
+...
+struct tracecmd_input *handle = tracecmd_open_head("trace.dat");
+ if (!handle) {
+ /* Failed to open trace.dat file */
+ }
+...
+ /* do some processing, before initialising the trace data for reading */
+...
+ if (tracecmd_init_data(handle) < 0) {
+ /* Failed to initialize hadle for reading the trace data */
+ }
+...
+ /* Read tracing data from the file, using the handle */
+...
+ tracecmd_close(handle);
+...
--
FILES
-----
@@ -3,9 +3,8 @@ libtracecmd(3)
NAME
----
-tracecmd_init_data, tracecmd_read_cpu_first, tracecmd_read_data,
-tracecmd_read_at, tracecmd_free_record, tracecmd_get_tep
-- Read recorded events from a trace file.
+tracecmd_read_cpu_first, tracecmd_read_data, tracecmd_read_at,
+tracecmd_free_record, tracecmd_get_tep - Read recorded events from a trace file.
SYNOPSIS
--------
@@ -13,7 +12,6 @@ SYNOPSIS
--
*#include <trace-cmd.h>*
-int *tracecmd_init_data*(struct tracecmd_input pass:[*]_handle_);
struct tep_record pass:[*]*tracecmd_read_cpu_first*(struct tracecmd_input pass:[*]_handle_, int _cpu_);
struct tep_record pass:[*]*tracecmd_read_data*(struct tracecmd_input pass:[*]_handle_, int _cpu_);
struct tep_record pass:[*]*tracecmd_read_at*(struct tracecmd_input pass:[*]_handle_, unsigned long long _offset_, int pass:[*]_cpu_);
@@ -24,11 +22,7 @@ struct tep_handle pass:[*]*tracecmd_get_tep*(struct tracecmd_input pass:[*]_hand
DESCRIPTION
-----------
This set of APIs can be used to read tracing data from a trace file opened
-with _tracecmd_open_head()(3)_
-
-The _tracecmd_init_data()_ function initializes the _handle_ for reading
-trace data from the file associated with it. This API must be called before
-any of the _tracecmd_read__ APIs.
+with _tracecmd_open()(3)_, _tracecmd_open_fd()(3)_ or _tracecmd_open_head()(3)_.
The _tracecmd_read_cpu_first()_ function reads the first trace record
for a given _cpu_ from a trace file associated with _handle_. The returned
@@ -54,9 +48,6 @@ _handle_.
RETURN VALUE
------------
-The _tracecmd_init_data()_ function returns -1 in case of an error or
-0 otherwise.
-
The _tracecmd_read_cpu_first()_, _tracecmd_read_data()_ and
_tracecmd_read_at()_ functions return a pointer to struct tep_record or
NULL in case of an error.The returned record must be freed with
@@ -72,7 +63,7 @@ EXAMPLE
--
#include <trace-cmd.h>
...
-struct tracecmd_input *handle = tracecmd_open_head("trace.dat");
+struct tracecmd_input *handle = tracecmd_open("trace.dat");
if (!handle) {
/* Failed to open trace.dat file */
}
@@ -80,11 +71,6 @@ struct tracecmd_input *handle = tracecmd_open_head("trace.dat");
unsigned long long offset = 0;
struct tep_record *rec;
int cpu = 0;
-
- if (tracecmd_init_data(handle) < 0) {
- /* Failed to initialize hadle for reading the trace data */
- }
-
rec = tracecmd_read_cpu_first(handle, cpu);
while (rec) {
...
Documented APIs: tracecmd_open() tracecmd_open_fd() Moved tracecmd_init_data() documentation to more appropriate man page. Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com> --- .../libtracecmd/libtracecmd-files.3.txt | 89 +++++++++++++++++-- .../libtracecmd/libtracecmd-record.3.txt | 22 +---- 2 files changed, 84 insertions(+), 27 deletions(-)