From: "Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com>
To: rostedt@goodmis.org
Cc: linux-trace-devel@vger.kernel.org
Subject: [PATCH v2 6/8] libtracefs man pages: helper APIs for working with trace instances.
Date: Mon, 21 Dec 2020 08:02:50 +0200 [thread overview]
Message-ID: <20201221060252.177890-7-tz.stoyanov@gmail.com> (raw)
In-Reply-To: <20201221060252.177890-1-tz.stoyanov@gmail.com>
Documented APIs:
tracefs_instance_get_name()
tracefs_instances_walk()
tracefs_instance_exists()
Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
Documentation/libtracefs-instances-utils.txt | 112 +++++++++++++++++++
1 file changed, 112 insertions(+)
create mode 100644 Documentation/libtracefs-instances-utils.txt
diff --git a/Documentation/libtracefs-instances-utils.txt b/Documentation/libtracefs-instances-utils.txt
new file mode 100644
index 0000000..aa5efbd
--- /dev/null
+++ b/Documentation/libtracefs-instances-utils.txt
@@ -0,0 +1,112 @@
+libtracefs(3)
+=============
+
+NAME
+----
+tracefs_instance_get_name, tracefs_instances_walk, tracefs_instance_exists -
+Helper functions for working with tracing instances.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <tracefs.h>*
+
+const char pass:[*]*tracefs_instance_get_name*(struct tracefs_instance pass:[*]_instance_);
+int *tracefs_instances_walk*(int (pass:[*]_callback_)(const char pass:[*], void pass:[*]), void pass:[*]_context)_;
+bool *tracefs_instance_exists*(const char pass:[*]_name_);
+
+--
+
+DESCRIPTION
+-----------
+Helper functions for working with trace instances.
+
+The _tracefs_instance_get_name()_ function returns the name of the given _instance_.
+Note that the top instance has no name, the function returns NULL for it.
+
+The _tracefs_instances_walk()_ function walks through all configured tracing
+instances in the system and calls _callback_ for each one of them. The _context_
+argument is passed to the _callback_, together with the instance name. If the
+_callback_ returns non-zero, the iteration stops. Note, the _callback_ is not
+called for the top top instance.
+
+The _tracefs_instance_exists()_ function checks if an instance with the given
+_name_ exists in the system.
+
+RETURN VALUE
+------------
+The _tracefs_instance_get_name()_ returns a string or NULL in case of the top
+instance. The returned string must _not_ be freed.
+
+The _tracefs_instances_walk()_ function returns 0, if all instances were iterated, 1
+if the iteration was stopped by the _callback_, or -1 in case of an error.
+
+The _tracefs_instance_exists()_ returns true if an instance with the given name
+exists in the system or false otherwise.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <tracefs.h>
+
+struct tracefs_instance *inst;
+....
+char *name = tracefs_instance_get_name(inst);
+
+ if(name) {
+ /* Got name of the instance */
+ }
+
+...
+static int instance_walk(char *name, void *context)
+{
+ /* Got instance with name */
+ return 0;
+}
+...
+ if (tracefs_instances_walk(instance_walk, NULL) < 0) {
+ /* Error walking through the instances */
+ }
+...
+ if (tracefs_instance_exists("foo")) {
+ /* There is instance with name foo in the system */
+ } else {
+ /* There is no instance with name foo in the system */
+ }
+--
+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/
\ No newline at end of file
--
2.28.0
next prev parent reply other threads:[~2020-12-21 6:04 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-12-21 6:02 [PATCH v2 0/8] libtracefs man pages Tzvetomir Stoyanov (VMware)
2020-12-21 6:02 ` [PATCH v2 1/8] libtracefs: Initial support for " Tzvetomir Stoyanov (VMware)
2020-12-21 6:02 ` [PATCH v2 2/8] libtracefs man pages: APIs for locating trace directory and files Tzvetomir Stoyanov (VMware)
2020-12-21 16:00 ` Steven Rostedt
2020-12-21 6:02 ` [PATCH v2 3/8] libtracefs man pages: APIs for working with trace systems and events Tzvetomir Stoyanov (VMware)
2020-12-21 16:18 ` Steven Rostedt
2020-12-21 6:02 ` [PATCH v2 4/8] libtracefs man pages: APIs for managing trace instances Tzvetomir Stoyanov (VMware)
2020-12-21 16:51 ` Steven Rostedt
2020-12-21 6:02 ` [PATCH v2 5/8] libtracefs man pages: APIs for working with files in " Tzvetomir Stoyanov (VMware)
2020-12-21 6:02 ` Tzvetomir Stoyanov (VMware) [this message]
2020-12-21 6:02 ` [PATCH v2 7/8] libtracefs man pages: APIs for initializing a tep handler with trace events from the local system Tzvetomir Stoyanov (VMware)
2020-12-21 17:19 ` Steven Rostedt
2020-12-21 6:02 ` [PATCH v2 8/8] libtracefs man pages: helper APIs for working with trace file system Tzvetomir Stoyanov (VMware)
2020-12-21 17:21 ` Steven Rostedt
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20201221060252.177890-7-tz.stoyanov@gmail.com \
--to=tz.stoyanov@gmail.com \
--cc=linux-trace-devel@vger.kernel.org \
--cc=rostedt@goodmis.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).