[PATCH 3/9] libtracefs man pages: APIs for locating trace directory and files.

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

Documented APIs:
tracefs_get_tracing_file()
tracefs_put_tracing_file()
tracefs_get_tracing_dir()
tracefs_find_tracing_dir()

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 Documentation/libtracefs-files.txt | 111 +++++++++++++++++++++++++++++
 1 file changed, 111 insertions(+)
 create mode 100644 Documentation/libtracefs-files.txt

diff --git a/Documentation/libtracefs-files.txt b/Documentation/libtracefs-files.txt
new file mode 100644
index 0000000..b288892
--- /dev/null
+++ b/Documentation/libtracefs-files.txt
@@ -0,0 +1,111 @@
+libtracefs(3)
+=============
+
+NAME
+----
+tracefs_get_tracing_file, tracefs_put_tracing_file, tracefs_get_tracing_dir,
+tracefs_find_tracing_dir - Find locations of trace directory and files.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <tracefs.h>*
+
+char pass:[*]*tracefs_get_tracing_file*(const char pass:[*]_name_);
+void *tracefs_put_tracing_file*(char pass:[*]_name_);
+const char pass:[*]*tracefs_get_tracing_dir*(void);
+char pass:[*]*tracefs_find_tracing_dir*(void);
+--
+
+DESCRIPTION
+-----------
+This set of APIs can be used to find the full path of the trace file
+system mount point and trace files in it.
+
+The _tracefs_get_tracing_file()_ function returns the full path of the
+file with given _name_ in the trace file system. The function works
+only with files in the trasefs main directory, it is not trace instance
+aware. It is recommended to use _tracefs_instance_get_file()_ and
+_tracefs_instance_get_dir()_ instead. The returned string must be freed
+with _tracefs_put_tracing_file()_.
+
+The _tracefs_put_tracing_file()_ function frees trace file name,
+returned by _tracefs_get_tracing_file()_.
+
+The _tracefs_find_tracing_dir()_ function finds the mount point of the
+trace file system and returns a full path to it. If the file system is
+not mounted, it will mount it. The returned string must be freed.
+
+The _tracefs_get_tracing_dir()_ function returns the full path to the
+trace file system. In the first function call, the mount point of the
+tracing file system is located, cached and returned. It will mount it,
+if it is not minted. On any subsequent call the cached path is returned.
+The return string must _not_ be freed.
+
+RETURN VALUE
+------------
+The _tracefs_get_tracing_file()_ function returns a string or NULL in case
+of an error. The returned string must be freed with _tracefs_put_tracing_file()_.
+
+The _tracefs_find_tracing_dir()_ function returns a string or NULL in case
+of an error. The returned string must be freed.
+
+The _tracefs_get_tracing_dir()_ function returns a constant string or NULL
+in case of an error. The returned string must _not_ be freed.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <tracefs.h>
+...
+char *trace_on = tracefs_get_tracing_file("tracing_on");
+	if (trace_on) {
+		...
+		tracefs_put_tracing_file(trace_on);
+	}
+...
+char *trace_dir = tracefs_find_tracing_dir();
+	if (trace_dir) {
+		...
+		free(trace_dir);
+	}
+...
+const char *trace_dir = tracefs_get_tracing_dir();
+
+--
+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>
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>
+--
+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/
\ No newline at end of file
-- 
2.28.0