[PATCH 3/4] trace-cmd library man pages: Documented APIs for opening trace file

["Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com>]

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(-)

diff --git a/Documentation/libtracecmd/libtracecmd-files.3.txt b/Documentation/libtracecmd/libtracecmd-files.3.txt
index 75809223..c5f0ad0a 100644
--- a/Documentation/libtracecmd/libtracecmd-files.3.txt
+++ b/Documentation/libtracecmd/libtracecmd-files.3.txt
@@ -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
 -----
diff --git a/Documentation/libtracecmd/libtracecmd-record.3.txt b/Documentation/libtracecmd/libtracecmd-record.3.txt
index f25dd34c..aa1a4a66 100644
--- a/Documentation/libtracecmd/libtracecmd-record.3.txt
+++ b/Documentation/libtracecmd/libtracecmd-record.3.txt
@@ -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) {
 		...
-- 
2.29.2