[PATCH 0/5] trace-cmd library: Update the man pages

[PATCH 0/5] trace-cmd library: Update the man pages

[Steven Rostedt]

From: "Steven Rostedt (Google)" <rostedt@goodmis.org>

The man pages for trace-cmd library is out of date. Add the check logic to
make sure everything that is in the header file is documented, and all man
pages are also in the libtracecmd man page.

Steven Rostedt (Google) (5):
  tracecmd library documentation: Use star and not underscore for
    function names
  trace-cmd library: Make tracecmd_filter_match() local
  libtracecmd: Add check-manpages.sh
  libtracecmd: Add a man pages for handling of time stamps
  libtracecmd: Add documentation on tracecmd_set/get_private()

 .../libtracecmd/libtracecmd-files.txt         | 110 ++++++++------
 .../libtracecmd/libtracecmd-instances.txt     |  32 ++--
 Documentation/libtracecmd/libtracecmd-log.txt |  12 +-
 .../libtracecmd/libtracecmd-peer.txt          |  16 +-
 .../libtracecmd/libtracecmd-record.txt        |  36 ++---
 .../libtracecmd/libtracecmd-timestamp.txt     | 138 ++++++++++++++++++
 Documentation/libtracecmd/libtracecmd.txt     |  14 +-
 Makefile                                      |   5 +-
 check-manpages.sh                             |  54 +++++++
 include/trace-cmd/trace-cmd.h                 |   2 -
 lib/trace-cmd/include/trace-cmd-local.h       |   3 +
 lib/trace-cmd/trace-filter.c                  |   4 +-
 12 files changed, 326 insertions(+), 100 deletions(-)
 create mode 100644 Documentation/libtracecmd/libtracecmd-timestamp.txt
 create mode 100755 check-manpages.sh

-- 
2.35.1

[PATCH 1/5] tracecmd library documentation: Use star and not underscore for function names

[Steven Rostedt]

From: "Steven Rostedt (Google)" <rostedt@goodmis.org>

Functions referenced in man pages should be bold and not underscored.
Convert all function references in the man pages to be bold.

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 .../libtracecmd/libtracecmd-files.txt         | 38 +++++++++----------
 .../libtracecmd/libtracecmd-instances.txt     | 32 ++++++++--------
 Documentation/libtracecmd/libtracecmd-log.txt | 12 +++---
 .../libtracecmd/libtracecmd-peer.txt          | 16 ++++----
 .../libtracecmd/libtracecmd-record.txt        | 36 +++++++++---------
 Documentation/libtracecmd/libtracecmd.txt     |  8 ++--
 6 files changed, 71 insertions(+), 71 deletions(-)

diff --git a/Documentation/libtracecmd/libtracecmd-files.txt b/Documentation/libtracecmd/libtracecmd-files.txt
index 2de5d6dfa660..382603efd50d 100644
--- a/Documentation/libtracecmd/libtracecmd-files.txt
+++ b/Documentation/libtracecmd/libtracecmd-files.txt
@@ -22,7 +22,7 @@ void *tracecmd_close*(struct tracecmd_input pass:[*]_handle_);
 DESCRIPTION
 -----------
 This set of APIs can be used to open and close a trace file recorded by
-_trace-cmd(1)_ and containing tracing information from ftrace, the official
+*trace-cmd(1)* and containing tracing information from ftrace, the official
 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 APIs for opening a trace file have a _flag_ input
@@ -33,37 +33,37 @@ is a combination of these options:
  TRACECMD_FL_LOAD_NO_SYSTEM_PLUGINS - Do not load system wide plugins, load only "local only"
 					plugins from user's home directory.
 
-The _tracecmd_open()_ function opens a given trace _file_, parses the
+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
+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
+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
+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
+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()_, _tracecmd_open_fd()_
-or _tracecmd_open_head()_ APIs.
+The *tracecmd_close()* function frees a _handle_, pointer to tracecmd_input
+structure, previously allocated with *tracecmd_open()*, *tracecmd_open_fd()*
+or *tracecmd_open_head()* APIs.
 
 RETURN VALUE
 ------------
-The _tracecmd_open()_, _tracecmd_open_fd()_ and _tracecmd_open_head()_
+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.
+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
+The *tracecmd_init_data()* function returns -1 in case of an error or
 0 otherwise.
 
 EXAMPLE
@@ -139,10 +139,10 @@ FILES
 
 SEE ALSO
 --------
-_libtracefs(3)_,
-_libtraceevent(3)_,
-_trace-cmd(1)_
-_trace-cmd.dat(5)_
+*libtracefs(3)*,
+*libtraceevent(3)*,
+*trace-cmd(1)*
+*trace-cmd.dat(5)*
 
 AUTHOR
 ------
diff --git a/Documentation/libtracecmd/libtracecmd-instances.txt b/Documentation/libtracecmd/libtracecmd-instances.txt
index df8fdc4e7f66..364085fdf482 100644
--- a/Documentation/libtracecmd/libtracecmd-instances.txt
+++ b/Documentation/libtracecmd/libtracecmd-instances.txt
@@ -22,36 +22,36 @@ DESCRIPTION
 This set of APIs can be used to get information and read tracing data
 from tracing instances stored in a trace file.
 
-The _tracecmd_buffer_instances()_ function gets the number of tracing
+The *tracecmd_buffer_instances()* function gets the number of tracing
 instances recorded in a trace file. The top instance is not counted.
 The _handle_ is a tracecmd_input handler returned by
-_tracecmd_open_head()_.
+*tracecmd_open_head()*.
 
-The _tracecmd_buffer_instance_name()_ function gets the name of the
+The *tracecmd_buffer_instance_name()* function gets the name of the
 tracing instance with given index _indx_, recorded in a trace file.
 The _indx_ is a number in the interval [0 .. count-1], where count
-is the number returned by _tracecmd_buffer_instances()_. The _handle_
-is a tracecmd_input handler returned by _tracecmd_open_head()_.
+is the number returned by *tracecmd_buffer_instances()*. The _handle_
+is a tracecmd_input handler returned by *tracecmd_open_head()*.
 
-The _tracecmd_buffer_instance_handle()_ allocates and initializes a
+The *tracecmd_buffer_instance_handle()* allocates and initializes a
 tracecmd_input handle, associated with trace instance with index
 _indx_ from a trace file.  The _handle_ is a tracecmd_input handler
-returned by _tracecmd_open_head()_. The _indx_ is a number in the
+returned by *tracecmd_open_head()*. The _indx_ is a number in the
 interval [0 .. count-1], where count is the number returned by
-_tracecmd_buffer_instances()_.
+*tracecmd_buffer_instances()*.
 
 RETURN VALUE
 ------------
-The _tracecmd_buffer_instances()_ function returns the number of tracing
+The *tracecmd_buffer_instances()* function returns the number of tracing
 instances recorded in a trace file.
 
-The _tracecmd_buffer_instance_name()_ function returns a string, the name
+The *tracecmd_buffer_instance_name()* function returns a string, the name
 of a tracing instance, or NULL in case of an error The string must *not*
 be freed.
 
-The _tracecmd_buffer_instance_handle()_ function returns a pointer to
+The *tracecmd_buffer_instance_handle()* function returns a pointer to
 newly allocated tracecmd_input handler or NULL in case if an error. The
-returned handler must be closed by _tracecmd_close()(3)_
+returned handler must be closed by *tracecmd_close()(3)*
 
 EXAMPLE
 -------
@@ -99,10 +99,10 @@ FILES
 
 SEE ALSO
 --------
-_libtracefs(3)_,
-_libtraceevent(3)_,
-_trace-cmd(1)_
-_trace-cmd.dat(5)_
+*libtracefs(3)*,
+*libtraceevent(3)*,
+*trace-cmd(1)*
+*trace-cmd.dat(5)*
 
 AUTHOR
 ------
diff --git a/Documentation/libtracecmd/libtracecmd-log.txt b/Documentation/libtracecmd/libtracecmd-log.txt
index de5c277684ec..38e17bf744ff 100644
--- a/Documentation/libtracecmd/libtracecmd-log.txt
+++ b/Documentation/libtracecmd/libtracecmd-log.txt
@@ -16,8 +16,8 @@ int *tracecmd_set_loglevel*(enum tep_loglevel _level_);
 
 DESCRIPTION
 -----------
-The _tracecmd_set_loglevel()_ function sets the level of the library logs that will be printed on
-the console. See _libtraceevent(3)_ for detailed desciription of the log levels. Setting the log
+The *tracecmd_set_loglevel()* function sets the level of the library logs that will be printed on
+the console. See *libtraceevent(3)* for detailed desciription of the log levels. Setting the log
 level to specific value means that logs from the previous levels will be printed too. For example
 _TEP_LOG_WARNING_ will print any logs with severity _TEP_LOG_WARNING_, _TEP_LOG_ERROR_ and
 _TEP_LOG_CRITICAL_. The default log level is _TEP_LOG_CRITICAL_.  When a new level is set, it is
@@ -48,10 +48,10 @@ FILES
 
 SEE ALSO
 --------
-_libtracefs(3)_,
-_libtraceevent(3)_,
-_trace-cmd(1)_
-_trace-cmd.dat(5)_
+*libtracefs(3)*,
+*libtraceevent(3)*,
+*trace-cmd(1)*
+*trace-cmd.dat(5)*
 
 AUTHOR
 ------
diff --git a/Documentation/libtracecmd/libtracecmd-peer.txt b/Documentation/libtracecmd/libtracecmd-peer.txt
index 2e3232c6edb5..c9774c86945a 100644
--- a/Documentation/libtracecmd/libtracecmd-peer.txt
+++ b/Documentation/libtracecmd/libtracecmd-peer.txt
@@ -25,13 +25,13 @@ Information about peers from the session is stored in the metadata of each
 trace file. These APIs use that information to extract and synchronize
 the trace data.
 
-The _tracecmd_get_traceid()_ function returns the trace ID stored in
+The *tracecmd_get_traceid()* function returns the trace ID stored in
 the trace file metadata associated with _handle_. Each peer from a trace
 session has an ID unique for that peer and that trace session only.
 This ID is used to match multiple trace files recorded in a same trace
 session.
 
-The _tracecmd_get_guest_cpumap()_ function gets the mapping of guest
+The *tracecmd_get_guest_cpumap()* function gets the mapping of guest
 virtual CPUs (VCPU) to the host process that represents those VCPUs and is
 stored in the metadata of the trace file associated with _handle_. This
 information is gathered during a host-guest trace session and is stored
@@ -47,9 +47,9 @@ The _name_, _vcpu_count_ and _cpu_pid_ values must *not* be freed.
 
 RETURN VALUE
 ------------
-The _tracecmd_get_traceid()_ function returns a 64 bit trace ID.
+The *tracecmd_get_traceid()* function returns a 64 bit trace ID.
 
-The _tracecmd_get_guest_cpumap()_ function returns -1 in case of
+The *tracecmd_get_guest_cpumap()* function returns -1 in case of
 an error or 0 otherwise. If 0 is returned, then the _name_, _vcpu_count_
 and _cpu_pid_ parameters contain the requested information.
 
@@ -107,10 +107,10 @@ FILES
 
 SEE ALSO
 --------
-_libtracefs(3)_,
-_libtraceevent(3)_,
-_trace-cmd(1)_
-_trace-cmd.dat(5)_
+*libtracefs(3)*,
+*libtraceevent(3)*,
+*trace-cmd(1)*
+*trace-cmd.dat(5)*
 
 AUTHOR
 ------
diff --git a/Documentation/libtracecmd/libtracecmd-record.txt b/Documentation/libtracecmd/libtracecmd-record.txt
index aa1a4a662929..69439552d6ba 100644
--- a/Documentation/libtracecmd/libtracecmd-record.txt
+++ b/Documentation/libtracecmd/libtracecmd-record.txt
@@ -22,38 +22,38 @@ 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()(3)_, _tracecmd_open_fd()(3)_ or _tracecmd_open_head()(3)_.
+with *tracecmd_open()(3)*, *tracecmd_open_fd()(3)* or *tracecmd_open_head()(3)*.
 
-The _tracecmd_read_cpu_first()_ function reads the first trace record
+The *tracecmd_read_cpu_first()* function reads the first trace record
 for a given _cpu_ from a trace file associated with _handle_. The returned
-record must be freed with _tracecmd_free_record()_.
+record must be freed with *tracecmd_free_record()*.
 
-The _tracecmd_read_data()_ function reads the next trace record for
+The *tracecmd_read_data()* function reads the next trace record for
 a given _cpu_ from a trace file associated with _handle_ and increments
-the read location pointer, so that the next call to _tracecmd_read_data()_
+the read location pointer, so that the next call to *tracecmd_read_data()*
 will not read the same record again. The returned record must be freed
-with _tracecmd_free_record()_.
+with *tracecmd_free_record()*.
 
-The _tracecmd_read_at()_ function reads a trace record from a specific
+The *tracecmd_read_at()* function reads a trace record from a specific
 _offset_ within the file associated with _handle_. The CPU on which the
 recorded event occurred is stored in the _cpu_. The function does not
 change the current read location pointer. The returned record must be
-freed with _tracecmd_free_record()_.
+freed with *tracecmd_free_record()*.
 
-The _tracecmd_free_record()_ function frees a _record_ returned by any
+The *tracecmd_free_record()* function frees a _record_ returned by any
 of the _tracecmd_read__ APIs.
 
-The _tracecmd_get_tep()_ function returns a tep context for a given
+The *tracecmd_get_tep()* function returns a tep context for a given
 _handle_.
 
 RETURN VALUE
 ------------
-The _tracecmd_read_cpu_first()_, _tracecmd_read_data()_ and
-_tracecmd_read_at()_ functions return a pointer to struct tep_record or
+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
-_tracecmd_free_record()_.
+*tracecmd_free_record()*.
 
-The _tracecmd_get_tep()_ function returns a pointer to tep context or
+The *tracecmd_get_tep()* function returns a pointer to tep context or
 NULL if there is no tep context for the given _handle_. The returned
 tep pointer must *not* be freed.
 
@@ -108,10 +108,10 @@ FILES
 
 SEE ALSO
 --------
-_libtracefs(3)_,
-_libtraceevent(3)_,
-_trace-cmd(1)_
-_trace-cmd.dat(5)_
+*libtracefs(3)*,
+*libtraceevent(3)*,
+*trace-cmd(1)*
+*trace-cmd.dat(5)*
 
 AUTHOR
 ------
diff --git a/Documentation/libtracecmd/libtracecmd.txt b/Documentation/libtracecmd/libtracecmd.txt
index dc528ce02aac..e9e11b32c8b6 100644
--- a/Documentation/libtracecmd/libtracecmd.txt
+++ b/Documentation/libtracecmd/libtracecmd.txt
@@ -56,10 +56,10 @@ FILES
 
 SEE ALSO
 --------
-_libtraceevent(3)_
-_libtracefs(3)_
-_trace-cmd(1)_
-_trace-cmd.dat(5)_
+*libtraceevent(3)*
+*libtracefs(3)*
+*trace-cmd(1)*
+*trace-cmd.dat(5)*
 
 AUTHOR
 ------
-- 
2.35.1

[PATCH 2/5] trace-cmd library: Make tracecmd_filter_match() local

[Steven Rostedt]

From: "Steven Rostedt (Google)" <rostedt@goodmis.org>

The function tracecmd_filter_match() is really an internal function. It
should not be exported for other applications (The trace-cmd core
functions do not use it). It should definitely not be in the public
headers.

Move the prototype so that it is only used internally within the
library.

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 include/trace-cmd/trace-cmd.h           | 2 --
 lib/trace-cmd/include/trace-cmd-local.h | 3 +++
 lib/trace-cmd/trace-filter.c            | 4 ++--
 3 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/include/trace-cmd/trace-cmd.h b/include/trace-cmd/trace-cmd.h
index 4963f45dfe12..331815b9edc2 100644
--- a/include/trace-cmd/trace-cmd.h
+++ b/include/trace-cmd/trace-cmd.h
@@ -76,7 +76,5 @@ enum tracecmd_filters {
 struct tracecmd_filter;
 struct tracecmd_filter *tracecmd_filter_add(struct tracecmd_input *handle,
 					    const char *filter_str, bool neg);
-enum tracecmd_filters tracecmd_filter_match(struct tracecmd_filter *filter,
-					    struct tep_record *record);
 
 #endif /* _TRACE_CMD_H */
diff --git a/lib/trace-cmd/include/trace-cmd-local.h b/lib/trace-cmd/include/trace-cmd-local.h
index 2a458133204b..c95ec6530fdd 100644
--- a/lib/trace-cmd/include/trace-cmd-local.h
+++ b/lib/trace-cmd/include/trace-cmd-local.h
@@ -49,6 +49,9 @@ struct data_file_write {
 	unsigned long long	file_data_offset;
 };
 
+enum tracecmd_filters tracecmd_filter_match(struct tracecmd_filter *filter,
+					    struct tep_record *record);
+
 void tracecmd_compress_init(void);
 void tracecmd_compress_free(void);
 
diff --git a/lib/trace-cmd/trace-filter.c b/lib/trace-cmd/trace-filter.c
index f7eb46c762d6..1c8c07fcf0da 100644
--- a/lib/trace-cmd/trace-filter.c
+++ b/lib/trace-cmd/trace-filter.c
@@ -44,8 +44,8 @@ static bool test_stacktraces(struct tracecmd_filter *filter, struct tep_record *
 		test_stacktrace(filter, record, filter->user_stacktrace_id);
 }
 
-enum tracecmd_filters tracecmd_filter_match(struct tracecmd_filter *filter,
-					    struct tep_record *record)
+__hidden enum tracecmd_filters tracecmd_filter_match(struct tracecmd_filter *filter,
+						     struct tep_record *record)
 {
 	bool found = false;
 	int ret;
-- 
2.35.1

[PATCH 3/5] libtracecmd: Add check-manpages.sh

[Steven Rostedt]

From: "Steven Rostedt (Google)" <rostedt@goodmis.org>

Add the script check-manpages.sh that makes sure all the function that
are documented in the man pages are show in the overall man page
"libtracecmd" as well as making sure that all functions in
trace-cmd.h is also documented.

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 Makefile          |  5 ++++-
 check-manpages.sh | 54 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+), 1 deletion(-)
 create mode 100755 check-manpages.sh

diff --git a/Makefile b/Makefile
index 7178d7a9758d..f0c7938b6908 100644
--- a/Makefile
+++ b/Makefile
@@ -508,7 +508,7 @@ install_gui: force
 install_libs: libs
 	$(Q)$(MAKE) -C $(src)/lib/trace-cmd/ $@
 
-doc:
+doc: check_doc
 	$(MAKE) -C $(src)/Documentation all
 
 doc_clean:
@@ -517,6 +517,9 @@ doc_clean:
 install_doc:
 	$(MAKE) -C $(src)/Documentation install
 
+check_doc: force
+	$(Q)$(src)/check-manpages.sh $(src)/Documentation/libtracecmd
+
 clean:
 	$(RM) *.o *~ *.a *.so .*.d
 	$(RM) tags TAGS cscope* $(PKG_CONFIG_SOURCE_FILE) $(VERSION_FILE)
diff --git a/check-manpages.sh b/check-manpages.sh
new file mode 100755
index 000000000000..1166bbe82cad
--- /dev/null
+++ b/check-manpages.sh
@@ -0,0 +1,54 @@
+#!/bin/bash
+# SPDX-License-Identifier: LGPL-2.1
+# Copyright (C) 2022, Google Inc, Steven Rostedt <rostedt@goodmis.org>
+#
+# This checks if any function is listed in a man page that is not listed
+# in the main man page.
+
+if [ $# -lt 1 ]; then
+	echo "usage: check-manpages man-page-path"
+	exit 1
+fi
+
+cd $1
+
+MAIN=libtracecmd
+MAIN_FILE=${MAIN}.txt
+
+# Ignore man pages that do not contain functions
+IGNORE=""
+
+for man in ${MAIN}-*.txt; do
+
+	sed -ne '/^NAME/,/^SYNOP/{/^[a-z]/{s/, *$//;s/,/\n/g;s/ //g;s/-.*$/-/;/-/{s/-//p;q};p}}' $man | while read a; do
+		if [ "${IGNORE/$man/}" != "${IGNORE}" ]; then
+			continue
+		fi
+		if ! grep -q '\*'${a}'\*' $MAIN_FILE; then
+			if [ "$last" == "" ]; then
+				echo
+			fi
+			if [ "$last" != "$man" ]; then
+				echo "Missing functions from $MAIN_FILE that are in $man"
+				last=$man
+			fi
+			echo "   ${a}"
+		fi
+	done
+done
+
+DEPRECATED=""
+
+sed -ne 's/^[a-z].*[ \*]\([a-z_][a-z_]*\)(.*/\1/p' -e 's/^\([a-z_][a-z_]*\)(.*/\1/p' ../../include/trace-cmd/trace-cmd.h | while read f; do
+	if ! grep -q '\*'${f}'\*' $MAIN_FILE; then
+		if [ "${DEPRECATED/\*$f\*/}" != "${DEPRECATED}" ]; then
+			continue;
+		fi
+		if [ "$last" == "" ]; then
+			echo
+			echo "Missing functions from $MAIN_FILE that are in tracefs.h"
+			last=$f
+		fi
+		echo "   ${f}"
+	fi
+done
-- 
2.35.1

[PATCH 4/5] libtracecmd: Add a man pages for handling of time stamps

[Steven Rostedt]

From: "Steven Rostedt (Google)" <rostedt@goodmis.org>

Add to the man pages the function tracecmd_get_first_ts(), and
tracecmd_add_ts_offset().

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 .../libtracecmd/libtracecmd-timestamp.txt     | 138 ++++++++++++++++++
 Documentation/libtracecmd/libtracecmd.txt     |   4 +
 2 files changed, 142 insertions(+)
 create mode 100644 Documentation/libtracecmd/libtracecmd-timestamp.txt

diff --git a/Documentation/libtracecmd/libtracecmd-timestamp.txt b/Documentation/libtracecmd/libtracecmd-timestamp.txt
new file mode 100644
index 000000000000..8695d003965b
--- /dev/null
+++ b/Documentation/libtracecmd/libtracecmd-timestamp.txt
@@ -0,0 +1,138 @@
+libtracecmd(3)
+=============
+
+NAME
+----
+tracecmd_get_first_ts, tracecmd_add_ts_offset - Handle time stamps from a trace file.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <trace-cmd.h>*
+
+unsigned long long *tracecmd_get_first_ts*(struct tracecmd_input pass:[*]_handle_);
+void *tracecmd_add_ts_offset*(struct tracecmd_input pass:[*]_handle_, long long _offset_);
+--
+
+DESCRIPTION
+-----------
+This set of APIs can be used to read tracing data from a trace file opened
+with _tracecmd_open()(3)_, _tracecmd_open_fd()(3)_ or _tracecmd_open_head()(3)_.
+
+The *tracecmd_get_first_ts()* function returns the time stamp of the first
+record in the _handle_.
+
+The *tracecmd_add_ts_offset()* function adds an offset to each of the records
+in the _handle_ that represents a trace file. This is useful for associating two
+different tracing files by their offset (for example a trace file from a host
+and a trace file from a guest that were not synchronized when created).
+
+RETURN VALUE
+------------
+The *tracecmd_get_first_ts()* function returns the timestamp of the first
+record in a trace file for the given _handle_.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <stdlib.h>
+#include <trace-cmd.h>
+
+static int print_events(struct tracecmd_input *handle, struct tep_record *record, int cpu, void *data)
+{
+	static struct trace_seq seq;
+	struct tep_handle *tep = tracecmd_get_tep(handle);
+	const char *file = tracecmd_get_private(handle);
+
+	if (!seq.buffer)
+		trace_seq_init(&seq);
+
+	trace_seq_reset(&seq);
+	trace_seq_printf(&seq, "%s: ", file);
+	tep_print_event(tep, &seq, record, "%6.1000d [%03d] %s-%d %s: %s\n",
+			TEP_PRINT_TIME, TEP_PRINT_CPU, TEP_PRINT_COMM, TEP_PRINT_PID,
+			TEP_PRINT_NAME, TEP_PRINT_INFO);
+	trace_seq_terminate(&seq);
+	trace_seq_do_printf(&seq);
+	return 0;
+}
+
+int main(int argc, char **argv)
+{
+	struct tracecmd_input **handles = NULL;
+	unsigned long long ts, first_ts = 0;
+	int nr_handles = 0;
+	int i;
+
+	if (argc < 2) {
+		printf("usage: %s trace.dat [trace.dat ...]\n", argv[0]);
+		exit(-1);
+	}
+
+	for (i = 1; i < argc; i++) {
+		handles = realloc(handles, sizeof(*handles) * (nr_handles + 1));
+		if (!handles)
+			exit(-1);
+		handles[nr_handles] = tracecmd_open(argv[i], 0);
+		if (!handles[nr_handles])
+			exit(-1);
+		tracecmd_set_private(handles[nr_handles], argv[i]);
+		ts = tracecmd_get_first_ts(handles[nr_handles]);
+		if (!first_ts || ts < first_ts)
+			first_ts = ts;
+		nr_handles++;
+	}
+
+	/* Set the time stamp to start at the first record found */
+	for (i = 0; i < nr_handles; i++)
+		tracecmd_add_ts_offset(handles[i], -first_ts);
+
+	tracecmd_iterate_events_multi(handles, nr_handles, print_events, NULL);
+
+	for (i = 0; i < nr_handles; i++)
+		tracecmd_close(handles[i]);
+	free(handles);
+}
+--
+FILES
+-----
+[verse]
+--
+*trace-cmd.h*
+	Header file to include in order to have access to the library APIs.
+*-ltracecmd*
+	Linker switch to add when building a program that uses the library.
+--
+
+SEE ALSO
+--------
+_libtracefs(3)_,
+_libtraceevent(3)_,
+_trace-cmd(1)_
+_trace-cmd.dat(5)_
+
+AUTHOR
+------
+[verse]
+--
+*Steven Rostedt* <rostedt@goodmis.org>
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtracecmd is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
+
+COPYING
+-------
+Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under
+the terms of the GNU Public License (GPL).
diff --git a/Documentation/libtracecmd/libtracecmd.txt b/Documentation/libtracecmd/libtracecmd.txt
index e9e11b32c8b6..1939c209dc34 100644
--- a/Documentation/libtracecmd/libtracecmd.txt
+++ b/Documentation/libtracecmd/libtracecmd.txt
@@ -30,6 +30,10 @@ Read tracing instances from a trace file:
 	const char pass:[*]*tracecmd_buffer_instance_name*(struct tracecmd_input pass:[*]_handle_, int _indx_);
 	struct tracecmd_input pass:[*]*tracecmd_buffer_instance_handle*(struct tracecmd_input pass:[*]_handle_, int _indx_);
 
+Handle time stamps from a trace file:
+	unsigned long long *tracecmd_get_first_ts*(struct tracecmd_input pass:[*]_handle_);
+	void *tracecmd_add_ts_offset*(struct tracecmd_input pass:[*]_handle_, long long _offset_);
+
 Get traceing peer information from a trace file:
 	unsigned long long *tracecmd_get_traceid*(struct tracecmd_input pass:[*]_handle_);
 	int *tracecmd_get_guest_cpumap*(struct tracecmd_input pass:[*]_handle_, unsigned long long _trace_id_, const char pass:[*]pass:[*]_name_, int pass:[*]_vcpu_count_, const int pass:[*]pass:[*]_cpu_pid_);
-- 
2.35.1

[PATCH 5/5] libtracecmd: Add documentation on tracecmd_set/get_private()

[Steven Rostedt]

From: "Steven Rostedt (Google)" <rostedt@goodmis.org>

The tracecmd_set_private() and tracecmd_get_private() functions were not
in the man pages. Add them, and also add a working example for the
tracecmd_open() (and other) function.

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 .../libtracecmd/libtracecmd-files.txt         | 72 ++++++++++++-------
 Documentation/libtracecmd/libtracecmd.txt     |  2 +
 2 files changed, 50 insertions(+), 24 deletions(-)

diff --git a/Documentation/libtracecmd/libtracecmd-files.txt b/Documentation/libtracecmd/libtracecmd-files.txt
index 382603efd50d..f8292cb4cbd5 100644
--- a/Documentation/libtracecmd/libtracecmd-files.txt
+++ b/Documentation/libtracecmd/libtracecmd-files.txt
@@ -4,7 +4,7 @@ libtracecmd(3)
 NAME
 ----
 tracecmd_open, tracecmd_open_fd, tracecmd_open_head, tracecmd_init_data,
-tracecmd_close - Open and close a trace file.
+tracecmd_close, tracecmd_set_private, tracecmd_get_private - Open and close a trace file.
 
 SYNOPSIS
 --------
@@ -17,6 +17,8 @@ struct tracecmd_input pass:[*]*tracecmd_open_fd*(int _fd_, int _flags_);
 struct tracecmd_input pass:[*]*tracecmd_open_head*(const char pass:[*]_file_, int _flags_);
 int *tracecmd_init_data*(struct tracecmd_input pass:[*]_handle_);
 void *tracecmd_close*(struct tracecmd_input pass:[*]_handle_);
+void *tracecmd_set_private*(struct tracecmd_input pass:[*]_handle_, void pass:[*]_data_);
+void pass:[*]*tracecmd_get_private*(struct tracecmd_input pass:[*]_handle_);
 --
 
 DESCRIPTION
@@ -55,6 +57,12 @@ The *tracecmd_close()* function frees a _handle_, pointer to tracecmd_input
 structure, previously allocated with *tracecmd_open()*, *tracecmd_open_fd()*
 or *tracecmd_open_head()* APIs.
 
+The *tracecmd_set_private()* function allows to add specific _data_ to the
+_handle_ that can be retrieved later.
+
+The *tracecmd_get_private()* function will retrieve the _data_ set by
+*tracecmd_set_private()* for the given _handle_.
+
 RETURN VALUE
 ------------
 The *tracecmd_open()*, *tracecmd_open_fd()* and *tracecmd_open_head()*
@@ -66,6 +74,8 @@ 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.
 
+The *tracecmd_get_private()* returns the _data_ set by *tracecmd_set_private()*.
+
 EXAMPLE
 -------
 [source,c]
@@ -75,32 +85,46 @@ a trace file, which can be used depending on the use case.
 
 1. Open and initialise the trace file in а single step:
 
+#include <stdlib.h>
 #include <trace-cmd.h>
-...
-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 */
+
+static int print_events(struct tracecmd_input *handle, struct tep_record *record, int cpu, void *data)
+{
+	static struct trace_seq seq;
+	struct tep_handle *tep = tracecmd_get_tep(handle);
+	const char *file = tracecmd_get_private(handle);
+
+	if (!seq.buffer)
+		trace_seq_init(&seq);
+
+	trace_seq_reset(&seq);
+	trace_seq_printf(&seq, "%s: ", file);
+	tep_print_event(tep, &seq, record, "%6.1000d [%03d] %s-%d %s: %s\n",
+			TEP_PRINT_TIME, TEP_PRINT_CPU, TEP_PRINT_COMM, TEP_PRINT_PID,
+			TEP_PRINT_NAME, TEP_PRINT_INFO);
+	trace_seq_terminate(&seq);
+	trace_seq_do_printf(&seq);
+	return 0;
+}
+
+int main(int argc, char **argv)
+{
+	struct tracecmd_input *handle;
+
+	if (argc < 2) {
+		printf("usage: %s trace.dat\n", argv[0]);
+		exit(-1);
 	}
-...
-	/* Read tracing data from the file, using the handle */
-...
+
+	handle = tracecmd_open(argv[i], 0);
+	if (!handle)
+		exit(-1);
+
+	tracecmd_set_private(handles[nr_handles], argv[i]);
+	tracecmd_iterate_events(handles, NULL, 0, print_events, NULL);
+
 	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
diff --git a/Documentation/libtracecmd/libtracecmd.txt b/Documentation/libtracecmd/libtracecmd.txt
index 1939c209dc34..141fec5d379c 100644
--- a/Documentation/libtracecmd/libtracecmd.txt
+++ b/Documentation/libtracecmd/libtracecmd.txt
@@ -16,6 +16,8 @@ Open and close trace file:
 	struct tracecmd_input pass:[*]*tracecmd_open_fd*(int _fd_, int _flags_);
 	struct tracecmd_input pass:[*]*tracecmd_open_head*(const char pass:[*]_file_, int _flags_);
 	void *tracecmd_close*(struct tracecmd_input pass:[*]_handle_);
+	void *tracecmd_set_private*(struct tracecmd_input pass:[*]_handle_, void pass:[*]_data_);
+	void pass:[*]*tracecmd_get_private*(struct tracecmd_input pass:[*]_handle_);
 
 Read tracing records from a trace file:
 	int *tracecmd_init_data*(struct tracecmd_input pass:[*]_handle_);
-- 
2.35.1