From: "Steven Rostedt (VMware)" <rostedt@xxxxxxxxxxx>
Add a man page for the following functions:
tracefs_error_last()
tracefs_error_all()
tracefs_error_clear()
Signed-off-by: Steven Rostedt (VMware) <rostedt@xxxxxxxxxxx>
---
Documentation/libtracefs-error.txt | 132 +++++++++++++++++++++++++++++
1 file changed, 132 insertions(+)
create mode 100644 Documentation/libtracefs-error.txt
diff --git a/Documentation/libtracefs-error.txt b/Documentation/libtracefs-error.txt
new file mode 100644
index 0000000..3f6a154
--- /dev/null
+++ b/Documentation/libtracefs-error.txt
@@ -0,0 +1,132 @@
+libtracefs(3)
+=============
+
+NAME
+----
+tracefs_error_last, tracefs_error_all, tracefs_error_clear -
+functions to read and clear the tracefs error log.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <tracefs.h>*
+
+char pass:[*]*tracefs_error_last*(struct tracefs_instance pass:[*]_instance_);
+char pass:[*]*tracefs_error_last*(struct tracefs_instance pass:[*]_instance_);
+int *tracefs_error_clear*(struct tracefs_instance pass:[*]_instance_);
+--
+
+DESCRIPTION
+-----------
+The *tracefs_error_last*() returns the last error message in the tracefs
+error log. Several actions that require proper syntax written into the
+tracefs file system may produce error messages in the error log. This
+function will show the most recent error in the error log.
+
+The *tracefs_error_all*() returns all messages saved in the error log.
+Note, this may not be all messages that were ever produced, as the kernel
+only keeps a limited amount of messages, and older ones may be discarded
+by the kernel.
+
+The *tracefs_error_clear*() will clear the error log.
+
+RETURN VALUE
+------------
+Both *tracefs_error_last*() and *tracefs_error_all*() will return an allocated
+string an error exists in the log, otherwise NULL is returned. If an error
+occurs, errno will be set, otherwise if there is no error messages to display
+then errno is not touched.
+
+*tracefs_error_clear*() returns 0 on success or -1 on error.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <stdlib.h>
+#include <unistd.h>
+#include <errno.h>
+
+#include <tracefs/tracefs.h>
+
+int main (int argc, char **argv, char **env)
+{
+ char *system = NULL;
+ char *kprobe;
+ char *format;
+ char *addr;
+ int arg = 1;
+ int ret;
+
+ if (argc < 4) {
+ printf("usage: %s [system] kprobe addr fmt\n", argv[0]);
+ exit(-1);
+ }
+
+ if (argc > 5)
+ system = argv[arg++];
+
+ kprobe = argv[arg++];
+ addr = argv[arg++];
+ format = argv[arg++];
+
+ tracefs_error_clear(NULL);
+ tracefs_kprobe_clear_probe(system, kprobe, true);
+
+ ret = tracefs_kprobe_raw(system, kprobe, addr, format);
+ if (ret < 0) {
+ char *err;
+
+ perror("Failed creating kprobe");
+ errno = 0;
+ err = tracefs_error_last(NULL);
+ if (err)
+ fprintf(stderr, "%s\n", err);
+ else if (errno)
+ perror("Failed reading error log");
+ free(err);
+ }
+
+ exit(ret);
+}
+--
+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>
+*Tzvetomir Stoyanov* <tz.stoyanov@xxxxxxxxx>
+--
+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) 2020 VMware, Inc. Free use of this software is granted under
+the terms of the GNU Public License (GPL).
--
2.31.1
|