[v2,2/8] libtracefs man pages: APIs for locating trace directory and files.

Commit Message

Tzvetomir Stoyanov (VMware) Dec. 21, 2020, 6:02 a.m. UTC

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

Signed-off-by: Tzvetomir Stoyanov (VMware) <[e-mail]>
---
 Documentation/libtracefs-files.txt | 97 ++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 Documentation/libtracefs-files.txt

Comments

Steven Rostedt Dec. 21, 2020, 4 p.m. UTC | #1

On Mon, 21 Dec 2020 08:02:46 +0200
"Tzvetomir Stoyanov (VMware)" <[e-mail]> wrote:

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

The commit log was not updated. I'll fix this.

-- Steve

> 
> Signed-off-by: Tzvetomir Stoyanov (VMware) <[e-mail]>
> ---
>  Documentation/libtracefs-files.txt | 97 ++++++++++++++++++++++++++++++
>  1 file changed, 97 insertions(+)
>  create mode 100644 Documentation/libtracefs-files.txt
> 
> diff --git a/Documentation/libtracefs-files.txt b/Documentation/libtracefs-files.txt

Patch

diff --git a/Documentation/libtracefs-files.txt b/Documentation/libtracefs-files.txt
new file mode 100644
index 0000000..8bf9d75
--- /dev/null
+++ b/Documentation/libtracefs-files.txt
@@ -0,0 +1,97 @@ 
+libtracefs(3)
+=============
+
+NAME
+----
+tracefs_get_tracing_file, tracefs_put_tracing_file, tracefs_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_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_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 mounted. 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_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);
+	}
+...
+const char *trace_dir = tracefs_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* <[e-mail]>
+*Tzvetomir Stoyanov* <[e-mail]>
+--
+REPORTING BUGS
+--------------
+Report bugs to  <[e-mail]>
+
+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