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

Commit Message

Steven Rostedt Feb. 23, 2022, 12:30 a.m. UTC

From: "Steven Rostedt (Google)" <[e-mail]>

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

Add it.

Signed-off-by: Steven Rostedt (Google) <[e-mail]>
---
 Documentation/libtracefs-instances-manage.txt | 14 +++++++++++++-
 Documentation/libtracefs.txt                  |  1 +
 2 files changed, 14 insertions(+), 1 deletion(-)

Patch

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_);