Re: [PATCH 4/6] libtracefs: Documentation for enable / disable tracing APIs

[Steven Rostedt <rostedt@goodmis.org>]

On Thu,  7 Jan 2021 10:32:48 +0200
"Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com> wrote:

> New man pages with documentation about:
>  tracefs_trace_is_on();
>  tracefs_trace_on();
>  tracefs_trace_off();
>  tracefs_trace_on_fd();
>  tracefs_trace_off_fd();
> 
> Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
> ---
>  Documentation/libtracefs-traceon.txt | 143 +++++++++++++++++++++++++++
>  1 file changed, 143 insertions(+)
>  create mode 100644 Documentation/libtracefs-traceon.txt
> 
> diff --git a/Documentation/libtracefs-traceon.txt b/Documentation/libtracefs-traceon.txt
> new file mode 100644
> index 0000000..af4b7f7
> --- /dev/null
> +++ b/Documentation/libtracefs-traceon.txt
> @@ -0,0 +1,143 @@
> +libtracefs(3)
> +=============
> +
> +NAME
> +----
> +tracefs_trace_is_on, tracefs_trace_on, tracefs_trace_off, tracefs_trace_on_fd,
> +tracefs_trace_off_fd - Functions to enable or disable tracing.
> +
> +SYNOPSIS
> +--------
> +[verse]
> +--
> +*#include <tracefs.h>*
> +
> +int *tracefs_trace_is_on*(struct tracefs_instance pass:[*]_instance_);
> +int *tracefs_trace_on*(struct tracefs_instance pass:[*]_instance_);
> +int *tracefs_trace_off*(struct tracefs_instance pass:[*]_instance_);
> +int *tracefs_trace_on_fd*(int _fd_);
> +int *tracefs_trace_off_fd*(int _fd_);
> +--
> +
> +DESCRIPTION
> +-----------
> +This set of functions can be used to check, enable or disable writing to the ring buffer in
> +the given trace instance. The tracing is enabled when writing to the ring buffer is enabled.
> +
> +The _tracefs_trace_is_on()_ function checks if tracing is enabled for the given _instance_. If
> +_instance_ is NULL, the top instance is used.
> +
> +The _tracefs_trace_on()_ and _tracefs_trace_off()_ functions set the tracing in the _instance_
> +to enable or disable state. If _instance_ is NULL, the top instance is used.
> +
> +The _tracefs_trace_on_fd()_ and _tracefs_trace_off_fd()_ functions set the tracing state to enable
> +or disable using the given _fd_. This file descriptor must be opened for writing with
> +*tracefs_instance_file_open*(3) for *tracing_on* file from desired trace instance. These functions
> +are faster than *tracefs_trace_on* and *tracefs_trace_off*.

Hmm, I think this should also add "tracefs_trace_on_get_fd()" that returns
a file descriptor on "tracing_on" on the given instance opened with O_RDWR.

	fd = tracefs_trace_on_get_fd(NULL);
	tracefs_trace_on_fd(fd);
	close(fd);

Would be the same as:

	tracefs_trace_on(NULL);

-- Steve