[v2,1/3] libtracefs: Rename the 'tracefs_get_hist_*()' APIs

Commit Message

Yordan Karadzhov Dec. 9, 2021, 10:45 a.m. UTC

The following APIs are renamed:
tracefs_get_hist_name()   -> tracefs_hist_get_name()
tracefs_get_hist_event()  -> tracefs_hist_get_event()
tracefs_get_hist_system() -> tracefs_hist_get_system()

This is done in order to match the naming convention used in
the library. The patch adds documentation as well.

Signed-off-by: Yordan Karadzhov (VMware) <[e-mail]>
---
 Documentation/libtracefs-hist.txt | 24 +++++++++++++++++++++++-
 include/tracefs.h                 |  6 +++---
 src/tracefs-hist.c                | 24 +++++++++++++++++++++---
 3 files changed, 47 insertions(+), 7 deletions(-)

Patch

diff --git a/Documentation/libtracefs-hist.txt b/Documentation/libtracefs-hist.txt
index 2eef718..3a167e8 100644
--- a/Documentation/libtracefs-hist.txt
+++ b/Documentation/libtracefs-hist.txt
@@ -4,7 +4,8 @@  libtracefs(3)
 NAME
 ----
 tracefs_hist_alloc, tracefs_hist_free, tracefs_hist_add_key, tracefs_hist_add_value, tracefs_hist_add_name, tracefs_hist_start,
-tracefs_hist_destory, tracefs_hist_add_sort_key, tracefs_hist_set_sort_key,tracefs_hist_sort_key_direction - Create and update event histograms
+tracefs_hist_destory, tracefs_hist_add_sort_key, tracefs_hist_set_sort_key, tracefs_hist_sort_key_direction
+tracefs_hist_echo_cmd, tracefs_hist_get_name, tracefs_hist_get_event, tracefs_hist_get_system - Create, update and describe event histograms
 
 SYNOPSIS
 --------
@@ -69,6 +70,12 @@  int tracefs_hist_command(struct tracefs_instance pass:[*]instance,
 			 struct tracefs_hist pass:[*]hist,
 			 enum tracefs_hist_command command);
 
+const char *tracefs_hist_get_name(struct tracefs_hist pass:[*]hist);
+
+const char *tracefs_hist_get_event(struct tracefs_hist pass:[*]hist);
+
+const char *tracefs_hist_get_system(struct tracefs_hist pass:[*]hist);
+
 --
 
 DESCRIPTION
@@ -229,12 +236,27 @@  instead of showing the number, show the name of the running task.
 *TRACEFS_HIST_KEY_USECS* for use with "common_timestamp" or TRACEFS_HIST_TIMESTAMP,
 in which case it will show the timestamp in microseconds instead of nanoseconds.
 
+*tracefs_hist_get_name*() returns the name of the histogram or NULL on error.
+The returned string belongs to the histogram object and is freed with the histogram
+by *tracefs_hist_free*().
+
+*tracefs_hist_get_event*() returns the event name of the histogram or NULL on error.
+The returned string belongs to the histogram object and is freed with the histogram
+by *tracefs_hist_free*().
+
+*tracefs_hist_get_system*() returns the system name of the histogram or NULL on error.
+The returned string belongs to the histogram object and is freed with the histogram
+by *tracefs_hist_free*().
+
 
 RETURN VALUE
 ------------
 *tracefs_hist_alloc_nd*() returns an allocated histogram descriptor which must
 be freed by *tracefs_hist_free*() or NULL on error.
 
+*tracefs_hist_get_name*(), *tracefs_hist_get_event*() and *tracefs_hist_get_system*()
+return strings owned by the histogram object.
+
 All the other functions return zero on success or -1 on error.
 
 If *tracefs_hist_start*() returns an error, a message may be displayed
diff --git a/include/tracefs.h b/include/tracefs.h
index 3ac3d9c..b874d3f 100644
--- a/include/tracefs.h
+++ b/include/tracefs.h
@@ -354,9 +354,9 @@  struct tracefs_hist *
 tracefs_hist_alloc_nd(struct tep_handle *tep,
 		      const char *system, const char *event_name,
 		      struct tracefs_hist_axis *axes);
-const char *tracefs_get_hist_name(struct tracefs_hist *hist);
-const char *tracefs_get_hist_event(struct tracefs_hist *hist);
-const char *tracefs_get_hist_system(struct tracefs_hist *hist);
+const char *tracefs_hist_get_name(struct tracefs_hist *hist);
+const char *tracefs_hist_get_event(struct tracefs_hist *hist);
+const char *tracefs_hist_get_system(struct tracefs_hist *hist);
 int tracefs_hist_add_key(struct tracefs_hist *hist, const char *key,
 			 enum tracefs_hist_key_type type);
 int tracefs_hist_add_value(struct tracefs_hist *hist, const char *value);
diff --git a/src/tracefs-hist.c b/src/tracefs-hist.c
index ea9e127..59ac5e4 100644
--- a/src/tracefs-hist.c
+++ b/src/tracefs-hist.c
@@ -41,17 +41,35 @@  struct tracefs_hist {
 	unsigned int		filter_state;
 };
 
-const char *tracefs_get_hist_name(struct tracefs_hist *hist)
+/*
+ * tracefs_hist_get_name - get the name of the histogram
+ * @hist: The histogram to get the name for
+ *
+ * Returns name string owned by @hist on success, or NULL on error.
+ */
+const char *tracefs_hist_get_name(struct tracefs_hist *hist)
 {
 	return hist ? hist->name : NULL;
 }
 
-const char *tracefs_get_hist_event(struct tracefs_hist *hist)
+/*
+ * tracefs_hist_get_event - get the event name of the histogram
+ * @hist: The histogram to get the event name for
+ *
+ * Returns event name string owned by @hist on success, or NULL on error.
+ */
+const char *tracefs_hist_get_event(struct tracefs_hist *hist)
 {
 	return hist ? hist->event_name : NULL;
 }
 
-const char *tracefs_get_hist_system(struct tracefs_hist *hist)
+/*
+ * tracefs_hist_get_system - get the system name of the histogram
+ * @hist: The histogram to get the system name for
+ *
+ * Returns system name string owned by @hist on success, or NULL on error.
+ */
+const char *tracefs_hist_get_system(struct tracefs_hist *hist)
 {
 	return hist ? hist->system : NULL;
 }