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 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).