[PATCH v2 0/7] New libtracefs APIs

[PATCH v2 0/7] New libtracefs APIs

[Tzvetomir Stoyanov (VMware)]

Added new APIs to tracefs library and updated man pages and unit tests:
  tracefs_instance_file_read_number();
  tracefs_instance_file_open();
  tracefs_trace_is_on();
  tracefs_trace_on();
  tracefs_trace_off();
  tracefs_trace_on_get_fd()p;
  tracefs_trace_on_fd();
  tracefs_trace_off_fd();

v2 changes:
 - Renamed tracefs_instance_file_read_int() to tracefs_instance_file_read_number().
 - Added new tracefs_trace_on_get_fd() API.
 - Better error checking of tracefs_instance_file_read_number() API.
 - A few code clean-ups, suggested by Steven.

Tzvetomir Stoyanov (VMware) (7):
  libtracefs: tracefs_instance_file_read() get a const file name
  libtracefs: New APIs for opening and reading ftrace files
  libtracefs: New APIs for enable / disable tracing
  libtracefs: Documentation for the new APIs for opening and reading
    ftrace files
  libtracefs: Documentation for enable / disable tracing APIs
  libtracefs: Unit tests for the new APIs for opening and reading ftrace
    files
  libtracefs: Unit tests for enable / disable tracing APIs

 Documentation/libtracefs-instances-files.txt |  47 +++++-
 Documentation/libtracefs-traceon.txt         | 151 +++++++++++++++++++
 Documentation/libtracefs.txt                 |  10 +-
 include/tracefs.h                            |  24 ++-
 src/Makefile                                 |   1 +
 src/tracefs-instance.c                       |  62 +++++++-
 src/tracefs-tools.c                          | 109 +++++++++++++
 utest/tracefs-utest.c                        | 137 ++++++++++++++++-
 8 files changed, 532 insertions(+), 9 deletions(-)
 create mode 100644 Documentation/libtracefs-traceon.txt
 create mode 100644 src/tracefs-tools.c

-- 
2.29.2

[PATCH v2 1/7] libtracefs: tracefs_instance_file_read() get a const file name

[Tzvetomir Stoyanov (VMware)]

The file name input parameter of tracefs_instance_file_read() API should
be a pointer to a constat string, as this file name must not be changed
by the API.

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 Documentation/libtracefs-instances-files.txt | 2 +-
 Documentation/libtracefs.txt                 | 2 +-
 include/tracefs.h                            | 2 +-
 src/tracefs-instance.c                       | 2 +-
 utest/tracefs-utest.c                        | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/libtracefs-instances-files.txt b/Documentation/libtracefs-instances-files.txt
index 9b18b73..a9af1f7 100644
--- a/Documentation/libtracefs-instances-files.txt
+++ b/Documentation/libtracefs-instances-files.txt
@@ -18,7 +18,7 @@ bool *tracefs_dir_exists*(struct tracefs_instance pass:[*]_instance_, char pass:
 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_);
+char pass:[*]*tracefs_instance_file_read*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, int pass:[*]_psize_);
 
 --
 
diff --git a/Documentation/libtracefs.txt b/Documentation/libtracefs.txt
index ddbf783..bf3882f 100644
--- a/Documentation/libtracefs.txt
+++ b/Documentation/libtracefs.txt
@@ -26,7 +26,7 @@ Trace instances:
 	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_);
+	char pass:[*]*tracefs_instance_file_read*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, int pass:[*]_psize_);
 	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_);
diff --git a/include/tracefs.h b/include/tracefs.h
index 3d70aca..06e2130 100644
--- a/include/tracefs.h
+++ b/include/tracefs.h
@@ -29,7 +29,7 @@ char *tracefs_instance_get_dir(struct tracefs_instance *instance);
 int tracefs_instance_file_write(struct tracefs_instance *instance,
 				const char *file, const char *str);
 char *tracefs_instance_file_read(struct tracefs_instance *instance,
-				 char *file, int *psize);
+				 const char *file, int *psize);
 int tracefs_instances_walk(int (*callback)(const char *, void *), void *context);
 
 bool tracefs_instance_exists(const char *name);
diff --git a/src/tracefs-instance.c b/src/tracefs-instance.c
index bf3de7c..6dc85ee 100644
--- a/src/tracefs-instance.c
+++ b/src/tracefs-instance.c
@@ -282,7 +282,7 @@ int tracefs_instance_file_write(struct tracefs_instance *instance,
  * The return string must be freed by free()
  */
 char *tracefs_instance_file_read(struct tracefs_instance *instance,
-				  char *file, int *psize)
+				 const char *file, int *psize)
 {
 	char *buf = NULL;
 	int size = 0;
diff --git a/utest/tracefs-utest.c b/utest/tracefs-utest.c
index b45a3c6..a8e8f67 100644
--- a/utest/tracefs-utest.c
+++ b/utest/tracefs-utest.c
@@ -181,7 +181,7 @@ static void test_trace_file(void)
 	tracefs_put_tracing_file(file);
 }
 
-static void test_instance_file_read(struct tracefs_instance *inst, char *fname)
+static void test_instance_file_read(struct tracefs_instance *inst, const char *fname)
 {
 	const char *tdir  = tracefs_tracing_dir();
 	char buf[BUFSIZ];
-- 
2.29.2

[PATCH v2 2/7] libtracefs: New APIs for opening and reading ftrace files

[Tzvetomir Stoyanov (VMware)]

These new APIs can be used to read long long integer from frtace file
and to open ftrace file:
  tracefs_instance_file_read_number();
  tracefs_instance_file_open();

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 include/tracefs.h      |  4 +++
 src/tracefs-instance.c | 60 +++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 63 insertions(+), 1 deletion(-)

diff --git a/include/tracefs.h b/include/tracefs.h
index 06e2130..bec8369 100644
--- a/include/tracefs.h
+++ b/include/tracefs.h
@@ -30,6 +30,10 @@ int tracefs_instance_file_write(struct tracefs_instance *instance,
 				const char *file, const char *str);
 char *tracefs_instance_file_read(struct tracefs_instance *instance,
 				 const char *file, int *psize);
+int tracefs_instance_file_read_number(struct tracefs_instance *instance,
+				      const char *file, long long *res);
+int tracefs_instance_file_open(struct tracefs_instance *instance,
+			       const char *file, int mode);
 int tracefs_instances_walk(int (*callback)(const char *, void *), void *context);
 
 bool tracefs_instance_exists(const char *name);
diff --git a/src/tracefs-instance.c b/src/tracefs-instance.c
index 6dc85ee..97bbb00 100644
--- a/src/tracefs-instance.c
+++ b/src/tracefs-instance.c
@@ -14,7 +14,7 @@
 #include <sys/stat.h>
 #include <fcntl.h>
 #include <dirent.h>
-#include <linux/limits.h>
+#include <limits.h>
 #include "tracefs.h"
 #include "tracefs-local.h"
 
@@ -301,6 +301,64 @@ char *tracefs_instance_file_read(struct tracefs_instance *instance,
 	return buf;
 }
 
+/**
+ * tracefs_instance_file_read_number - Read long long integer from a trace file.
+ * @instance: ftrace instance, can be NULL for the top instance
+ * @file: name of the file
+ * @res: The integer from the file.
+ *
+ * Returns 0 if the reading is successful and the result is stored in res, -1
+ * in case of an error.
+ */
+int tracefs_instance_file_read_number(struct tracefs_instance *instance,
+				      const char *file, long long *res)
+{
+	long long num;
+	int ret = -1;
+	int size = 0;
+	char *str;
+
+	str = tracefs_instance_file_read(instance, file, &size);
+	if (size && str) {
+		errno = 0;
+		num = strtoll(str, NULL, 0);
+		if (errno == 0) {
+			*res = num;
+			ret = 0;
+		}
+	}
+	free(str);
+	return ret;
+}
+
+/**
+ * tracefs_instance_file_open - Open a trace file for reading and writing
+ * @instance: ftrace instance, can be NULL for the top instance
+ * @file: name of the file
+ * @mode: file open flags, -1 for default O_RDWR
+ *
+ * Returns -1 in case of an error, or a valid file descriptor otherwise.
+ * The returned FD must be closed with close()
+ */
+int tracefs_instance_file_open(struct tracefs_instance *instance,
+			       const char *file, int mode)
+{
+	int flags = O_RDWR;
+	int fd = -1;
+	char *path;
+
+	path = tracefs_instance_get_file(instance, file);
+	if (!path)
+		return -1;
+
+	if (mode >= 0)
+		flags = mode;
+	fd = open(path, flags);
+	tracefs_put_tracing_file(path);
+
+	return fd;
+}
+
 static bool check_file_exists(struct tracefs_instance *instance,
 			     char *name, bool dir)
 {
-- 
2.29.2

[PATCH v2 3/7] libtracefs: New APIs for enable / disable tracing

[Tzvetomir Stoyanov (VMware)]

These new APIs can be used to enable / disable tracing in given ftrace
instance:
  tracefs_trace_is_on();
  tracefs_trace_on();
  tracefs_trace_off();
  tracefs_trace_on_get_fd();
  tracefs_trace_on_fd();
  tracefs_trace_off_fd();

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 include/tracefs.h   |  18 ++++++++
 src/Makefile        |   1 +
 src/tracefs-tools.c | 109 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 128 insertions(+)
 create mode 100644 src/tracefs-tools.c

diff --git a/include/tracefs.h b/include/tracefs.h
index bec8369..85a776e 100644
--- a/include/tracefs.h
+++ b/include/tracefs.h
@@ -40,6 +40,24 @@ bool tracefs_instance_exists(const char *name);
 bool tracefs_file_exists(struct tracefs_instance *instance, char *name);
 bool tracefs_dir_exists(struct tracefs_instance *instance, char *name);
 
+int tracefs_trace_is_on(struct tracefs_instance *instance);
+int tracefs_trace_on(struct tracefs_instance *instance);
+int tracefs_trace_off(struct tracefs_instance *instance);
+int tracefs_trace_on_fd(int fd);
+int tracefs_trace_off_fd(int fd);
+
+/**
+ * tracefs_trace_on_get_fd - Get a file descriptor of "tracing_on" in given instance
+ * @instance: ftrace instance, can be NULL for the top instance
+ *
+ * Returns -1 in case of an error, or a valid file descriptor to "tracing_on"
+ * file for reading and writing.The returned FD must be closed with close().
+ */
+static inline int tracefs_trace_on_get_fd(struct tracefs_instance *instance)
+{
+	return tracefs_instance_file_open(instance, "tracing_on", O_RDWR);
+}
+
 /* events */
 void tracefs_list_free(char **list);
 char **tracefs_event_systems(const char *tracing_dir);
diff --git a/src/Makefile b/src/Makefile
index 3f64905..dabdbb4 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -6,6 +6,7 @@ OBJS =
 OBJS += tracefs-utils.o
 OBJS += tracefs-instance.o
 OBJS += tracefs-events.o
+OBJS += tracefs-tools.o
 
 OBJS := $(OBJS:%.o=$(bdir)/%.o)
 DEPS := $(OBJS:$(bdir)/%.o=$(bdir)/.%.d)
diff --git a/src/tracefs-tools.c b/src/tracefs-tools.c
new file mode 100644
index 0000000..101f389
--- /dev/null
+++ b/src/tracefs-tools.c
@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: LGPL-2.1
+/*
+ * Copyright (C) 2008, 2009, 2010 Red Hat Inc, Steven Rostedt <srostedt@redhat.com>
+ *
+ * Updates:
+ * Copyright (C) 2021, VMware, Tzvetomir Stoyanov <tz.stoyanov@gmail.com>
+ *
+ */
+#include <stdlib.h>
+#include <unistd.h>
+#include <fcntl.h>
+
+#include "tracefs.h"
+#include "tracefs-local.h"
+
+#define TRACE_CTRL	"tracing_on"
+
+static int trace_on_off(int fd, bool on)
+{
+	const char *val = on ? "1" : "0";
+	int ret;
+
+	ret = write(fd, val, 1);
+	if (ret == 1)
+		return 0;
+
+	return -1;
+}
+
+static int trace_on_off_file(struct tracefs_instance *instance, bool on)
+{
+	int ret;
+	int fd;
+
+	fd = tracefs_instance_file_open(instance, TRACE_CTRL, O_WRONLY);
+	if (fd < 0)
+		return -1;
+	ret = trace_on_off(fd, on);
+	close(fd);
+
+	return ret;
+}
+
+/**
+ * tracefs_trace_is_on - Check if writing traces to the ring buffer is enabled
+ * @instance: ftrace instance, can be NULL for the top instance
+ *
+ * Returns -1 in case of an error, 0 if tracing is disable or 1 if tracing
+ * is enabled.
+ */
+int tracefs_trace_is_on(struct tracefs_instance *instance)
+{
+	long long res;
+
+	if (tracefs_instance_file_read_number(instance, TRACE_CTRL, &res) == 0)
+		return (int)res;
+
+	return -1;
+}
+
+/**
+ * tracefs_trace_on - Enable writing traces to the ring buffer of the given instance
+ * @instance: ftrace instance, can be NULL for the top instance
+ *
+ * Returns -1 in case of an error or 0 otherwise
+ */
+int tracefs_trace_on(struct tracefs_instance *instance)
+{
+	return trace_on_off_file(instance, true);
+}
+
+/**
+ * tracefs_trace_off - Disable writing traces to the ring buffer of the given instance
+ * @instance: ftrace instance, can be NULL for the top instance
+ *
+ * Returns -1 in case of an error or 0 otherwise
+ */
+int tracefs_trace_off(struct tracefs_instance *instance)
+{
+	return trace_on_off_file(instance, false);
+}
+
+/**
+ * tracefs_trace_on_fd - Enable writing traces to the ring buffer
+ * @fd: File descriptor to ftrace tracing_on file, previously opened
+ *	with tracefs_trace_on_get_fd()
+ *
+ * Returns -1 in case of an error or 0 otherwise
+ */
+int tracefs_trace_on_fd(int fd)
+{
+	if (fd < 0)
+		return -1;
+	return trace_on_off(fd, true);
+}
+
+/**
+ * tracefs_trace_off_fd - Disable writing traces to the ring buffer
+ * @fd: File descriptor to ftrace tracing_on file, previously opened
+ *	with tracefs_trace_on_get_fd()
+ *
+ * Returns -1 in case of an error or 0 otherwise
+ */
+int tracefs_trace_off_fd(int fd)
+{
+	if (fd < 0)
+		return -1;
+	return trace_on_off(fd, false);
+}
-- 
2.29.2

[PATCH v2 4/7] libtracefs: Documentation for the new APIs for opening and reading ftrace files

[Tzvetomir Stoyanov (VMware)]

Man pages updated with documentation about:
  tracefs_instance_file_open();
  tracefs_instance_file_read_number();

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 Documentation/libtracefs-instances-files.txt | 45 ++++++++++++++++++--
 Documentation/libtracefs.txt                 |  2 +
 2 files changed, 44 insertions(+), 3 deletions(-)

diff --git a/Documentation/libtracefs-instances-files.txt b/Documentation/libtracefs-instances-files.txt
index a9af1f7..124ef52 100644
--- a/Documentation/libtracefs-instances-files.txt
+++ b/Documentation/libtracefs-instances-files.txt
@@ -4,8 +4,8 @@ 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.
+tracefs_instance_get_dir, tracefs_instance_file_open, tracefs_instance_file_write,
+tracefs_instance_file_read, tracefs_instance_file_read_number - Work with files in tracing instances.
 
 SYNOPSIS
 --------
@@ -17,8 +17,10 @@ bool *tracefs_file_exists*(struct tracefs_instance pass:[*]_instance_, char pass
 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_open*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, int _mode_);
 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_, const char pass:[*]_file_, int pass:[*]_psize_);
+int *tracefs_instance_file_read_number*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, long long int pass:[*]_res_);
 
 --
 
@@ -41,12 +43,19 @@ The _tracefs_instance_get_dir()_ function  returns the full path of the director
 with given _name_ in _instance_. Note, it does not check if the directory exists
 in the instance.
 
+The _tracefs_instance_file_open()_ function opens trace _file_ from given _instance_ and returns
+a file descriptor to it. The file access _mode_ can be specified, see *open*(3) for more details.
+If -1 is passed as _mode_, default O_RDWR is used.
+
 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 _tracefs_instance_file_read()_ function reads the content of a _file_ from
 the given _instance_.
 
+The _tracefs_instance_file_read_number()_ function reads the content of a _file_ from
+the given _instance_ and converts it to a long long integer, which is stored in _res_.
+
 RETURN VALUE
 ------------
 The _tracefs_file_exists()_ and  _tracefs_dir_exists()_ functions return true if the
@@ -56,6 +65,9 @@ The _tracefs_instance_get_file()_ and _tracefs_instance_get_dir()_ functions ret
 a string or NULL in case of an error. The returned string must be freed with
 _tracefs_put_tracing_file()_.
 
+The _tracefs_instance_file_open()_ function returns a file descriptor to the opened file. It must be
+closed with *close*(3). In case of an error, -1 is returned.
+
 The _tracefs_instance_file_write()_ function returns the number of written bytes,
 or -1 in case of an error.
 
@@ -63,6 +75,9 @@ The _tracefs_instance_file_read()_ function returns a pointer to a NULL terminat
 string, read from the file, or NULL in case of an error. The returned string must
 be freed with free().
 
+The _tracefs_instance_file_read_number()_ function returns 0 if a valid integer is read from
+the file and stored in _res_ or -1 in case of an error.
+
 EXAMPLE
 -------
 [source,c]
@@ -123,6 +138,30 @@ struct tracefs_instance *inst = tracefs_instance_create("foo");
 		tracefs_instance_destroy(inst);
 	else
 		tracefs_instance_free(inst);
+	...
+
+	long long int res;
+	if (tracefs_instance_file_read_number(NULL, "tracing_on", &res) == 0) {
+		if (res == 0) {
+			/* tracing is disabled in the top instance */
+		} else if (res == 1) {
+			/* tracing is enabled in the top instance */
+		} else {
+			/* Unknown tracing state of the top instance */
+		}
+	} else {
+		/* Failed to read integer from tracing_on file */
+	}
+
+	...
+
+	int fd;
+	fd = tracefs_instance_file_open(NULL, "tracing_on", O_WRONLY);
+	if (fd >= 0) {
+		/* Got file descriptor to the tracing_on file from the top instance for writing */
+		...
+		close(fd);
+	}
 --
 FILES
 -----
diff --git a/Documentation/libtracefs.txt b/Documentation/libtracefs.txt
index bf3882f..0350416 100644
--- a/Documentation/libtracefs.txt
+++ b/Documentation/libtracefs.txt
@@ -25,8 +25,10 @@ Trace instances:
 	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_open*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, int _mode_);
 	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_, const char pass:[*]_file_, int pass:[*]_psize_);
+	int *tracefs_instance_file_read_number*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, long long int pass:[*]_res_);
 	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_);
-- 
2.29.2

[PATCH v2 5/7] libtracefs: Documentation for enable / disable tracing APIs

[Tzvetomir Stoyanov (VMware)]

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 | 151 +++++++++++++++++++++++++++
 Documentation/libtracefs.txt         |   6 ++
 2 files changed, 157 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..d7fc239
--- /dev/null
+++ b/Documentation/libtracefs-traceon.txt
@@ -0,0 +1,151 @@
+libtracefs(3)
+=============
+
+NAME
+----
+tracefs_trace_is_on, tracefs_trace_on, tracefs_trace_off, tracefs_trace_on_get_fd,
+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_get_fd_(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_get_fd()_ function returns a file deascriptor to the "tracing_on" file from
+the given _instance_. If _instance_ is NULL, the top trace instance is used. The returned descriptor
+can be used for fast enabling or disabling the tracing of the instance.
+
+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_trace_on_get_fd*(3) of the 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_get_fd()_ function returns a file descriptor to "tracing_on"
+file for reading and writing, which must be closed wuth close(). In case of an error -1 is returned.
+
+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_trace_on_get_fd(NULL);
+
+	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).
diff --git a/Documentation/libtracefs.txt b/Documentation/libtracefs.txt
index 0350416..cea21fe 100644
--- a/Documentation/libtracefs.txt
+++ b/Documentation/libtracefs.txt
@@ -45,6 +45,12 @@ Trace helper functions:
 	void *tracefs_list_free*(char pass:[*]pass:[*]_list_);
 	char pass:[*]pass:[*]*tracefs_tracers*(const char pass:[*]_tracing_dir_);
 	char pass:[*]*tracefs_get_clock*(struct tracefs_instance pass:[*]_instance_);
+	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_get_fd_(struct tracefs_instance pass:[*]_instance_);
+	int *tracefs_trace_on_fd*(int _fd_);
+	int *tracefs_trace_off_fd*(int _fd_);
 --
 
 DESCRIPTION
-- 
2.29.2

[PATCH v2 6/7] libtracefs: Unit tests for the new APIs for opening and reading ftrace files

[Tzvetomir Stoyanov (VMware)]

Added unit tests for:
  tracefs_instance_file_open();
  tracefs_instance_file_read_number();

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 utest/tracefs-utest.c | 94 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)

diff --git a/utest/tracefs-utest.c b/utest/tracefs-utest.c
index a8e8f67..bbe653c 100644
--- a/utest/tracefs-utest.c
+++ b/utest/tracefs-utest.c
@@ -218,6 +218,7 @@ static void test_instance_file_read(struct tracefs_instance *inst, const char *f
 #define ALL_TRACERS	"available_tracers"
 #define CUR_TRACER	"current_tracer"
 #define PER_CPU		"per_cpu"
+#define TRACE_ON	"tracing_on"
 static void test_instance_file(void)
 {
 	struct tracefs_instance *instance = NULL;
@@ -322,6 +323,97 @@ static void test_instance_file(void)
 	free(inst_dir);
 }
 
+static bool check_fd_name(int fd, char *name)
+{
+	char link[PATH_MAX + 1];
+	char path[PATH_MAX + 1];
+	struct stat st;
+	char *file;
+	int ret;
+
+	snprintf(link, PATH_MAX, "/proc/self/fd/%d", fd);
+	ret = lstat(link, &st);
+	CU_TEST(ret == 0);
+	if (ret < 0)
+		return false;
+	CU_TEST(S_ISLNK(st.st_mode));
+	if (!S_ISLNK(st.st_mode))
+		return false;
+	ret = readlink(link, path, PATH_MAX);
+	CU_TEST(ret > 0);
+	if (ret > PATH_MAX || ret < 0)
+		return false;
+	path[ret] = 0;
+	file = basename(path);
+	CU_TEST(file != NULL);
+	if (!file)
+		return false;
+	ret = strcmp(file, name);
+	CU_TEST(ret == 0);
+	if (ret)
+		return false;
+	return true;
+}
+
+#define FLAGS_STR	"flags:"
+static bool check_fd_mode(int fd, int mode)
+{
+	char path[PATH_MAX + 1];
+	long fmode = -1;
+	char *line = NULL;
+	struct stat st;
+	size_t len = 0;
+	ssize_t size;
+	FILE *file;
+	int ret;
+
+	snprintf(path, PATH_MAX, "/proc/self/fdinfo/%d", fd);
+	ret = stat(path, &st);
+	CU_TEST(ret == 0);
+	if (ret < 0)
+		return false;
+	file = fopen(path, "r");
+	if (!file)
+		return false;
+	while ((size = getline(&line, &len, file)) > 0) {
+		if (strncmp(line, FLAGS_STR, strlen(FLAGS_STR)))
+			continue;
+		fmode = strtol(line + strlen(FLAGS_STR), NULL, 8);
+		break;
+	}
+	free(line);
+	fclose(file);
+	if (fmode < 0 ||
+	    (O_ACCMODE & fmode) != (O_ACCMODE & mode))
+		return false;
+	return true;
+}
+
+static void test_instance_file_fd(void)
+{
+	const char *name = get_rand_str();
+	long long res = -1;
+	char rd[2];
+	int fd;
+
+	fd = tracefs_instance_file_open(test_instance, name, -1);
+	CU_TEST(fd == -1);
+	fd = tracefs_instance_file_open(test_instance, TRACE_ON, O_RDONLY);
+	CU_TEST(fd >= 0);
+	CU_TEST(check_fd_name(fd, TRACE_ON));
+	CU_TEST(check_fd_mode(fd, O_RDONLY));
+
+	CU_TEST(tracefs_instance_file_read_number(test_instance, "available_tracer", &res) != 0);
+	CU_TEST(tracefs_instance_file_read_number(test_instance, name, &res) != 0);
+	CU_TEST(tracefs_instance_file_read_number(test_instance, TRACE_ON, &res) == 0);
+	CU_TEST((res == 0 || res == 1));
+	CU_TEST(read(fd, &rd, 1) == 1);
+	rd[1] = 0;
+	CU_TEST(res == atoi(rd));
+
+	close(fd);
+}
+
 static void exclude_string(char **strings, char *name)
 {
 	int i;
@@ -614,6 +706,8 @@ void test_tracefs_lib(void)
 	CU_add_test(suite, "tracing file / directory APIs",
 		    test_trace_file);
 	CU_add_test(suite, "instance file / directory APIs",
+		    test_instance_file_fd);
+	CU_add_test(suite, "instance file descriptor",
 		    test_instance_file);
 	CU_add_test(suite, "systems and events APIs",
 		    test_system_event);
-- 
2.29.2

[PATCH v2 7/7] libtracefs: Unit tests for enable / disable tracing APIs

[Tzvetomir Stoyanov (VMware)]

New unit tests for these APIs:
 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>
---
 utest/tracefs-utest.c | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/utest/tracefs-utest.c b/utest/tracefs-utest.c
index bbe653c..0520f49 100644
--- a/utest/tracefs-utest.c
+++ b/utest/tracefs-utest.c
@@ -414,6 +414,44 @@ static void test_instance_file_fd(void)
 	close(fd);
 }
 
+static void test_tracing_onoff(void)
+{
+	long long res = -1;
+	int fd;
+
+	fd = tracefs_trace_on_get_fd(test_instance);
+	CU_TEST(fd >= 0);
+	CU_TEST(check_fd_name(fd, TRACE_ON));
+	CU_TEST(check_fd_mode(fd, O_RDWR));
+	CU_TEST(tracefs_instance_file_read_number(test_instance, TRACE_ON, &res) == 0);
+	if (res == 1) {
+		CU_TEST(tracefs_trace_is_on(test_instance) == 1);
+		CU_TEST(tracefs_trace_off(test_instance) == 0);
+		CU_TEST(tracefs_trace_is_on(test_instance) == 0);
+		CU_TEST(tracefs_trace_on(test_instance) == 0);
+		CU_TEST(tracefs_trace_is_on(test_instance) == 1);
+
+		CU_TEST(tracefs_trace_off_fd(fd) == 0);
+		CU_TEST(tracefs_trace_is_on(test_instance) == 0);
+		CU_TEST(tracefs_trace_on_fd(fd) == 0);
+		CU_TEST(tracefs_trace_is_on(test_instance) == 1);
+	} else {
+		CU_TEST(tracefs_trace_is_on(test_instance) == 0);
+		CU_TEST(tracefs_trace_on(test_instance) == 0);
+		CU_TEST(tracefs_trace_is_on(test_instance) == 1);
+		CU_TEST(tracefs_trace_off(test_instance) == 0);
+		CU_TEST(tracefs_trace_is_on(test_instance) == 0);
+
+		CU_TEST(tracefs_trace_on_fd(fd) == 0);
+		CU_TEST(tracefs_trace_is_on(test_instance) == 1);
+		CU_TEST(tracefs_trace_off_fd(fd) == 0);
+		CU_TEST(tracefs_trace_is_on(test_instance) == 0);
+	}
+
+	if (fd >= 0)
+		close(fd);
+}
+
 static void exclude_string(char **strings, char *name)
 {
 	int i;
@@ -721,4 +759,7 @@ void test_tracefs_lib(void)
 		    test_instances_walk);
 	CU_add_test(suite, "tracefs_get_clock API",
 		    test_get_clock);
+	CU_add_test(suite, "tracing on / off",
+		    test_tracing_onoff);
+
 }
-- 
2.29.2