linux-trace-devel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: "Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com>
To: rostedt@goodmis.org
Cc: linux-trace-devel@vger.kernel.org
Subject: [PATCH v2 4/8] libtracefs man pages: APIs for managing trace instances.
Date: Mon, 21 Dec 2020 08:02:48 +0200	[thread overview]
Message-ID: <20201221060252.177890-5-tz.stoyanov@gmail.com> (raw)
In-Reply-To: <20201221060252.177890-1-tz.stoyanov@gmail.com>

Documented APIs:
tracefs_instance_create()
tracefs_instance_destroy()
tracefs_instance_free()
tracefs_instance_is_new()

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 Documentation/libtracefs-instances-manage.txt | 111 ++++++++++++++++++
 1 file changed, 111 insertions(+)
 create mode 100644 Documentation/libtracefs-instances-manage.txt

diff --git a/Documentation/libtracefs-instances-manage.txt b/Documentation/libtracefs-instances-manage.txt
new file mode 100644
index 0000000..aca2161
--- /dev/null
+++ b/Documentation/libtracefs-instances-manage.txt
@@ -0,0 +1,111 @@
+libtracefs(3)
+=============
+
+NAME
+----
+tracefs_instance_create, tracefs_instance_destroy, tracefs_instance_free,
+tracefs_instance_is_new - Manage trace instances.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <tracefs.h>*
+
+struct tracefs_instance pass:[*]*tracefs_instance_create*(const char pass:[*]_name_);
+int *tracefs_instance_destroy*(struct tracefs_instance pass:[*]_instance_);
+void *tracefs_instance_free*(struct tracefs_instance pass:[*]_instance_);
+bool *tracefs_instance_is_new*(struct tracefs_instance pass:[*]_instance_);
+
+--
+
+DESCRIPTION
+-----------
+This set of functions can be used to manage trace instances. A trace
+instance is a sub buffer used by the Linux tracing system. Given a unique
+name, the events enabled in an instance do not affect the main tracing
+system, nor other instances, as events enabled in the main tracing system
+or other instances do not affect the given instance.
+
+The _tracefs_instance_create()_ function allocates and initializes a new
+tracefs_instance structure and returns it. If the instance does not yet
+exist in the system, it will be created.
+
+The _tracefs_instance_destroy()_ frees the _instance_ structure, and will
+also remove the trace instance from the system.
+
+The _tracefs_instance_free()_ function frees the tracefs_instance structure,
+without removing the trace instance from the system.
+
+The _tracefs_instance_is_new()_ function checks if the given _instance_ is
+newly created by _tracefs_instance_create()_, or it has been in the system
+before that.
+
+RETURN VALUE
+------------
+The _tracefs_instance_create()_ function returns a pointer to a newly allocated
+tracefs_instance structure. It must be freed with _tracefs_instance_destroy()_ or
+_tracefs_instance_free()_.
+
+The _tracefs_instance_destroy()_ function returns -1 in case of an error,
+or 0 otherwise.
+
+The _tracefs_instance_is_new()_ function returns true if the
+_tracefs_instance_create() that allocated _instance_ also created the
+trace instance in the system, or false if the trace instance already
+existed in the system when _instance_ was allocated by
+_tracefs_instance_create()_.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <tracefs.h>
+
+struct tracefs_instance *inst = tracefs_instance_create("foo");
+	if (!inst) {
+		/* Error creating a new trace instance */
+		...
+	}
+
+	...
+
+	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@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


  parent reply	other threads:[~2020-12-21  6:03 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 ` Tzvetomir Stoyanov (VMware) [this message]
2020-12-21 16:51   ` [PATCH v2 4/8] libtracefs man pages: APIs for managing trace instances 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 ` [PATCH v2 6/8] libtracefs man pages: helper APIs for working with " Tzvetomir Stoyanov (VMware)
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-5-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).