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

[Steven Rostedt <rostedt@goodmis.org>]

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