[PATCH 09/11] libtracefs: Add man pages for tracefs_event_file_*() functions

[Steven Rostedt <rostedt@goodmis.org>]

From: "Steven Rostedt (Google)" <rostedt@goodmis.org>

Add the following functions to the man pages:
   tracefs_event_get_file()
   tracefs_event_file_read()
   tracefs_event_file_write()
   tracefs_event_file_append()
   tracefs_event_file_clear()
   tracefs_event_file_exists()

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 Documentation/libtracefs-events-file.txt | 217 +++++++++++++++++++++++
 Documentation/libtracefs.txt             |  11 ++
 2 files changed, 228 insertions(+)
 create mode 100644 Documentation/libtracefs-events-file.txt

diff --git a/Documentation/libtracefs-events-file.txt b/Documentation/libtracefs-events-file.txt
new file mode 100644
index 000000000000..5102cc5e6859
--- /dev/null
+++ b/Documentation/libtracefs-events-file.txt
@@ -0,0 +1,217 @@
+libtracefs(3)
+=============
+
+NAME
+----
+tracefs_event_get_file, tracefs_event_file_read, tracefs_event_file_write, tracefs_event_file_append,
+tracefs_event_file_clear, tracefs_event_file_exists - Work with trace event files.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <tracefs.h>*
+
+char pass:[*]*tracefs_event_get_file*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			     const char pass:[*]_file_);
+char pass:[*]*tracefs_event_file_read*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			      const char pass:[*]_file_, int pass:[*]_psize_);
+int *tracefs_event_file_write*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			     const char pass:[*]_file_, const char pass:[*]_str_);
+int *tracefs_event_file_append*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			      const char pass:[*]_file_, const char pass:[*]_str_);
+int *tracefs_event_file_clear*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			     const char pass:[*]_file_);
+bool *tracefs_event_file_exists*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			       const char pass:[*]_file_)
+
+--
+
+DESCRIPTION
+-----------
+These are functions for accessing tracefs event specific files.
+These functions act similar to the tracefs instance file functions
+but are easier to get to if the system and events are known before hand.
+
+The *tracefs_event_get_file()* returns the full path of the _file_ for
+the given _system_ and _event_ that is within the given _instance_.
+If _instance_ is NULL, then the file for the _event_ for the top level
+instance is returned. Note, there is no check to see if the file actually
+exists or even if the system and event exist. It only creates the path
+name for such an event if it did exist. This acts similar to the
+*tracefs_instance_get_file*(3), but is to be used to get to event files
+if the _system_ and _event_ are already known.
+
+The *tracefs_event_file_read()* reads the content for the _event_ _file_
+for the given _instance_ or the top level instance if _instance_ is
+NULL. The content of the file is returned and _psize_ is set to the amount
+of data that was read. The returned content must be freed with *free*(3).
+This acts similar to the *tracefs_instance_file_read*(3), but is
+to be used to read the event file if the _system_ and _event_ are already
+known.
+
+The *tracefs_event_file_write()* writes _str_ to the _event_ _file_.
+It will truncate anything that is already in that file. 
+This acts similar to the *tracefs_instance_file_write*(3), but is
+to be used to read the event file if the _system_ and _event_ are already
+known.
+
+The *tracefs_event_file_append()* appends _str_ to the _event_ _file_.
+It will not clear out the file as it writes _sting_.
+This acts similar to the *tracefs_instance_file_append*(3), but is
+to be used to read the event file if the _system_ and _event_ are already
+known.
+
+The *tracefs_event_file_clear()* clears the content of the _event_ _file_.
+This acts similar to the *tracefs_instance_file_clear*(3), but is
+to be used to read the event file if the _system_ and _event_ are already
+known.
+
+The *tracefs_event_file_exists()* returns true if the _event_ _file_
+exists, and false otherwise. This acts similar to the *tracefs_instance_file_exists*(3),
+but is to be used to read the event file if the _system_ and _event_ are already
+known.
+
+RETURN VALUE
+------------
+*tracefs_event_get_file()* returns the path of the given _system_/_event_ _file_ on
+success and NULL on error. The return value must be freed with *tracefs_put_tracing_file*(3).
+
+*tracefs_event_file_read()* reads the content of the _system_/_event_ _file_ or
+NULL on error. The return pointer must be freed with *free*(3).
+
+*tracefs_event_file_write()* and *tracefs_event_file_append()* returns the number of
+bytes written to the _system_/_event_ _file_ or negative on error.
+
+*tracefs_event_file_clear()* returns zero on success and -1 on error.
+
+*tracefs_event_file_exists()* returns true if the _system_/_event_ _file_ exists for
+the given _instance_ (or top level if _instance_ is NULL) or false otherwise.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <tracefs.h>
+
+int main(int argc, char **argv)
+{
+	char *system;
+	char *event;
+	char *file;
+	char *cmd = NULL;
+	char *buf;
+	char *str;
+	char ch = 'r';
+	int size;
+
+	if (argc < 4) {
+		printf("usage: %s sytem event file [(-a|-w) write | -c]\n"
+		       "   reads the system/event file or writes if [write is supplied]\n",
+		       argv[0]);
+		exit(0);
+	}
+
+	system = argv[1];
+	event = argv[2];
+	file = argv[3];
+	if (argc > 4)
+		cmd = argv[4];
+
+	if (!tracefs_event_file_exists(NULL, system, event, file)) {
+		fprintf(stderr, "File %s/%s/%s does not exist\n",
+				system, event, file);
+		exit(-1);
+	}
+
+	if (cmd) {
+		if (cmd[0] != '-')
+			ch = cmd[0];
+		else
+			ch = cmd[1];
+		if (!ch)
+			ch = 'c';
+	}
+
+	switch (ch) {
+	case 'r':
+		buf = tracefs_event_file_read(NULL, system, event, file, &size);
+		if (buf)
+			printf("%s", buf);
+		else
+			fprintf(stderr, "Failed to read %s/%s/%s\n",
+				system, event, file);
+		free(buf);
+		break;
+	case 'w':
+	case 'a':
+		if (argc < 6) {
+			fprintf(stderr, "%s command requires something to write\n",
+				ch == 'w' ? "write" : "append");
+			exit(-1);
+		}
+		if (ch == 'w')
+			size = tracefs_event_file_write(NULL, system, event, file, argv[5]);
+		else
+			size = tracefs_event_file_append(NULL, system, event, file, argv[5]);
+		if (size < 0) {
+			fprintf(stderr, "Failed to write '%s' to %s/%s/%s\n",
+					argv[5], system, event, file);
+			exit(-1);
+		}
+		break;
+	case 'c':
+		if (tracefs_event_file_clear(NULL, system, event, file) < 0) {
+			fprintf(stderr, "Failed to clear %s/%s/%s\n",
+				system, event, file);
+			exit(-1);
+		}
+		break;
+	default:
+		fprintf(stderr, "Unknown command '%c'\n", ch);
+		exit(-1);
+	}
+	exit(0);
+}
+--
+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>
+--
+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) 2022 Google, 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 44629e32d202..82cb5744b7b9 100644
--- a/Documentation/libtracefs.txt
+++ b/Documentation/libtracefs.txt
@@ -57,6 +57,17 @@ Trace events:
 	struct tep_handle pass:[*]*tracefs_local_events_system*(const char pass:[*]_tracing_dir_, const char pass:[*] const pass:[*]_sys_names_);
 	int *tracefs_fill_local_events*(const char pass:[*]_tracing_dir_, struct tep_handle pass:[*]_tep_, int pass:[*]_parsing_failures_);
 	int *tracefs_load_cmdlines*(const char pass:[*]_tracing_dir_, struct tep_handle pass:[*]_tep_);
+	char pass:[*]*tracefs_event_get_file*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			     const char pass:[*]_file_);
+	char pass:[*]*tracefs_event_file_read*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			      const char pass:[*]_file_, int pass:[*]_psize_);
+	int *tracefs_event_file_write*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			     const char pass:[*]_file_, const char pass:[*]_str_);
+	int *tracefs_event_file_append*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			      const char pass:[*]_file_, const char pass:[*]_str_);
+	int *tracefs_event_file_clear*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
+			     const char pass:[*]_file_);
+	bool *tracefs_event_file_exists*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_,
 
 Event filters:
 	int *tracefs_filter_string_append*(struct tep_event pass:[*]_event_, char pass:[**]_filter_,
-- 
2.34.1