[PATCH 00/11] libtracefs: Add man page checks and upate man pages

[PATCH 00/11] libtracefs: Add man page checks and upate man pages

[Steven Rostedt]

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

In preperation to release libtracefs 1.3, the man pages need to be complete.

I sent a patch to add a check-manpage.sh which this series is based on:

   https://lore.kernel.org/all/20220222131816.0bfdb33e@gandalf.local.home/

This series fixes the man page issues that the script has found. It also
updates the script to check tracefs.h to see if there's any missing functions
that should be in the man pages.

This series fixes the missing functions from the man pages too.

Finally, to make sure that functions are not missed in the future, the script
is executed whenever "make doc" is performed.

Steven Rostedt (Google) (11):
  libtracefs: Update main man page for all functions
  libtracefs: Do not check libtracefs-options.txt man page
  libtracefs: Have check-manpages.sh check tracefs.h as well
  libtracefs: Add documentation for tracefs_instances()
  libtracefs: Hide tracefs_list_pop() and make it trace_list_pop()
  libtracefs: Add documentation for tracefs_list_add/size()
  libtracefs: Add documentation for tracefs_iterate_stop()
  libtracefs: Add documentation for tracefs_option_id()
  libtracefs: Add man pages for tracefs_event_file_*() functions
  libtracefs: Do not check for deprecated functions
  libtracefs: Run the check-manpages.sh on building of docs

 Documentation/libtracefs-events-file.txt      | 217 ++++++++++++++++++
 Documentation/libtracefs-events.txt           |   9 +-
 .../libtracefs-instances-affinity.txt         |   4 +-
 Documentation/libtracefs-instances-manage.txt |  14 +-
 Documentation/libtracefs-option-get.txt       |  11 +-
 Documentation/libtracefs-utils.txt            |  28 ++-
 Documentation/libtracefs.txt                  |  33 +++
 Makefile                                      |   5 +-
 check-manpages.sh                             |  22 ++
 include/tracefs-local.h                       |   1 +
 include/tracefs.h                             |   1 -
 src/tracefs-hist.c                            |  10 +-
 src/tracefs-utils.c                           |   6 +-
 13 files changed, 342 insertions(+), 19 deletions(-)
 create mode 100644 Documentation/libtracefs-events-file.txt

-- 
2.34.1

[PATCH 01/11] libtracefs: Update main man page for all functions

[Steven Rostedt]

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

Add all the missing functions to the main man page.

Also, fix the tracefs_instance_set_affinity_raw and
tracefs_instance_get_affinity_raw as they were missing the "instance" part
in the name.

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 Documentation/libtracefs-instances-affinity.txt |  4 ++--
 Documentation/libtracefs.txt                    | 17 +++++++++++++++++
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/Documentation/libtracefs-instances-affinity.txt b/Documentation/libtracefs-instances-affinity.txt
index 385d65035ece..39dd44c1a3fb 100644
--- a/Documentation/libtracefs-instances-affinity.txt
+++ b/Documentation/libtracefs-instances-affinity.txt
@@ -3,8 +3,8 @@ libtracefs(3)
 
 NAME
 ----
-tracefs_instance_set_affinity, tracefs_instance_set_affinity_set, tracefs_set_affinity_raw,
-tracefs_instance_get_affinity, tracefs_instance_get_affinity_set, tracefs_get_affinity_raw
+tracefs_instance_set_affinity, tracefs_instance_set_affinity_set, tracefs_instance_set_affinity_raw,
+tracefs_instance_get_affinity, tracefs_instance_get_affinity_set, tracefs_instance_get_affinity_raw
 - Sets or retrieves the affinity for an instance or top level for what CPUs enable tracing.
 
 SYNOPSIS
diff --git a/Documentation/libtracefs.txt b/Documentation/libtracefs.txt
index 33988007d865..12df3ce3b7af 100644
--- a/Documentation/libtracefs.txt
+++ b/Documentation/libtracefs.txt
@@ -19,6 +19,7 @@ Locations of tracing files and directories:
 Trace instances:
 	struct tracefs_instance pass:[*]*tracefs_instance_create*(const char pass:[*]_name_);
 	int *tracefs_instance_destroy*(struct tracefs_instance pass:[*]_instance_);
+	struct tracefs_instance pass:[*]*tracefs_instance_alloc*(const char pass:[*]_tracing_dir_, const char pass:[*]_name_);
 	void *tracefs_instance_free*(struct tracefs_instance pass:[*]_instance_);
 	bool *tracefs_instance_is_new*(struct tracefs_instance pass:[*]_instance_);
 	bool *tracefs_file_exists*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_name_);
@@ -27,9 +28,12 @@ Trace instances:
 	char pass:[*]*tracefs_instance_get_dir*(struct tracefs_instance pass:[*]_instance_);
 	int *tracefs_instance_file_open*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, int _mode_);
 	int *tracefs_instance_file_write*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, const char pass:[*]_str_);
+	int *tracefs_instance_file_append*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, const char pass:[*]_str_);
+	int *tracefs_instance_file_clear*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_);
 	char pass:[*]*tracefs_instance_file_read*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, int pass:[*]_psize_);
 	int *tracefs_instance_file_read_number*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, long long int pass:[*]_res_);
 	const char pass:[*]*tracefs_instance_get_name*(struct tracefs_instance pass:[*]_instance_);
+	const char pass:[*]*tracefs_instance_get_trace_dir*(struct tracefs_instance pass:[*]_instance_);
 	int *tracefs_instances_walk*(int (pass:[*]_callback_)(const char pass:[*], void pass:[*]), void pass:[*]_context)_;
 	bool *tracefs_instance_exists*(const char pass:[*]_name_);
 	int *tracefs_instance_set_affinity*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_cpu_str_);
@@ -42,10 +46,15 @@ Trace instances:
 Trace events:
 	char pass:[*]pass:[*]*tracefs_event_systems*(const char pass:[*]_tracing_dir_);
 	char pass:[*]pass:[*]*tracefs_system_events*(const char pass:[*]_tracing_dir_, const char pass:[*]_system_);
+	int *tracefs_event_enable*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_,
+                           const char pass:[*]_event_);
+	int *tracefs_event_disable*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_,
+                            const char pass:[*]_event_);
 	int *tracefs_iterate_raw_events*(struct tep_handle pass:[*]_tep_, struct tracefs_instance pass:[*]_instance_, cpu_set_t pass:[*]_cpus_, int _cpu_size_, int (pass:[*]_callback_)(struct tep_event pass:[*], struct tep_record pass:[*], int, void pass:[*]), void pass:[*]_callback_context_);
 	struct tep_handle pass:[*]*tracefs_local_events*(const char pass:[*]_tracing_dir_);
 	struct tep_handle pass:[*]*tracefs_local_events_system*(const char pass:[*]_tracing_dir_, const char pass:[*] const pass:[*]_sys_names_);
 	int *tracefs_fill_local_events*(const char pass:[*]_tracing_dir_, struct tep_handle pass:[*]_tep_, int pass:[*]_parsing_failures_);
+	int *tracefs_load_cmdlines*(const char pass:[*]_tracing_dir_, struct tep_handle pass:[*]_tep_);
 
 Event filters:
 	int *tracefs_filter_string_append*(struct tep_event pass:[*]_event_, char pass:[**]_filter_,
@@ -70,6 +79,11 @@ Trace helper functions:
 	int *tracefs_trace_on_fd*(int _fd_);
 	int *tracefs_trace_off_fd*(int _fd_);
 
+Trace stream:
+	ssize_t *tracefs_trace_pipe_stream*(int _fd_, struct tracefs_instance pass:[*]_instance_, int _flags_);
+	ssize_t *tracefs_trace_pipe_print*(struct tracefs_instance pass:[*]_instance_, int _flags_);
+	void *tracefs_trace_pipe_stop*(struct tracefs_instance pass:[*]_instance_);
+
 Trace options:
 	const struct tracefs_options_mask pass:[*]*tracefs_options_get_supported*(struct tracefs_instance pass:[*]_instance_);
 	bool *tracefs_option_is_supported*(struct tracefs_instance pass:[*]_instance_, enum tracefs_option_id _id_);
@@ -106,8 +120,10 @@ Dynamic event generic APIs:
 	int *tracefs_dynevent_destroy_all*(unsigned int _types_, bool _force_);
 	void *tracefs_dynevent_free*(struct tracefs_dynevent pass:[*]_devent_);
 	void *tracefs_dynevent_list_free*(struct tracefs_dynevent pass:[*]pass:[*]_events_);
+	struct tracefs_dynevent pass:[*]*tracefs_dynevent_get*(enum tracefs_dynevent_type _type_, const char pass:[*]_system_, const char pass:[*]_event_);
 	struct tracefs_dynevent pass:[*]pass:[*]*tracefs_dynevent_get_all*(unsigned int _types_, const char pass:[*]_system_);
 	enum tracefs_dynevent_type *tracefs_dynevent_info*(struct tracefs_dynevent pass:[*]_dynevent_, char pass:[*]pass:[*]_system_, char pass:[*]pass:[*]_event_, char pass:[*]pass:[*]_prefix_, char pass:[*]pass:[*]_addr_, char pass:[*]pass:[*]_format_);
+	struct tep_event pass:[*]*tracefs_dynevent_get_event*(struct tep_handle pass:[*]_tep_, struct tracefs_dynevent pass:[*]_dynevent_);
 
 Even probes (eprobes):
 	struct tracefs_dynevent pass:[*] *tracefs_eprobe_alloc*(const char pass:[*]_system_, const char pass:[*]_event_, const char pass:[*]_target_system_, const char pass:[*]_target_event_, const char pass:[*]_fetchargs_);
@@ -173,6 +189,7 @@ Synthetic events:
 	const char pass:[*]*tracefs_synth_show_event*(struct tracefs_synth pass:[*]_synth_);
 	const char pass:[*]*tracefs_synth_show_start_hist*(struct tracefs_synth pass:[*]_synth_);
 	const char pass:[*]*tracefs_synth_show_end_hist*(struct tracefs_synth pass:[*]_synth_);
+	struct tep_event pass:[*]*tracefs_synth_get_event*(struct tep_handle pass:[*]_tep_, struct tracefs_synth pass:[*]_synth_);
 
 Ftrace errors reporting:
 	char pass:[*]*tracefs_error_last*(struct tracefs_instance pass:[*]_instance_);
-- 
2.34.1

[PATCH 02/11] libtracefs: Do not check libtracefs-options.txt man page

[Steven Rostedt]

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

The trace_options man page is there to list options and does not contain
any functions. It should be ignored from the check as it does not have
functions.

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 check-manpages.sh | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/check-manpages.sh b/check-manpages.sh
index a52281198f6e..b455fecd124b 100755
--- a/check-manpages.sh
+++ b/check-manpages.sh
@@ -15,9 +15,15 @@ cd $1
 MAIN=libtracefs
 MAIN_FILE=${MAIN}.txt
 
+# Ignore man pages that do not contain functions
+IGNORE="libtracefs-options.txt"
+
 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
-- 
2.34.1

[PATCH 03/11] libtracefs: Have check-manpages.sh check tracefs.h as well

[Steven Rostedt]

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

Test to make sure that all functions listed in tracefs.h are described in
libtracefs.txt man page.

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 check-manpages.sh | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/check-manpages.sh b/check-manpages.sh
index b455fecd124b..33419a92fd2f 100755
--- a/check-manpages.sh
+++ b/check-manpages.sh
@@ -36,3 +36,14 @@ for man in ${MAIN}-*.txt; do
 		fi
 	done
 done
+
+sed -ne 's/^[a-z].*[ \*]\([a-z_][a-z_]*\)(.*/\1/p' -e 's/^\([a-z_][a-z_]*\)(.*/\1/p' ../include/tracefs.h | while read f; do
+	if ! grep -q '\*'${f}'\*' $MAIN_FILE; then
+		if [ "$last" == "" ]; then
+			echo
+			echo "Missing functions from $MAIN_FILE that are in tracefs.h"
+			last=$f
+		fi
+		echo "   ${f}"
+	fi
+done
-- 
2.34.1

[PATCH 04/11] libtracefs: Add documentation for tracefs_instances()

[Steven Rostedt]

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

The function tracefs_instances() is missing from the man pages.

Add it.

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 Documentation/libtracefs-instances-manage.txt | 14 +++++++++++++-
 Documentation/libtracefs.txt                  |  1 +
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/Documentation/libtracefs-instances-manage.txt b/Documentation/libtracefs-instances-manage.txt
index 31e77a39c594..c03a272c18f0 100644
--- a/Documentation/libtracefs-instances-manage.txt
+++ b/Documentation/libtracefs-instances-manage.txt
@@ -4,7 +4,7 @@ libtracefs(3)
 NAME
 ----
 tracefs_instance_create, tracefs_instance_destroy, tracefs_instance_alloc, tracefs_instance_free,
-tracefs_instance_is_new - Manage trace instances.
+tracefs_instance_is_new, tracefs_instances - Manage trace instances.
 
 SYNOPSIS
 --------
@@ -17,6 +17,7 @@ int *tracefs_instance_destroy*(struct tracefs_instance pass:[*]_instance_);
 struct tracefs_instance pass:[*]*tracefs_instance_alloc*(const char pass:[*]_tracing_dir_, const char pass:[*]_name_);
 void *tracefs_instance_free*(struct tracefs_instance pass:[*]_instance_);
 bool *tracefs_instance_is_new*(struct tracefs_instance pass:[*]_instance_);
+char pass:[**]*tracefs_instances*(const char pass:[*]_regex_);
 
 --
 
@@ -53,6 +54,12 @@ The *tracefs_instance_is_new()* function checks if the given _instance_ is
 newly created by *tracefs_instance_create()*, or it has been in the system
 before that.
 
+The *tracefs_instances*() function returns a list of instances that exist in
+the system that match the regular expression _regex_. If _regex_ is NULL, then
+it will match all instances that exist. The returned list must be freed with
+*tracefs_list_free*(3). Note, if no instances are found an empty list is returned
+and that too needs to be free with *tracefs_list_free*(3).
+
 RETURN VALUE
 ------------
 The *tracefs_instance_create()* and *tracefs_instance_alloc()* functions return a pointer to
@@ -68,6 +75,11 @@ trace instance in the system, or false if the trace instance already
 existed in the system when _instance_ was allocated by
 *tracefs_instance_create()* or *tracefs_instance_alloc()*.
 
+The *tracefs_instances()* returns a list of instance names that exist on the system.
+The list must be freed with *tracefs_list_free*(3). An empty list is returned if
+no instance exists that matches _regex_, and this needs to be freed with
+*tracefs_list_free*(3) as well. NULL is returned on error.
+
 EXAMPLE
 -------
 [source,c]
diff --git a/Documentation/libtracefs.txt b/Documentation/libtracefs.txt
index 12df3ce3b7af..5864a5de61e6 100644
--- a/Documentation/libtracefs.txt
+++ b/Documentation/libtracefs.txt
@@ -21,6 +21,7 @@ Trace instances:
 	int *tracefs_instance_destroy*(struct tracefs_instance pass:[*]_instance_);
 	struct tracefs_instance pass:[*]*tracefs_instance_alloc*(const char pass:[*]_tracing_dir_, const char pass:[*]_name_);
 	void *tracefs_instance_free*(struct tracefs_instance pass:[*]_instance_);
+	char pass:[**]*tracefs_instances*(const char pass:[*]_regex_);
 	bool *tracefs_instance_is_new*(struct tracefs_instance pass:[*]_instance_);
 	bool *tracefs_file_exists*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_name_);
 	bool *tracefs_dir_exists*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_name_);
-- 
2.34.1

[PATCH 05/11] libtracefs: Hide tracefs_list_pop() and make it trace_list_pop()

[Steven Rostedt]

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

The tracefs_list_pop() is not ready to be exposed as an API. Make it
hidden and rename it to trace_list_pop().

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 include/tracefs-local.h |  1 +
 include/tracefs.h       |  1 -
 src/tracefs-hist.c      | 10 +++++-----
 src/tracefs-utils.c     |  6 +++---
 4 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/include/tracefs-local.h b/include/tracefs-local.h
index bf157e11aaea..926fd02c3d1e 100644
--- a/include/tracefs-local.h
+++ b/include/tracefs-local.h
@@ -71,6 +71,7 @@ struct tracefs_options_mask *
 enabled_opts_mask(struct tracefs_instance *instance);
 
 char **trace_list_create_empty(void);
+int trace_list_pop(char **list);
 
 char *append_string(char *str, const char *delim, const char *add);
 int trace_test_state(int state);
diff --git a/include/tracefs.h b/include/tracefs.h
index 1848ad0aa668..301f1b155ba1 100644
--- a/include/tracefs.h
+++ b/include/tracefs.h
@@ -75,7 +75,6 @@ int tracefs_error_clear(struct tracefs_instance *instance);
 void tracefs_list_free(char **list);
 char **tracefs_list_add(char **list, const char *string);
 int tracefs_list_size(char **list);
-int tracefs_list_pop(char **list);
 
 /**
  * tracefs_trace_on_get_fd - Get a file descriptor of "tracing_on" in given instance
diff --git a/src/tracefs-hist.c b/src/tracefs-hist.c
index aec61ad52e72..5a89be2876d2 100644
--- a/src/tracefs-hist.c
+++ b/src/tracefs-hist.c
@@ -1096,14 +1096,14 @@ static int add_synth_fields(struct tracefs_synth *synth,
 
 	ret = asprintf(&str, "$%s", name);
 	if (ret < 0) {
-		tracefs_list_pop(synth->synthetic_fields);
+		trace_list_pop(synth->synthetic_fields);
 		return -1;
 	}
 
 	list = tracefs_list_add(synth->synthetic_args, str);
 	free(str);
 	if (!list) {
-		tracefs_list_pop(synth->synthetic_fields);
+		trace_list_pop(synth->synthetic_fields);
 		return -1;
 	}
 
@@ -1156,7 +1156,7 @@ int tracefs_synth_add_match_field(struct tracefs_synth *synth,
 
 	list = tracefs_list_add(synth->end_keys, end_match_field);
 	if (!list) {
-		tracefs_list_pop(synth->start_keys);
+		trace_list_pop(synth->start_keys);
 		return -1;
 	}
 	synth->end_keys = list;
@@ -1176,8 +1176,8 @@ int tracefs_synth_add_match_field(struct tracefs_synth *synth,
 	return 0;
 
  pop_lists:
-	tracefs_list_pop(synth->start_keys);
-	tracefs_list_pop(synth->end_keys);
+	trace_list_pop(synth->start_keys);
+	trace_list_pop(synth->end_keys);
 	return -1;
 }
 
diff --git a/src/tracefs-utils.c b/src/tracefs-utils.c
index a502c2dec736..0ad9a35e7819 100644
--- a/src/tracefs-utils.c
+++ b/src/tracefs-utils.c
@@ -448,14 +448,14 @@ char **tracefs_list_add(char **list, const char *string)
 	return list;
 }
 
-/**
- * tracefs_list_pop - Removes the last string added
+/*
+ * trace_list_pop - Removes the last string added
  * @list: The list to remove the last event from
  *
  * Returns 0 on success, -1 on error.
  * Returns 1 if the list is empty or NULL.
  */
-int tracefs_list_pop(char **list)
+__hidden int trace_list_pop(char **list)
 {
 	unsigned long size;
 
-- 
2.34.1

[PATCH 06/11] libtracefs: Add documentation for tracefs_list_add/size()

[Steven Rostedt]

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

The functions tracefs_list_add() and tracefs_list_size() are missing from
the man pages.

Add them.

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

diff --git a/Documentation/libtracefs-utils.txt b/Documentation/libtracefs-utils.txt
index 9478911afbae..ddbd6759bb1b 100644
--- a/Documentation/libtracefs-utils.txt
+++ b/Documentation/libtracefs-utils.txt
@@ -3,8 +3,8 @@ libtracefs(3)
 
 NAME
 ----
-tracefs_tracers, tracefs_get_clock, tracefs_list_free -
-Helper functions for working with trace file system.
+tracefs_tracers, tracefs_get_clock, tracefs_list_free, tracefs_list_add,
+tracefs_list_size - Helper functions for working with trace file system.
 
 SYNOPSIS
 --------
@@ -15,6 +15,8 @@ SYNOPSIS
 char pass:[*]pass:[*]*tracefs_tracers*(const char pass:[*]_tracing_dir_);
 char pass:[*]*tracefs_get_clock*(struct tracefs_instance pass:[*]_instance_);
 void *tracefs_list_free*(char pass:[*]pass:[*]_list_);
+char pass:[**]*tracefs_list_add*(char **_list_, const char *_string_);
+int *tracefs_list_size*(char pass:[**]_list_);
 --
 
 DESCRIPTION
@@ -36,6 +38,18 @@ The *tracefs_list_free()* function frees an array of strings, returned by
 *tracefs_event_systems()*, *tracefs_system_events()* and *tracefs_tracers()*
 APIs.
 
+The *tracefs_list_add()* function adds _string_ to the string _list_. If
+_list_ is NULL, then a new list is created with the first element a copy
+of _string_, and the second element will be a NULL pointer.  If _list_ is
+not NULL, then it is reallocated to include a new element and a NULL terminator,
+and the new allocated array is returned. The list passed in should be ignored,
+as it wil be freed if a new one was allocated.
+
+The *tracefs_list_size()* is a fast way to find out the number of elements
+in a string array that is to be freed with *tracefs_list_free()*. Note, this
+depends on meta data that is created for these lists and will not work on
+normal string arrays like argv.
+
 RETURN VALUE
 ------------
 The *tracefs_tracers()* returns array of strings. The last element in that
@@ -45,6 +59,16 @@ In case of an error, NULL is returned.
 The *tracefs_get_clock()* returns string, that must be freed with free(), or NULL
 in case of an error.
 
+The *tracefs_list_add()* returns an allocated string array that must be freed
+with *tracefs_list_free()* on success or NULL on error. If NULL is returned,
+then the passed in _list_ is untouched. Thus, *tracefs_list_add()* should be
+treated similarly to *realloc*(3).
+
+The *tracefs_list_size()* returns the number of strings in the _list_. The
+passed in list must be one that is to be freed with *tracefs_list_free()*
+as the list has meta data that is used to determine the size and this does
+not work on any normal string array like argv.
+
 EXAMPLE
 -------
 [source,c]
diff --git a/Documentation/libtracefs.txt b/Documentation/libtracefs.txt
index 5864a5de61e6..ad4d5849954d 100644
--- a/Documentation/libtracefs.txt
+++ b/Documentation/libtracefs.txt
@@ -72,6 +72,8 @@ Function filters:
 
 Trace helper functions:
 	void *tracefs_list_free*(char pass:[*]pass:[*]_list_);
+	char pass:[**]*tracefs_list_add*(char **_list_, const char *_string_);
+	int *tracefs_list_size*(char pass:[**]_list_);
 	char pass:[*]*tracefs_get_clock*(struct tracefs_instance pass:[*]_instance_);
 	int *tracefs_trace_is_on*(struct tracefs_instance pass:[*]_instance_);
 	int *tracefs_trace_on*(struct tracefs_instance pass:[*]_instance_);
-- 
2.34.1

[PATCH 07/11] libtracefs: Add documentation for tracefs_iterate_stop()

[Steven Rostedt]

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

The function tracefs_iterate_stop() is missing from the man pages.

Add it.

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 Documentation/libtracefs-events.txt | 9 +++++++--
 Documentation/libtracefs.txt        | 1 +
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/Documentation/libtracefs-events.txt b/Documentation/libtracefs-events.txt
index 3c2b95dcc762..f998c79b04ec 100644
--- a/Documentation/libtracefs-events.txt
+++ b/Documentation/libtracefs-events.txt
@@ -3,8 +3,8 @@ libtracefs(3)
 
 NAME
 ----
-tracefs_event_systems, tracefs_system_events, tracefs_event_enable,
-tracefs_event_disable,  tracefs_iterate_raw_events - Work with trace systems and events.
+tracefs_event_systems, tracefs_system_events, tracefs_event_enable, tracefs_event_disable,
+tracefs_iterate_raw_events, tracefs_iterate_stop - Work with trace systems and events.
 
 SYNOPSIS
 --------
@@ -22,6 +22,7 @@ int *tracefs_iterate_raw_events*(struct tep_handle pass:[*]_tep_, struct tracefs
 				 cpu_set_t pass:[*]_cpus_, int _cpu_size_,
 				 int (pass:[*]_callback_)(struct tep_event pass:[*], struct tep_record pass:[*], int, void pass:[*]),
 				 void pass:[*]_callback_context_);
+void *tracefs_iterate_stop*(struct tracefs_instance pass:[*]_instance_);
 
 --
 
@@ -75,6 +76,10 @@ record is; The record representing the event; The CPU that the event
 occurred on; and a pointer to user specified _callback_context_. If the _callback_
 returns non-zero, the iteration stops.
 
+Use *tracefs_iterate_stop()* to force a executing *tracefs_iterate_raw_events()*
+to halt. This can be called from either a callback that is called by
+the iterator (even though a return of non-zero will stop it), or from another
+thread.
 
 RETURN VALUE
 ------------
diff --git a/Documentation/libtracefs.txt b/Documentation/libtracefs.txt
index ad4d5849954d..0e339af60f4f 100644
--- a/Documentation/libtracefs.txt
+++ b/Documentation/libtracefs.txt
@@ -52,6 +52,7 @@ Trace events:
 	int *tracefs_event_disable*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_,
                             const char pass:[*]_event_);
 	int *tracefs_iterate_raw_events*(struct tep_handle pass:[*]_tep_, struct tracefs_instance pass:[*]_instance_, cpu_set_t pass:[*]_cpus_, int _cpu_size_, int (pass:[*]_callback_)(struct tep_event pass:[*], struct tep_record pass:[*], int, void pass:[*]), void pass:[*]_callback_context_);
+	void *tracefs_iterate_stop*(struct tracefs_instance pass:[*]_instance_);
 	struct tep_handle pass:[*]*tracefs_local_events*(const char pass:[*]_tracing_dir_);
 	struct tep_handle pass:[*]*tracefs_local_events_system*(const char pass:[*]_tracing_dir_, const char pass:[*] const pass:[*]_sys_names_);
 	int *tracefs_fill_local_events*(const char pass:[*]_tracing_dir_, struct tep_handle pass:[*]_tep_, int pass:[*]_parsing_failures_);
-- 
2.34.1

[PATCH 08/11] libtracefs: Add documentation for tracefs_option_id()

[Steven Rostedt]

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

The function tracefs_option_id() is missing from the man pages.

Add it.

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 Documentation/libtracefs-option-get.txt | 11 +++++++++--
 Documentation/libtracefs.txt            |  1 +
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/Documentation/libtracefs-option-get.txt b/Documentation/libtracefs-option-get.txt
index dce5afab4894..8a688a7dd8f2 100644
--- a/Documentation/libtracefs-option-get.txt
+++ b/Documentation/libtracefs-option-get.txt
@@ -3,8 +3,8 @@ libtracefs(3)
 
 NAME
 ----
-tracefs_options_get_supported, tracefs_option_is_supported,
-tracefs_options_get_enabled, tracefs_option_is_enabled, tracefs_option_mask_is_set
+tracefs_options_get_supported, tracefs_option_is_supported, tracefs_options_get_enabled,
+tracefs_option_is_enabled, tracefs_option_mask_is_set, tracefs_option_id
 - Get and check ftrace options.
 
 SYNOPSIS
@@ -18,6 +18,7 @@ bool *tracefs_option_is_supported*(struct tracefs_instance pass:[*]_instance_, e
 const struct tracefs_options_mask pass:[*]*tracefs_options_get_enabled*(struct tracefs_instance pass:[*]_instance_);
 bool *tracefs_option_is_enabled*(struct tracefs_instance pass:[*]_instance_, enum tracefs_option_id _id_);
 bool *tracefs_option_mask_is_set*(const struct tracefs_options_mask *options, enum tracefs_option_id id);
+enum tracefs_option_id *tracefs_option_id*(const char pass:[*]_name_);
 --
 
 DESCRIPTION
@@ -43,6 +44,9 @@ given _instance_. If _instance_ is NULL, the top trace instance is used.
 The *tracefs_option_mask_is_set()* function checks if the bit, corresponding to the option with _id_ is
 set in the _options_ bitmask returned from *tracefs_option_get_enabled()* and *tracefs_option_is_supported()*.
 
+The *tracefs_option_id()* converts an option _name_ into its corresponding id, if it is found.
+This allows to find the option _id_ to use in the other functions if only the _name_ is known.
+
 RETURN VALUE
 ------------
 The *tracefs_options_get_supported()* and *tracefs_options_get_enabled()* functions, on success,
@@ -56,6 +60,9 @@ option in supported / enabled, or false otherwise.
 The *tracefs_option_mask_is_set()* returns true if the corresponding option is set in the mask
 or false otherwise.
 
+The *tracefs_option_id()* returns the corresponding id defined by *tracefs_options*(3) from
+the given _name_. If the _name_ can not be found, then TRACEFS_OPTION_INVALID is returned.
+
 EXAMPLE
 -------
 [source,c]
diff --git a/Documentation/libtracefs.txt b/Documentation/libtracefs.txt
index 0e339af60f4f..44629e32d202 100644
--- a/Documentation/libtracefs.txt
+++ b/Documentation/libtracefs.txt
@@ -97,6 +97,7 @@ Trace options:
 	int *tracefs_option_enable*(struct tracefs_instance pass:[*]_instance_, enum tracefs_option_id _id_);
 	int *tracefs_option_disable*(struct tracefs_instance pass:[*]_instance_, enum tracefs_option_id _id_);
 	const char pass:[*]*tracefs_option_name*(enum tracefs_option_id _id_);
+	enum tracefs_option_id *tracefs_option_id*(const char pass:[*]_name_);
 
 Ftrace tracers:
 	char pass:[*]pass:[*]*tracefs_tracers*(const char pass:[*]_tracing_dir_);
-- 
2.34.1

[PATCH 09/11] libtracefs: Add man pages for tracefs_event_file_*() functions

[Steven Rostedt]

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

Add the following functions to the man pages:
   tracefs_event_get_file()
   tracefs_event_file_read()
   tracefs_event_file_write()
   tracefs_event_file_append()
   tracefs_event_file_clear()
   tracefs_event_file_exists()

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 Documentation/libtracefs-events-file.txt | 217 +++++++++++++++++++++++
 Documentation/libtracefs.txt             |  11 ++
 2 files changed, 228 insertions(+)
 create mode 100644 Documentation/libtracefs-events-file.txt

diff --git a/Documentation/libtracefs-events-file.txt b/Documentation/libtracefs-events-file.txt
new file mode 100644
index 000000000000..5102cc5e6859
--- /dev/null
+++ b/Documentation/libtracefs-events-file.txt
@@ -0,0 +1,217 @@
+libtracefs(3)
+=============
+
+NAME
+----
+tracefs_event_get_file, tracefs_event_file_read, tracefs_event_file_write, tracefs_event_file_append,
+tracefs_event_file_clear, tracefs_event_file_exists - Work with trace event files.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <tracefs.h>*
+
+char pass:[*]*tracefs_event_get_file*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			     const char pass:[*]_file_);
+char pass:[*]*tracefs_event_file_read*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			      const char pass:[*]_file_, int pass:[*]_psize_);
+int *tracefs_event_file_write*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			     const char pass:[*]_file_, const char pass:[*]_str_);
+int *tracefs_event_file_append*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			      const char pass:[*]_file_, const char pass:[*]_str_);
+int *tracefs_event_file_clear*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			     const char pass:[*]_file_);
+bool *tracefs_event_file_exists*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			       const char pass:[*]_file_)
+
+--
+
+DESCRIPTION
+-----------
+These are functions for accessing tracefs event specific files.
+These functions act similar to the tracefs instance file functions
+but are easier to get to if the system and events are known before hand.
+
+The *tracefs_event_get_file()* returns the full path of the _file_ for
+the given _system_ and _event_ that is within the given _instance_.
+If _instance_ is NULL, then the file for the _event_ for the top level
+instance is returned. Note, there is no check to see if the file actually
+exists or even if the system and event exist. It only creates the path
+name for such an event if it did exist. This acts similar to the
+*tracefs_instance_get_file*(3), but is to be used to get to event files
+if the _system_ and _event_ are already known.
+
+The *tracefs_event_file_read()* reads the content for the _event_ _file_
+for the given _instance_ or the top level instance if _instance_ is
+NULL. The content of the file is returned and _psize_ is set to the amount
+of data that was read. The returned content must be freed with *free*(3).
+This acts similar to the *tracefs_instance_file_read*(3), but is
+to be used to read the event file if the _system_ and _event_ are already
+known.
+
+The *tracefs_event_file_write()* writes _str_ to the _event_ _file_.
+It will truncate anything that is already in that file. 
+This acts similar to the *tracefs_instance_file_write*(3), but is
+to be used to read the event file if the _system_ and _event_ are already
+known.
+
+The *tracefs_event_file_append()* appends _str_ to the _event_ _file_.
+It will not clear out the file as it writes _sting_.
+This acts similar to the *tracefs_instance_file_append*(3), but is
+to be used to read the event file if the _system_ and _event_ are already
+known.
+
+The *tracefs_event_file_clear()* clears the content of the _event_ _file_.
+This acts similar to the *tracefs_instance_file_clear*(3), but is
+to be used to read the event file if the _system_ and _event_ are already
+known.
+
+The *tracefs_event_file_exists()* returns true if the _event_ _file_
+exists, and false otherwise. This acts similar to the *tracefs_instance_file_exists*(3),
+but is to be used to read the event file if the _system_ and _event_ are already
+known.
+
+RETURN VALUE
+------------
+*tracefs_event_get_file()* returns the path of the given _system_/_event_ _file_ on
+success and NULL on error. The return value must be freed with *tracefs_put_tracing_file*(3).
+
+*tracefs_event_file_read()* reads the content of the _system_/_event_ _file_ or
+NULL on error. The return pointer must be freed with *free*(3).
+
+*tracefs_event_file_write()* and *tracefs_event_file_append()* returns the number of
+bytes written to the _system_/_event_ _file_ or negative on error.
+
+*tracefs_event_file_clear()* returns zero on success and -1 on error.
+
+*tracefs_event_file_exists()* returns true if the _system_/_event_ _file_ exists for
+the given _instance_ (or top level if _instance_ is NULL) or false otherwise.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <tracefs.h>
+
+int main(int argc, char **argv)
+{
+	char *system;
+	char *event;
+	char *file;
+	char *cmd = NULL;
+	char *buf;
+	char *str;
+	char ch = 'r';
+	int size;
+
+	if (argc < 4) {
+		printf("usage: %s sytem event file [(-a|-w) write | -c]\n"
+		       "   reads the system/event file or writes if [write is supplied]\n",
+		       argv[0]);
+		exit(0);
+	}
+
+	system = argv[1];
+	event = argv[2];
+	file = argv[3];
+	if (argc > 4)
+		cmd = argv[4];
+
+	if (!tracefs_event_file_exists(NULL, system, event, file)) {
+		fprintf(stderr, "File %s/%s/%s does not exist\n",
+				system, event, file);
+		exit(-1);
+	}
+
+	if (cmd) {
+		if (cmd[0] != '-')
+			ch = cmd[0];
+		else
+			ch = cmd[1];
+		if (!ch)
+			ch = 'c';
+	}
+
+	switch (ch) {
+	case 'r':
+		buf = tracefs_event_file_read(NULL, system, event, file, &size);
+		if (buf)
+			printf("%s", buf);
+		else
+			fprintf(stderr, "Failed to read %s/%s/%s\n",
+				system, event, file);
+		free(buf);
+		break;
+	case 'w':
+	case 'a':
+		if (argc < 6) {
+			fprintf(stderr, "%s command requires something to write\n",
+				ch == 'w' ? "write" : "append");
+			exit(-1);
+		}
+		if (ch == 'w')
+			size = tracefs_event_file_write(NULL, system, event, file, argv[5]);
+		else
+			size = tracefs_event_file_append(NULL, system, event, file, argv[5]);
+		if (size < 0) {
+			fprintf(stderr, "Failed to write '%s' to %s/%s/%s\n",
+					argv[5], system, event, file);
+			exit(-1);
+		}
+		break;
+	case 'c':
+		if (tracefs_event_file_clear(NULL, system, event, file) < 0) {
+			fprintf(stderr, "Failed to clear %s/%s/%s\n",
+				system, event, file);
+			exit(-1);
+		}
+		break;
+	default:
+		fprintf(stderr, "Unknown command '%c'\n", ch);
+		exit(-1);
+	}
+	exit(0);
+}
+--
+FILES
+-----
+[verse]
+--
+*tracefs.h*
+	Header file to include in order to have access to the library APIs.
+*-ltracefs*
+	Linker switch to add when building a program that uses the library.
+--
+
+SEE ALSO
+--------
+*libtracefs*(3),
+*libtraceevent*(3),
+*trace-cmd*(1)
+
+AUTHOR
+------
+[verse]
+--
+*Steven Rostedt* <rostedt@goodmis.org>
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtracefs is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
+
+COPYING
+-------
+Copyright \(C) 2022 Google, Inc. Free use of this software is granted under
+the terms of the GNU Public License (GPL).
diff --git a/Documentation/libtracefs.txt b/Documentation/libtracefs.txt
index 44629e32d202..82cb5744b7b9 100644
--- a/Documentation/libtracefs.txt
+++ b/Documentation/libtracefs.txt
@@ -57,6 +57,17 @@ Trace events:
 	struct tep_handle pass:[*]*tracefs_local_events_system*(const char pass:[*]_tracing_dir_, const char pass:[*] const pass:[*]_sys_names_);
 	int *tracefs_fill_local_events*(const char pass:[*]_tracing_dir_, struct tep_handle pass:[*]_tep_, int pass:[*]_parsing_failures_);
 	int *tracefs_load_cmdlines*(const char pass:[*]_tracing_dir_, struct tep_handle pass:[*]_tep_);
+	char pass:[*]*tracefs_event_get_file*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			     const char pass:[*]_file_);
+	char pass:[*]*tracefs_event_file_read*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			      const char pass:[*]_file_, int pass:[*]_psize_);
+	int *tracefs_event_file_write*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			     const char pass:[*]_file_, const char pass:[*]_str_);
+	int *tracefs_event_file_append*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			      const char pass:[*]_file_, const char pass:[*]_str_);
+	int *tracefs_event_file_clear*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			     const char pass:[*]_file_);
+	bool *tracefs_event_file_exists*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
 
 Event filters:
 	int *tracefs_filter_string_append*(struct tep_event pass:[*]_event_, char pass:[**]_filter_,
-- 
2.34.1

[PATCH 10/11] libtracefs: Do not check for deprecated functions

[Steven Rostedt]

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

tracefs_event_append_filter() and tracefs_event_verify_filter() are
deprecated, where tracefs_filter_string_append() and
tracefs_filter_string_verify() should be used instead. They are purposely
not in the man pages. Do not have the checker warn about them.

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 check-manpages.sh | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/check-manpages.sh b/check-manpages.sh
index 33419a92fd2f..d3ec6af65c50 100755
--- a/check-manpages.sh
+++ b/check-manpages.sh
@@ -37,8 +37,13 @@ for man in ${MAIN}-*.txt; do
 	done
 done
 
+DEPRECATED="*tracefs_event_append_filter* *tracefs_event_verify_filter*"
+
 sed -ne 's/^[a-z].*[ \*]\([a-z_][a-z_]*\)(.*/\1/p' -e 's/^\([a-z_][a-z_]*\)(.*/\1/p' ../include/tracefs.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"
-- 
2.34.1

[PATCH 11/11] libtracefs: Run the check-manpages.sh on building of docs

[Steven Rostedt]

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

When "make doc" is called, run the check-manpages.sh. This will ensure
that we have all the covered man pages whenever we build the documents.

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 Makefile | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 544684c1c37c..b43e0aae3a96 100644
--- a/Makefile
+++ b/Makefile
@@ -282,7 +282,7 @@ install_pkgconfig: $(PKG_CONFIG_FILE)
 	$(Q)$(call , $(PKG_CONFIG_FILE)) \
 		$(call do_install_pkgconfig_file,$(prefix))
 
-doc:
+doc: check_doc
 	$(Q)$(call descend,$(src)/Documentation,all)
 
 doc_clean:
@@ -291,6 +291,9 @@ doc_clean:
 install_doc:
 	$(Q)$(call descend,$(src)/Documentation,install)
 
+check_doc: force
+	$(Q)$(src)/check-manpages.sh $(src)/Documentation
+
 define build_uninstall_script
 	$(Q)mkdir $(BUILD_OUTPUT)/tmp_build
 	$(Q)$(MAKE) -C $(src) DESTDIR=$(BUILD_OUTPUT)/tmp_build/ O=$(BUILD_OUTPUT) $1 > /dev/null
-- 
2.34.1