diff mbox series

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

Message ID 20201217094626.1402191-4-tz.stoyanov@gmail.com (mailing list archive)
State Superseded
Headers show
Series libtracefs man pages | expand

Commit Message

Tzvetomir Stoyanov (VMware) Dec. 17, 2020, 9:46 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) <tz.stoyanov@gmail.com>
---
 Documentation/libtracefs-files.txt | 111 +++++++++++++++++++++++++++++
 1 file changed, 111 insertions(+)
 create mode 100644 Documentation/libtracefs-files.txt

Comments

Steven Rostedt Dec. 18, 2020, 6:55 p.m. UTC | #1 
On Thu, 17 Dec 2020 11:46:20 +0200
"Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com> wrote:

> +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.

How should it 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.

Should state how it should be freed. tracefs_put_tracing_file() or free() ?

If it is free(), then stating:

 "The returned string must be freed with free()"

is fine.

> +
> +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();
> +

Not a very useful example ;-)  We we can fix examples at a later time. I
plan on writing a lot of example code to post, and some can make their way
into the man pages.

-- Steve
Tzvetomir Stoyanov (VMware) Dec. 21, 2020, 3:44 a.m. UTC | #2 
On Fri, Dec 18, 2020 at 8:55 PM Steven Rostedt <rostedt@goodmis.org> wrote:
>
> On Thu, 17 Dec 2020 11:46:20 +0200
> "Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com> wrote:
>
> > +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.
>
> How should it be freed?
I'll add " with free()" in the next version of the patch, but I was
wondering if the
user should use "tracefs_put_tracing_file()" instead ? These APIs are not
consistent, may be they should be renamed. Now we have:

   tracefs_get_tracing_file() / tracefs_put_tracing_file()
   tracefs_get_tracing_dir() / returns static, must not be feed.
   tracefs_find_tracing_dir() / free()


>
> > +
> > +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.
>
> Should state how it should be freed. tracefs_put_tracing_file() or free() ?
>
> If it is free(), then stating:
>
>  "The returned string must be freed with free()"
>
> is fine.
>
> > +
> > +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();
> > +
>
> Not a very useful example ;-)  We we can fix examples at a later time. I
> plan on writing a lot of example code to post, and some can make their way
> into the man pages.
>
> -- Steve
Steven Rostedt Dec. 21, 2020, 4:10 a.m. UTC | #3 
On Mon, 21 Dec 2020 05:44:45 +0200
Tzvetomir Stoyanov <tz.stoyanov@gmail.com> wrote:

> > How should it be freed?
> I'll add " with free()" in the next version of the patch, but I was
> wondering if the
> user should use "tracefs_put_tracing_file()" instead ? These APIs are not
> consistent, may be they should be renamed.

Good point.

> Now we have:
> 
>    tracefs_get_tracing_file() / tracefs_put_tracing_file()
>    tracefs_get_tracing_dir() / returns static, must not be feed.
>    tracefs_find_tracing_dir() / free()

Perhaps we should change tracefs_get_tracing_dir() to simply:
tracefs_tracing_dir().


Hmm, what's the difference between "tracefs_find_tracing_dir() and
tracefs_get_tracing_dir() (or what we will call tracefs_tracing_dir())?

The only difference I see from the two descriptions is that one returns
a cached string and the other returns just an allocated string. Do we
even need tracefs_find_tracing_dir()?

> 
> 
> >
> > > +
> > > +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.

Just noticed the above typo. s/minted/mounted/

Although,  I wonder if a minted dir tastes good? ;-)

-- Steve

> > > +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.
> >
> > Should state how it should be freed. tracefs_put_tracing_file() or free() ?
> >
> > If it is free(), then stating:
> >
> >  "The returned string must be freed with free()"
> >
> > is fine.
> >
> > > +
> > > +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();
> > > +
> >
> > Not a very useful example ;-)  We we can fix examples at a later time. I
> > plan on writing a lot of example code to post, and some can make their way
> > into the man pages.
> >
> > -- Steve
> 
> 
>
Tzvetomir Stoyanov (VMware) Dec. 21, 2020, 5:03 a.m. UTC | #4 
On Mon, Dec 21, 2020 at 6:10 AM Steven Rostedt <rostedt@goodmis.org> wrote:
>
> On Mon, 21 Dec 2020 05:44:45 +0200
> Tzvetomir Stoyanov <tz.stoyanov@gmail.com> wrote:
>
> > > How should it be freed?
> > I'll add " with free()" in the next version of the patch, but I was
> > wondering if the
> > user should use "tracefs_put_tracing_file()" instead ? These APIs are not
> > consistent, may be they should be renamed.
>
> Good point.
>
> > Now we have:
> >
> >    tracefs_get_tracing_file() / tracefs_put_tracing_file()
> >    tracefs_get_tracing_dir() / returns static, must not be feed.
> >    tracefs_find_tracing_dir() / free()
>
> Perhaps we should change tracefs_get_tracing_dir() to simply:
> tracefs_tracing_dir().
>
>
> Hmm, what's the difference between "tracefs_find_tracing_dir() and
> tracefs_get_tracing_dir() (or what we will call tracefs_tracing_dir())?
>
> The only difference I see from the two descriptions is that one returns
> a cached string and the other returns just an allocated string. Do we
> even need tracefs_find_tracing_dir()?

The tracefs_find_tracing_dir() function is used in trace-cmd, but I agree that
it can be removed. I'll rename tracefs_get_tracing_dir() to
tracefs_tracing_dir()
and remove tracefs_find_tracing_dir() API. Going to change trace-cmd to use
only tracefs_tracing_dir() API.

>
> >
> >
> > >
> > > > +
> > > > +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.
>
> Just noticed the above typo. s/minted/mounted/
>
> Although,  I wonder if a minted dir tastes good? ;-)
>
> -- Steve
>
> > > > +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.
> > >
> > > Should state how it should be freed. tracefs_put_tracing_file() or free() ?
> > >
> > > If it is free(), then stating:
> > >
> > >  "The returned string must be freed with free()"
> > >
> > > is fine.
> > >
> > > > +
> > > > +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();
> > > > +
> > >
> > > Not a very useful example ;-)  We we can fix examples at a later time. I
> > > plan on writing a lot of example code to post, and some can make their way
> > > into the man pages.
> > >
> > > -- Steve
> >
> >
> >
>
diff mbox series

Patch

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