Re: [PATCH 5/9] libtracefs man pages: APIs for managing trace instances.

[Steven Rostedt <rostedt@goodmis.org>]

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

> Documented APIs:
> tracefs_instance_create()
> tracefs_instance_destroy()
> tracefs_instance_free()
> tracefs_instance_is_new()
> 
> Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
> ---
>  Documentation/libtracefs-instances-manage.txt | 104 ++++++++++++++++++
>  1 file changed, 104 insertions(+)
>  create mode 100644 Documentation/libtracefs-instances-manage.txt
> 
> diff --git a/Documentation/libtracefs-instances-manage.txt b/Documentation/libtracefs-instances-manage.txt
> new file mode 100644
> index 0000000..ca08269
> --- /dev/null
> +++ b/Documentation/libtracefs-instances-manage.txt
> @@ -0,0 +1,104 @@
> +libtracefs(3)
> +=============
> +
> +NAME
> +----
> +tracefs_instance_create, tracefs_instance_destroy, tracefs_instance_free,
> +tracefs_instance_is_new - Manage trace instances.
> +
> +SYNOPSIS
> +--------
> +[verse]
> +--
> +*#include <tracefs.h>*
> +
> +struct tracefs_instance pass:[*]*tracefs_instance_create*(const char pass:[*]_name_);
> +int *tracefs_instance_destroy*(struct tracefs_instance pass:[*]_instance_);
> +void *tracefs_instance_free*(struct tracefs_instance pass:[*]_instance_);
> +bool *tracefs_instance_is_new*(struct tracefs_instance pass:[*]_instance_);
> +
> +--
> +
> +DESCRIPTION
> +-----------
> +This set of functions can be used to manage trace instances.

We should add a description of what a trace instance is:

 "A trace instance is a sub buffer used by the Linux tracing system. Given
 a unique name, the events enabled in an instance do not affect the main
 tracing system, nor other instances, as events enabled in the main tracing
 system or other instances do not affect the given instance."



> +
> +The _tracefs_instance_create()_ function creates a new trace instance with given
> +_name_, if it does not already exist in the system. It allocates and initializes
> +a new tracefs_instance structure and returns it.

The above description is a little ambiguous to what happen if the instance
already exists in the system. Perhaps reword the above to:

 "The _tracefs_instance_create()_ function allocates and initializes a new
 tracefs_instance structure and returns it. If the instance does not yet
 exist in the system, it will be created."

> +
> +The _tracefs_instance_destroy()_ destroys the trace _instance_ and frees the
> +tracefs_instance structure.

 "The _tracefs_instance_destroy()_ frees the _instance_ structure, and will
 also remove the trace instance from the system."


> +
> +The _tracefs_instance_free()_ function frees the tracefs_instance structure,
> +without destroying the trace instance.
> +
> +The _tracefs_instance_is_new()_ function checks if the given _instance_ is newly
> +created by _tracefs_instance_create()_, or it has been in the system before that.

 "The _tracefs_instance_is_new()_ function returns true if the
 _tracefs_instance_create() that allocated _instance_ also created the
 trace instance in the system, or false if the trace instance already
 existed in the system when _instance_ was allocated by
 _tracefs_instance_create()_.

-- Steve

> +
> +RETURN VALUE
> +------------
> +The _tracefs_instance_create()_ function returns a pointer to a newly allocated
> +tracefs_instance structure. It must be freed with _tracefs_instance_destroy()_ or
> +_tracefs_instance_free()_.
> +
> +The _tracefs_instance_destroy()_ function returns -1 in case of an error,
> +or 0 otherwise.
> +
> +The _tracefs_instance_is_new()_ function returns true if the instance is
> +created by _tracefs_instance_create()_ or false if it was in the system
> +before that.
> +
> +