[PATCH 0/6] New libtracefs APIs

[PATCH 0/6] New libtracefs APIs

[Tzvetomir Stoyanov (VMware)]

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

The main motivation is to cover trace-cmd use cases of tracefs library.
These APIs are the first step in that direction.

Tzvetomir Stoyanov (VMware) (6):
  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         | 143 +++++++++++++++++++
 include/tracefs.h                            |  12 +-
 src/Makefile                                 |   1 +
 src/tracefs-instance.c                       |  59 +++++++-
 src/tracefs-tools.c                          | 123 ++++++++++++++++
 utest/tracefs-utest.c                        | 131 +++++++++++++++++
 7 files changed, 509 insertions(+), 7 deletions(-)
 create mode 100644 Documentation/libtracefs-traceon.txt
 create mode 100644 src/tracefs-tools.c

-- 
2.29.2

[PATCH 1/6] libtracefs: New APIs for opening and reading ftrace files

[Tzvetomir Stoyanov (VMware)]

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

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 include/tracefs.h      |  6 ++++-
 src/tracefs-instance.c | 59 ++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 62 insertions(+), 3 deletions(-)

diff --git a/include/tracefs.h b/include/tracefs.h
index 3d70aca..460fa4c 100644
--- a/include/tracefs.h
+++ b/include/tracefs.h
@@ -29,7 +29,11 @@ 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_instance_file_read_int(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 bf3de7c..27b9e99 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"
 
@@ -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;
@@ -301,6 +301,61 @@ char *tracefs_instance_file_read(struct tracefs_instance *instance,
 	return buf;
 }
 
+/**
+ * tracefs_instance_file_read_int - Read an 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_int(struct tracefs_instance *instance,
+				   const char *file, long long *res)
+{
+	long long ret = LLONG_MAX;
+	int size = 0;
+	char *str;
+
+	str = tracefs_instance_file_read(instance, file, &size);
+	if (size && str)
+		ret = strtoll(str, NULL, 0);
+	free(str);
+
+	if (LLONG_MIN == ret || LLONG_MAX == ret)
+		return -1;
+	*res = ret;
+	return 0;
+}
+
+/**
+ * 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

Re: [PATCH 1/6] libtracefs: New APIs for opening and reading ftrace files

[Steven Rostedt]

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

> These new APIs can be used to read integer from frtace file and to open
> ftrace file:
>   tracefs_instance_file_read_int();
>   tracefs_instance_file_open();
> 
> Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
> ---
>  include/tracefs.h      |  6 ++++-
>  src/tracefs-instance.c | 59 ++++++++++++++++++++++++++++++++++++++++--
>  2 files changed, 62 insertions(+), 3 deletions(-)
> 
> diff --git a/include/tracefs.h b/include/tracefs.h
> index 3d70aca..460fa4c 100644
> --- a/include/tracefs.h
> +++ b/include/tracefs.h
> @@ -29,7 +29,11 @@ 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_instance_file_read_int(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 bf3de7c..27b9e99 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"
>  
> @@ -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)

The above is more of a clean up and should be a separate patch.

>  {
>  	char *buf = NULL;
>  	int size = 0;
> @@ -301,6 +301,61 @@ char *tracefs_instance_file_read(struct tracefs_instance *instance,
>  	return buf;
>  }
>  
> +/**
> + * tracefs_instance_file_read_int - Read an 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_int(struct tracefs_instance *instance,
> +				   const char *file, long long *res)

Let's call this "tracefs_instance_file_number()" as "int" may be confusing
as it really returns "long long".

> +{
> +	long long ret = LLONG_MAX;
> +	int size = 0;
> +	char *str;
> +
> +	str = tracefs_instance_file_read(instance, file, &size);
> +	if (size && str)
> +		ret = strtoll(str, NULL, 0);
> +	free(str);
> +
> +	if (LLONG_MIN == ret || LLONG_MAX == ret)
> +		return -1;

As it is possible that the file could read LLONG_MIN or LLONG_MAX, we
should follow the man page and use errno to detect an error:

	if (!size || !str)
		return -1;

	errno = 0;
	ret = strtoll(str, NULL, 0);
	if (errno)
		return -1;


-- Steve

> +	*res = ret;
> +	return 0;
> +}
> +
> +/**
> + * 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)
>  {

[PATCH 2/6] 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_fd();
  tracefs_trace_off_fd();

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

diff --git a/include/tracefs.h b/include/tracefs.h
index 460fa4c..bc799c7 100644
--- a/include/tracefs.h
+++ b/include/tracefs.h
@@ -40,6 +40,12 @@ 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);
+
 /* 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..89e2d6d
--- /dev/null
+++ b/src/tracefs-tools.c
@@ -0,0 +1,123 @@
+// 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)
+{
+	int ret;
+
+	if (on)
+		ret = write(fd, "1", 1);
+	else
+		ret = write(fd, "0", 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)
+{
+	char buf[10];
+	int ret;
+	int fd;
+
+	fd = tracefs_instance_file_open(instance, TRACE_CTRL, O_RDONLY);
+	if (fd < 0)
+		return -1;
+	ret = read(fd, buf, 10);
+	if (ret > 0) {
+		buf[9] = 0;
+		ret = atoi(buf);
+	} else {
+		ret = -1;
+	}
+	close(fd);
+
+	return ret;
+}
+
+/**
+ * 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 for reading
+ *	with tracefs_instance_file_open()
+ *
+ * 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 for reading
+ *	with tracefs_instance_file_open()
+ *
+ * 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

Re: [PATCH 2/6] libtracefs: New APIs for enable / disable tracing

[Steven Rostedt]

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

> 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_fd();
>   tracefs_trace_off_fd();
> 
> Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
> ---
>  include/tracefs.h   |   6 +++
>  src/Makefile        |   1 +
>  src/tracefs-tools.c | 123 ++++++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 130 insertions(+)
>  create mode 100644 src/tracefs-tools.c
> 
> diff --git a/include/tracefs.h b/include/tracefs.h
> index 460fa4c..bc799c7 100644
> --- a/include/tracefs.h
> +++ b/include/tracefs.h
> @@ -40,6 +40,12 @@ 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);
> +
>  /* 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..89e2d6d
> --- /dev/null
> +++ b/src/tracefs-tools.c
> @@ -0,0 +1,123 @@
> +// 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)
> +{
> +	int ret;
> +
> +	if (on)
> +		ret = write(fd, "1", 1);
> +	else
> +		ret = write(fd, "0", 1);

Instead of having both blocks of the if statement call write, it would be
simpler to have:

	const char *val = on ? "1" : "0";

	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)
> +{
> +	char buf[10];
> +	int ret;
> +	int fd;
> +
> +	fd = tracefs_instance_file_open(instance, TRACE_CTRL, O_RDONLY);
> +	if (fd < 0)
> +		return -1;
> +	ret = read(fd, buf, 10);
> +	if (ret > 0) {
> +		buf[9] = 0;
> +		ret = atoi(buf);
> +	} else {
> +		ret = -1;
> +	}
> +	close(fd);

Wouldn't the above be better to use tracefs_instance_file_read_number()?


	long long val;

	ret = tracefs_instance_file_read_number(instance, TRACE_CTRL, &val);
	if (ret < 0)
		return -1;

	return !!val;

-- Steve

> +
> +	return ret;
> +}
> +
> +/**
> + * 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 for reading
> + *	with tracefs_instance_file_open()
> + *
> + * 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 for reading
> + *	with tracefs_instance_file_open()
> + *
> + * 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);
> +}

[PATCH 3/6] 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_int();

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 Documentation/libtracefs-instances-files.txt | 47 ++++++++++++++++++--
 1 file changed, 43 insertions(+), 4 deletions(-)

diff --git a/Documentation/libtracefs-instances-files.txt b/Documentation/libtracefs-instances-files.txt
index 9b18b73..d3aaef2 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_int - 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_, char pass:[*]_file_, int pass:[*]_psize_);
+char pass:[*]*tracefs_instance_file_read*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, int pass:[*]_psize_);
+int *tracefs_instance_file_read_int*(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_int()_ 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_int()_ 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_int(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
 -----
-- 
2.29.2

[PATCH 4/6] 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 | 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*.
+
+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).
-- 
2.29.2

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

[Steven Rostedt]

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

[PATCH 5/6] 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_int();

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

diff --git a/utest/tracefs-utest.c b/utest/tracefs-utest.c
index b45a3c6..a51d6fc 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, char *fname)
 #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,95 @@ 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_int(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 +704,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 6/6] 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 | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/utest/tracefs-utest.c b/utest/tracefs-utest.c
index a51d6fc..2a80cf7 100644
--- a/utest/tracefs-utest.c
+++ b/utest/tracefs-utest.c
@@ -412,6 +412,42 @@ static void test_instance_file_fd(void)
 	close(fd);
 }
 
+static void test_tracing_onoff(void)
+{
+	long long res = -1;
+	int fd;
+
+	fd = tracefs_instance_file_open(test_instance, TRACE_ON, O_WRONLY);
+	CU_TEST(fd >= 0);
+	CU_TEST(tracefs_instance_file_read_int(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;
@@ -719,4 +755,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