Documented APIs:
tracefs_file_exists()
tracefs_dir_exists()
tracefs_instance_get_file()
tracefs_instance_get_dir()
tracefs_instance_file_write()
tracefs_instance_file_read()
Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@xxxxxxxxx>
---
Documentation/libtracefs-instances-files.txt | 160 +++++++++++++++++++
1 file changed, 160 insertions(+)
create mode 100644 Documentation/libtracefs-instances-files.txt
diff --git a/Documentation/libtracefs-instances-files.txt b/Documentation/libtracefs-instances-files.txt
new file mode 100644
index 0000000..7f9d381
--- /dev/null
+++ b/Documentation/libtracefs-instances-files.txt
@@ -0,0 +1,160 @@
+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.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <tracefs.h>*
+
+bool *tracefs_file_exists*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_name_);
+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_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_);
+
+--
+
+DESCRIPTION
+-----------
+This set of APIs can be used to work with trace files in all trace instances.
+Each of these APIs take an _instance_ argument, that can be NULL to act
+on the top level instance. Otherwise, it acts on an instance created with
+*tracefs_insance_create*(3)
+
+The _tracefs_file_exists()_ function checks if a file with _name_ exists in _instance_.
+
+The _tracefs_dir_exists()_ function checks if a directory with _name_ exists in _instance_.
+
+The _tracefs_instance_get_file()_ function returns the full path of the file
+with given _name_ in _instance_. Note, it does not check if the file exists in
+the instance.
+
+The _tracefs_instance_get_dir()_ function returns the full path of the directory
+with given _name_ in _instance_. Note, it does not check if the directory exists
+in the instance.
+
+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 given _instance_.
+
+RETURN VALUE
+------------
+The _tracefs_file_exists()_ and _tracefs_dir_exists()_ functions return true if the
+file / directory exist in the given instance or false if it does not exist.
+
+The _tracefs_instance_get_file()_ and _tracefs_instance_get_dir()_ functions return
+a string or NULL in case of an error. The returned string must be freed with
+_tracefs_put_tracing_file()_.
+
+The _tracefs_instance_file_write()_ function returns the number of written bytes,
+or -1 in case of an error.
+
+The _tracefs_instance_file_read()_ function returns a pointer to a NULL terminated
+string, read from the file, or NULL in case of an error. The returned string must
+be freed with free().
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <tracefs.h>
+
+struct tracefs_instance *inst = tracefs_instance_create("foo");
+ if (!inst) {
+ /* Error creating a new trace instance */
+ ...
+ }
+
+ if (tracefs_file_exists(inst,"trace_clock")) {
+ /* The instance foo supports trace clock */
+ char *path, *clock;
+ int size;
+
+ path = = tracefs_instance_get_file(inst, "trace_clock")
+ if (!path) {
+ /* Error getting the path to trace_clock file in instance foo */
+ ...
+ }
+ ...
+ tracefs_put_tracing_file(path);
+
+ clock = tracefs_instance_file_read(inst, "trace_clock", &size);
+ if (!clock) {
+ /* Failed to read trace_clock file in instance foo */
+ ...
+ }
+ ...
+ free(clock);
+
+ if (tracefs_instance_file_write(inst, "trace_clock", "global") != strlen("global")) {
+ /* Failed to set gloabl trace clock in instance foo */
+ ...
+ }
+ } else {
+ /* The instance foo does not support trace clock */
+ }
+
+ if (tracefs_dir_exists(inst,"options")) {
+ /* The instance foo supports trace options */
+ char *path = tracefs_instance_get_file(inst, "options");
+ if (!path) {
+ /* Error getting the path to options directory in instance foo */
+ ...
+ }
+
+ tracefs_put_tracing_file(path);
+ } else {
+ /* The instance foo does not support trace options */
+ }
+
+ ...
+
+ if (tracefs_instance_is_new(inst))
+ tracefs_instance_destroy(inst);
+ else
+ tracefs_instance_free(inst);
+--
+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/
\ No newline at end of file
--
2.28.0
|