From: "Steven Rostedt (Google)" <rostedt@xxxxxxxxxxx>
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@xxxxxxxxxxx>
---
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@xxxxxxxxxxx>
+--
+REPORTING BUGS
+--------------
+Report bugs to <linux-trace-devel@xxxxxxxxxxxxxxx>
+
+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
|