Re: [PATCH 6/9] libtracefs man pages: APIs for working with files in trace instances.

[Steven Rostedt <rostedt@goodmis.org>]

On Thu, 17 Dec 2020 11:46:23 +0200
"Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com> wrote:

> Documented APIs:
> tracefs_file_exists()
> tracefs_dir_exists()
> tracefs_instance_get_file()
> tracefs_instance_get_dir()
> tracefs_instance_file_write()
> tracefs_instance_file_read()
> 
> Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
> ---
>  Documentation/libtracefs-instances-files.txt | 157 +++++++++++++++++++
>  1 file changed, 157 insertions(+)
>  create mode 100644 Documentation/libtracefs-instances-files.txt
> 
> diff --git a/Documentation/libtracefs-instances-files.txt b/Documentation/libtracefs-instances-files.txt
> new file mode 100644
> index 0000000..f1e9707
> --- /dev/null
> +++ b/Documentation/libtracefs-instances-files.txt
> @@ -0,0 +1,157 @@
> +libtracefs(3)
> +=============
> +
> +NAME
> +----
> +tracefs_file_exists, tracefs_dir_exists, tracefs_instance_get_file,
> +tracefs_instance_get_dir, tracefs_instance_file_write,
> +tracefs_instance_file_read - Work with files in tracing instances.
> +
> +SYNOPSIS
> +--------
> +[verse]
> +--
> +*#include <tracefs.h>*
> +
> +bool *tracefs_file_exists*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_name_);
> +bool *tracefs_dir_exists*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_name_);
> +char pass:[*]*tracefs_instance_get_file*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_);
> +char pass:[*]*tracefs_instance_get_dir*(struct tracefs_instance pass:[*]_instance_);
> +int *tracefs_instance_file_write*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, const char pass:[*]_str_);
> +char pass:[*]*tracefs_instance_file_read*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_file_, int pass:[*]_psize_);
> +
> +--
> +
> +DESCRIPTION
> +-----------
> +This set of APIs can be used to work with trace files in all trace instances.

> +All they have _instance_ argument, to limit the scope on the given trace _instance_ only.
> +If _instance_ is NULL, the scope is limited to the main trace instance.

Replace the above with:

  "Each of these APIs take an _instance_ argument, that can be NULL to act
  on the top level instance. Otherwise, it acts on an instance created with
  *tracefs_insance_create*(3)".

> +
> +The _tracefs_file_exists()_ function checks if a file with _name_ exists in _instance_.
> +
> +The _tracefs_dir_exists()_ function checks if a directory with _name_ exists in _instance_.
> +
> +The _tracefs_instance_get_file()_ function returns the full path of the file with
> +given _name_ in _instance_.

Should add: "Note, it does not check if the file exists in the instance".

> +
> +The _tracefs_instance_get_dir()_ function  returns the full path of the directory with
> +given _name_ in _instance_.

 "Note, it does not check if the directory exists in the instance."

> +
> +The _tracefs_instance_file_write()_ function writes a string _str_ in a _file_ from
> +the given _instance_, without the terminating NULL character.
> +
> +The _tracefs_instance_file_read()_ function reads the content of a _file_  from
> +the given _instance_.
> +
> +RETURN VALUE
> +------------
> +The _tracefs_file_exists()_ and  _tracefs_dir_exists()_ functions return true if the
> +file / directory exist in the given instance or false if they do not exist.

 "or false if it does not exist."

The "it" references the file or directory, not the functions, and "the"
makes it singular.

-- Steve


> +
> +The _tracefs_instance_get_file()_ and _tracefs_instance_get_dir()_ functions return
> +a string or NULL in case of an error. The returned string must be freed with
> +_tracefs_put_tracing_file()_.
> +
> +The _tracefs_instance_file_write()_ function returns the number of written bytes,
> +or -1 in case of an error.
> +
> +The _tracefs_instance_file_read()_ function returns a pointer to a NULL terminated
> +string, read from the file, or NULL in case of an error. The returned string must
> +be freed with free().
> +