diff mbox series

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

Message ID 20210107083250.16295-5-tz.stoyanov@gmail.com (mailing list archive)
State Superseded
Headers show
Series New libtracefs APIs | expand

Commit Message

Tzvetomir Stoyanov (VMware) Jan. 7, 2021, 8:32 a.m. UTC 
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

Comments

Steven Rostedt Jan. 7, 2021, 4:37 p.m. UTC | #1 
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
diff mbox series

Patch

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*.
+
+RETURN VALUE
+------------
+The _tracefs_trace_is_on()_ function returns 0 if tracing is disable, 1 if it is enabled or
+-1 in case of an error.
+
+The _tracefs_trace_on()_, _tracefs_trace_off()_, _tracefs_trace_on_fd()_ and
+_tracefs_trace_off_fd()_ functions return -1 in case of an error or 0 otherwise.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <tracefs.h>
+
+	int ret;
+
+	ret = tracefs_trace_is_on(NULL);
+	if (ret == 0) {
+		/* Tracing is disabled in the top instance */
+	} else if (ret == 1) {"
+		/* Tracing is enabled in the top instance */
+	} else {
+		/* Error getting tracing state of the top instance */
+	}
+
+	...
+
+	if (!tracefs_trace_on(NULL)) {
+	    /* Enabled tracing in the top instance */
+
+	    ...
+
+	    if (!tracefs_trace_off(NULL)) {
+	    	/* Disabled tracing in the top instance */
+	    } else {
+	    	/* Error disabling tracing in the top instance */
+	    }
+	} else {
+		/* Error enabling tracing in the top instance */
+	}
+
+	...
+
+	int fd = tracefs_instance_file_open(NULL, "tracing_on", O_WRONLY);
+
+	if (fd < 0) {
+		/* Error opening tracing_on file */
+	}
+	...
+	if (!tracefs_trace_on_fd(fd)) {
+	    /* Enabled tracing in the top instance */
+
+	    ...
+
+	    if (!tracefs_trace_off_fd(fd)) {
+	    	/* Disabled tracing in the top instance */
+	    } else {
+	    	/* Error disabling tracing in the top instance */
+	    }
+	} else {
+		/* Error enabling tracing in the top instance */
+	}
+
+	...
+
+	close(fd);
+--
+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/
+
+COPYING
+-------
+Copyright \(C) 2021 VMware, Inc. Free use of this software is granted under
+the terms of the GNU Public License (GPL).