Re: [PATCH 7/9] libtracefs man pages: helper APIs for working with trace instances.

[Steven Rostedt <rostedt@goodmis.org>]

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

> Documented APIs:
> tracefs_instance_get_name()
> tracefs_instances_walk()
> tracefs_instance_exists()
> 
> Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
> ---
>  Documentation/libtracefs-instances-utils.txt | 111 +++++++++++++++++++
>  1 file changed, 111 insertions(+)
>  create mode 100644 Documentation/libtracefs-instances-utils.txt
> 
> diff --git a/Documentation/libtracefs-instances-utils.txt b/Documentation/libtracefs-instances-utils.txt
> new file mode 100644
> index 0000000..1630d5c
> --- /dev/null
> +++ b/Documentation/libtracefs-instances-utils.txt
> @@ -0,0 +1,111 @@
> +libtracefs(3)
> +=============
> +
> +NAME
> +----
> +tracefs_instance_get_name, tracefs_instances_walk, tracefs_instance_exists -
> +Helper functions for working with tracing instances.
> +
> +SYNOPSIS
> +--------
> +[verse]
> +--
> +*#include <tracefs.h>*
> +
> +const char pass:[*]*tracefs_instance_get_name*(struct tracefs_instance pass:[*]_instance_);
> +int *tracefs_instances_walk*(int (pass:[*]_callback_)(const char pass:[*], void pass:[*]), void pass:[*]_context)_;
> +bool *tracefs_instance_exists*(const char pass:[*]_name_);
> +
> +--
> +
> +DESCRIPTION
> +-----------
> +Helper functions for working with trace instances.
> +
> +The _tracefs_instance_get_name()_ function returns the name of the given _instance_.
> +Note that the top instance has no name, the function returns NULL for it.
> +
> +The _tracefs_instances_walk()_ function walks through all configured tracing
> +instances in the system and calls _callback_ for each one of them. The _context_
> +argument is passed to the _callback_, together with the instance name. If the
> +_callback_ returns non-zero, the iteration stops.

Does this include the top level instance? If not, this should be specified.


> +
> +The _tracefs_instance_exists()_ function checks if an instance with given _name_

   "with the given _name_"


> +exists in the system.
> +
> +RETURN VALUE
> +------------
> +The _tracefs_instance_get_name()_ returns string or NULL in case of the top


  "returns a string or "

> +instance. The returned string must _not_ be freed.
> +
> +The _tracefs_instances_walk()_ function returns 0, if all instances were iterated, 1
> +if the iteration was stopped by the _callback_, or -1 in case of an error.
> +
> +The _tracefs_instance_exists()_ returns true if an instance with given name

 "with the given name"

-- Steve

> +exists in the system or false otherwise.
> +
> +EXAMPLE
> +-------
> +[source,c]
> +--
> +#include <tracefs.h>
> +
> +struct tracefs_instance *inst;
> +....
> +char *name = tracefs_instance_get_name(inst);
> +
> +	if(name) {
> +		/* Got name of the instance */
> +	}
> +
> +...
> +static int instance_walk(char *name, void *context)
> +{
> +	/* Got instance with name */
> +	return 0;
> +}
> +...
> +	if (tracefs_instances_walk(instance_walk, NULL) < 0) {
> +		/* Error walking through the instances */
> +	}
> +...
> +	if (tracefs_instance_exists("foo")) {
> +		/* There is instance with name foo in the system */
> +	} else {
> +		/* There is no instance with name foo in the system */
> +	}
> +--
> +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