From: "Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com>
To: rostedt@goodmis.org
Cc: linux-trace-devel@vger.kernel.org
Subject: [PATCH 1/2] libtracefs: Document new instance APIs
Date: Thu, 18 Feb 2021 05:38:45 +0200 [thread overview]
Message-ID: <20210218033846.1891289-2-tz.stoyanov@gmail.com> (raw)
In-Reply-To: <20210218033846.1891289-1-tz.stoyanov@gmail.com>
Added documentation for these new APIs:
tracefs_instance_alloc()
tracefs_instance_get_trace_dir()
Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
Documentation/libtracefs-instances-manage.txt | 34 +++++++++++++++----
Documentation/libtracefs-instances-utils.txt | 16 +++++++--
2 files changed, 41 insertions(+), 9 deletions(-)
diff --git a/Documentation/libtracefs-instances-manage.txt b/Documentation/libtracefs-instances-manage.txt
index a831ef2..e7dc393 100644
--- a/Documentation/libtracefs-instances-manage.txt
+++ b/Documentation/libtracefs-instances-manage.txt
@@ -3,7 +3,7 @@ libtracefs(3)
NAME
----
-tracefs_instance_create, tracefs_instance_destroy, tracefs_instance_free,
+tracefs_instance_create, tracefs_instance_destroy, tracefs_instance_alloc, tracefs_instance_free,
tracefs_instance_is_new - Manage trace instances.
SYNOPSIS
@@ -14,6 +14,7 @@ SYNOPSIS
struct tracefs_instance pass:[*]*tracefs_instance_create*(const char pass:[*]_name_);
int *tracefs_instance_destroy*(struct tracefs_instance pass:[*]_instance_);
+struct tracefs_instance pass:[*]*tracefs_instance_alloc*(const char pass:[*]_tracing_dir_, const char pass:[*]_name_);
void *tracefs_instance_free*(struct tracefs_instance pass:[*]_instance_);
bool *tracefs_instance_is_new*(struct tracefs_instance pass:[*]_instance_);
@@ -28,12 +29,22 @@ 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.
+tracefs_instance structure and returns it. If the instance with _name_ does
+not yet exist in the system, it will be created. The _name_ could be NULL,
+then the new tracefs_instance structure is initialised for the top instance.
+Note that the top instance cannot be created in the system, if it does not
+exist.
The _tracefs_instance_destroy()_ frees the _instance_ structure, and will
also remove the trace instance from the system.
+The _tracefs_instance_alloc()_ function allocates a new tracefs_instance structure
+for existing trace instance. If the instance does not exist in the system, the function
+fails. The _tracing_dir_ parameter points to the system trace directory. It can be
+NULL, then default system trace directory is used. This parameter is useful to allocate
+instances to trace directories, copied from another machine. The _name_ is the name of
+the instance, or NULL for the top instance in the given _tracing_dir_.
+
The _tracefs_instance_free()_ function frees the tracefs_instance structure,
without removing the trace instance from the system.
@@ -43,8 +54,8 @@ 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
+The _tracefs_instance_create()_ and _tracefs_instance_alloc()_ functions return 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,
@@ -54,7 +65,7 @@ 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()_.
+_tracefs_instance_create()_ or _tracefs_instance_alloc()_.
EXAMPLE
-------
@@ -74,6 +85,17 @@ struct tracefs_instance *inst = tracefs_instance_create("foo");
tracefs_instance_destroy(inst);
else
tracefs_instance_free(inst);
+...
+
+struct tracefs_instance *inst = tracefs_instance_alloc(NULL, "bar");
+ if (!inst) {
+ /* Error allocating 'bar' trace instance */
+ ...
+ }
+
+ ...
+
+ tracefs_instance_free(inst);
--
FILES
-----
diff --git a/Documentation/libtracefs-instances-utils.txt b/Documentation/libtracefs-instances-utils.txt
index 3bd54a5..f559406 100644
--- a/Documentation/libtracefs-instances-utils.txt
+++ b/Documentation/libtracefs-instances-utils.txt
@@ -3,7 +3,8 @@ libtracefs(3)
NAME
----
-tracefs_instance_get_name, tracefs_instances_walk, tracefs_instance_exists -
+tracefs_instance_get_name, tracefs_instance_get_trace_dir,
+tracefs_instances_walk, tracefs_instance_exists -
Helper functions for working with tracing instances.
SYNOPSIS
@@ -13,6 +14,7 @@ SYNOPSIS
*#include <tracefs.h>*
const char pass:[*]*tracefs_instance_get_name*(struct tracefs_instance pass:[*]_instance_);
+const char pass:[*]*tracefs_instance_get_trace_dir*(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_);
@@ -25,6 +27,9 @@ 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_instance_get_trace_dir()_ function returns the tracing directory, where
+the given _instance_ is configured.
+
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
@@ -39,6 +44,9 @@ 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_instance_get_trace_dir()_ returns a string or NULL in case of an error.
+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.
@@ -54,11 +62,13 @@ EXAMPLE
struct tracefs_instance *inst;
....
char *name = tracefs_instance_get_name(inst);
-
if(name) {
/* Got name of the instance */
}
-
+char *dir = tracefs_instance_get_trace_dir(inst);
+ if(dir) {
+ /* Got tracing directory of the instance */
+ }
...
static int instance_walk(char *name, void *context)
{
--
2.29.2
next prev parent reply other threads:[~2021-02-18 3:39 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-02-18 3:38 [PATCH 0/2] Documentation for new libtracefs APIs Tzvetomir Stoyanov (VMware)
2021-02-18 3:38 ` Tzvetomir Stoyanov (VMware) [this message]
2021-02-18 3:38 ` [PATCH 2/2] libtracefs: Document APIs for trace options Tzvetomir Stoyanov (VMware)
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=20210218033846.1891289-2-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).