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

[Tzvetomir Stoyanov <tz.stoyanov@gmail.com>]

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



-- 
Tzvetomir (Ceco) Stoyanov
VMware Open Source Technology Center