From: "Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com>
To: rostedt@goodmis.org
Cc: linux-trace-devel@vger.kernel.org
Subject: [PATCH 3/6] libtracefs: Documentation for the new APIs for opening and reading ftrace files
Date: Thu, 7 Jan 2021 10:32:47 +0200 [thread overview]
Message-ID: <20210107083250.16295-4-tz.stoyanov@gmail.com> (raw)
In-Reply-To: <20210107083250.16295-1-tz.stoyanov@gmail.com>
Man pages updated with documentation about:
tracefs_instance_file_open();
tracefs_instance_file_read_int();
Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
Documentation/libtracefs-instances-files.txt | 47 ++++++++++++++++++--
1 file changed, 43 insertions(+), 4 deletions(-)
diff --git a/Documentation/libtracefs-instances-files.txt b/Documentation/libtracefs-instances-files.txt
index 9b18b73..d3aaef2 100644
--- a/Documentation/libtracefs-instances-files.txt
+++ b/Documentation/libtracefs-instances-files.txt
@@ -4,8 +4,8 @@ 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.
+tracefs_instance_get_dir, tracefs_instance_file_open, tracefs_instance_file_write,
+tracefs_instance_file_read, tracefs_instance_file_read_int - Work with files in tracing instances.
SYNOPSIS
--------
@@ -17,8 +17,10 @@ bool *tracefs_file_exists*(struct tracefs_instance pass:[*]_instance_, char pass
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_open*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, int _mode_);
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_);
+char pass:[*]*tracefs_instance_file_read*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, int pass:[*]_psize_);
+int *tracefs_instance_file_read_int*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, long long int pass:[*]_res_);
--
@@ -41,12 +43,19 @@ The _tracefs_instance_get_dir()_ function returns the full path of the director
with given _name_ in _instance_. Note, it does not check if the directory exists
in the instance.
+The _tracefs_instance_file_open()_ function opens trace _file_ from given _instance_ and returns
+a file descriptor to it. The file access _mode_ can be specified, see *open*(3) for more details.
+If -1 is passed as _mode_, default O_RDWR is used.
+
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 _tracefs_instance_file_read()_ function reads the content of a _file_ from
the given _instance_.
+The _tracefs_instance_file_read_int()_ function reads the content of a _file_ from
+the given _instance_ and converts it to a long long integer, which is stored in _res_.
+
RETURN VALUE
------------
The _tracefs_file_exists()_ and _tracefs_dir_exists()_ functions return true if the
@@ -56,6 +65,9 @@ The _tracefs_instance_get_file()_ and _tracefs_instance_get_dir()_ functions ret
a string or NULL in case of an error. The returned string must be freed with
_tracefs_put_tracing_file()_.
+The _tracefs_instance_file_open()_ function returns a file descriptor to the opened file. It must be
+closed with *close*(3). In case of an error, -1 is returned.
+
The _tracefs_instance_file_write()_ function returns the number of written bytes,
or -1 in case of an error.
@@ -63,6 +75,9 @@ The _tracefs_instance_file_read()_ function returns a pointer to a NULL terminat
string, read from the file, or NULL in case of an error. The returned string must
be freed with free().
+The _tracefs_instance_file_read_int()_ function returns 0 if a valid integer is read from the file
+and stored in _res_ or -1 in case of an error.
+
EXAMPLE
-------
[source,c]
@@ -123,6 +138,30 @@ struct tracefs_instance *inst = tracefs_instance_create("foo");
tracefs_instance_destroy(inst);
else
tracefs_instance_free(inst);
+ ...
+
+ long long int res;
+ if (tracefs_instance_file_read_int(NULL, "tracing_on", &res) == 0) {
+ if (res == 0) {
+ /* tracing is disabled in the top instance */
+ } else if (res == 1) {
+ /* tracing is enabled in the top instance */
+ } else {
+ /* Unknown tracing state of the top instance */
+ }
+ } else {
+ /* Failed to read integer from tracing_on file */
+ }
+
+ ...
+
+ int fd;
+ fd = tracefs_instance_file_open(NULL, "tracing_on", O_WRONLY);
+ if (fd >= 0) {
+ /* Got file descriptor to the tracing_on file from the top instance for writing */
+ ...
+ close(fd);
+ }
--
FILES
-----
--
2.29.2
next prev parent reply other threads:[~2021-01-07 8:33 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-01-07 8:32 [PATCH 0/6] New libtracefs APIs Tzvetomir Stoyanov (VMware)
2021-01-07 8:32 ` [PATCH 1/6] libtracefs: New APIs for opening and reading ftrace files Tzvetomir Stoyanov (VMware)
2021-01-07 15:58 ` Steven Rostedt
2021-01-07 8:32 ` [PATCH 2/6] libtracefs: New APIs for enable / disable tracing Tzvetomir Stoyanov (VMware)
2021-01-07 16:12 ` Steven Rostedt
2021-01-07 8:32 ` Tzvetomir Stoyanov (VMware) [this message]
2021-01-07 8:32 ` [PATCH 4/6] libtracefs: Documentation for enable / disable tracing APIs Tzvetomir Stoyanov (VMware)
2021-01-07 16:37 ` Steven Rostedt
2021-01-07 8:32 ` [PATCH 5/6] libtracefs: Unit tests for the new APIs for opening and reading ftrace files Tzvetomir Stoyanov (VMware)
2021-01-07 8:32 ` [PATCH 6/6] libtracefs: Unit tests for enable / disable tracing APIs 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=20210107083250.16295-4-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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.