From: Tzvetomir Stoyanov <tstoyanov@vmware.com>
To: rostedt@goodmis.org
Cc: linux-trace-devel@vger.kernel.org
Subject: [PATCH v6 17/26] tools/lib/traceevent: Man pages find field APIs
Date: Fri, 3 May 2019 12:11:10 +0300 [thread overview]
Message-ID: <20190503091119.23399-18-tstoyanov@vmware.com> (raw)
In-Reply-To: <20190503091119.23399-1-tstoyanov@vmware.com>
Create man pages for libtraceevent APIs:
tep_find_common_field(),
tep_find_field()
tep_find_any_field()
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-field_find.txt | 118 ++++++++++++++++++
1 file changed, 118 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_find.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-field_find.txt b/tools/lib/traceevent/Documentation/libtraceevent-field_find.txt
new file mode 100644
index 000000000000..0896af5b9eff
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-field_find.txt
@@ -0,0 +1,118 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_find_common_field, tep_find_field, tep_find_any_field -
+Search for a field in an event.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+struct tep_format_field pass:[*]*tep_find_common_field*(struct tep_event pass:[*]_event_, const char pass:[*]_name_);
+struct tep_format_field pass:[*]*tep_find_field*(struct tep_event_ormat pass:[*]_event_, const char pass:[*]_name_);
+struct tep_format_field pass:[*]*tep_find_any_field*(struct tep_event pass:[*]_event_, const char pass:[*]_name_);
+--
+
+DESCRIPTION
+-----------
+These functions search for a field with given name in an event. The field
+returned can be used to find the field content from within a data record.
+
+The _tep_find_common_field()_ function searches for a common field with _name_
+in the _event_.
+
+The _tep_find_field()_ function searches for an event specific field with
+_name_ in the _event_.
+
+The _tep_find_any_field()_ function searches for any field with _name_ in the
+_event_.
+
+RETURN VALUE
+------------
+The _tep_find_common_field(), _tep_find_field()_ and _tep_find_any_field()_
+functions return a pointer to the found field, or NULL in case there is no field
+with the requested name.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+void get_htimer_info(struct tep_handle *tep, struct tep_record *record)
+{
+ struct tep_format_field *field;
+ struct tep_event *event;
+ long long softexpires;
+ int mode;
+ int pid;
+
+ event = tep_find_event_by_name(tep, "timer", "hrtimer_start");
+
+ field = tep_find_common_field(event, "common_pid");
+ if (field == NULL) {
+ /* Cannot find "common_pid" field in the event */
+ } else {
+ /* Get pid from the data record */
+ pid = tep_read_number(tep, record->data + field->offset,
+ field->size);
+ }
+
+ field = tep_find_field(event, "softexpires");
+ if (field == NULL) {
+ /* Cannot find "softexpires" event specific field in the event */
+ } else {
+ /* Get softexpires parameter from the data record */
+ softexpires = tep_read_number(tep, record->data + field->offset,
+ field->size);
+ }
+
+ field = tep_find_any_field(event, "mode");
+ if (field == NULL) {
+ /* Cannot find "mode" field in the event */
+ } else
+ {
+ /* Get mode parameter from the data record */
+ mode = tep_read_number(tep, record->data + field->offset,
+ field->size);
+ }
+}
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-ltraceevent*
+ Linker switch to add when building a program that uses the library.
+--
+
+SEE ALSO
+--------
+_libtraceevent(3)_, _trace-cmd(1)_
+
+AUTHOR
+------
+[verse]
+--
+*Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
--
2.20.1
next prev parent reply other threads:[~2019-05-03 9:11 UTC|newest]
Thread overview: 30+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-05-03 9:10 [PATCH v6 00/26] Libtraceevent MAN pages Tzvetomir Stoyanov
2019-05-03 9:10 ` [PATCH v6 01/26] tools/lib/traceevent: Implement libtraceevent man pages Tzvetomir Stoyanov
2019-05-10 17:34 ` Steven Rostedt
2019-05-03 9:10 ` [PATCH v6 02/26] tools/lib/traceevent: Add support for man pages with multiple names Tzvetomir Stoyanov
2019-05-03 9:10 ` [PATCH v6 03/26] tools/lib/traceevent: libtraceevent man pages for tep_handler related APIs Tzvetomir Stoyanov
2019-05-03 9:10 ` [PATCH v6 04/26] tools/lib/traceevent: Man page for header_page APIs Tzvetomir Stoyanov
2019-05-03 9:10 ` [PATCH v6 05/26] tools/lib/traceevent: Man page for get/set cpus APIs Tzvetomir Stoyanov
2019-05-03 9:10 ` [PATCH v6 06/26] tools/lib/traceevent: Man page for file endian APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 07/26] tools/lib/traceevent: Man page for host " Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 08/26] tools/lib/traceevent: Man page for page size APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 09/26] tools/lib/traceevent: Man page for tep_strerror() Tzvetomir Stoyanov
2019-05-10 17:48 ` Steven Rostedt
2019-05-03 9:11 ` [PATCH v6 10/26] tools/lib/traceevent: Man pages for event handler APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 11/26] tools/lib/traceevent: Man pages for function related libtraceevent APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 12/26] tools/lib/traceevent: Man pages for registering print function Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 13/26] tools/lib/traceevent: Man page for tep_read_number() Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 14/26] tools/lib/traceevent: Man pages for event find APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 15/26] tools/lib/traceevent: Man page for list events APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 16/26] tools/lib/traceevent: Man pages for libtraceevent event get APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` Tzvetomir Stoyanov [this message]
2019-05-03 9:11 ` [PATCH v6 18/26] tools/lib/traceevent: Man pages get field value APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 19/26] tools/lib/traceevent: Man pages for print field APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 20/26] tools/lib/traceevent: Man page for tep_read_number_field() Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 21/26] tools/lib/traceevent: Man pages for event fields APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 22/26] tools/lib/traceevent: Man pages for event filter APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 23/26] tools/lib/traceevent: Man pages for parse event APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 24/26] tools/lib/traceevent: Man page for tep_parse_header_page() Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 25/26] tools/lib/traceevent: Man pages for APIs, used to extract common fields from a record Tzvetomir Stoyanov
2019-05-10 18:29 ` Steven Rostedt
2019-05-03 9:11 ` [PATCH v6 26/26] tools/lib/traceevent: Man pages for trace sequences APIs Tzvetomir Stoyanov
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=20190503091119.23399-18-tstoyanov@vmware.com \
--to=tstoyanov@vmware.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).