Fix: documentation: refer to bt_put()

[babeltrace.git] / include / babeltrace / ctf-ir / fields.h

diff --git a/include/babeltrace/ctf-ir/fields.h b/include/babeltrace/ctf-ir/fields.h
index 1b1ac8c2c8bcb53f86131ba5e62a370a57df472a..74a9f309f3bf41732012572ad5f573921b8c91d6 100644 (file)
--- a/include/babeltrace/ctf-ir/fields.h
+++ b/include/babeltrace/ctf-ir/fields.h
@@ -59,7 +59,7 @@ extern struct bt_ctf_field *bt_ctf_field_create(
  * bt_ctf_field_structure_get_field: get a structure's field.
  *
  * Get the structure's field corresponding to the provided field name.
- * bt_ctf_field_put() must be called on the returned value.
+ * bt_put() must be called on the returned value.
  *
  * @param structure Structure field instance.
  * @param name Name of the field in the provided structure.
@@ -73,7 +73,7 @@ extern struct bt_ctf_field *bt_ctf_field_structure_get_field(
  * bt_ctf_field_structure_get_field_by_index: get a structure's field by index.
  *
  * Get the structure's field corresponding to the provided field name.
- * bt_ctf_field_put() must be called on the returned value.
+ * bt_put() must be called on the returned value.
  * The indexes are the same as those provided for bt_ctf_field_type_structure.
  *
  * @param structure Structure field instance.
@@ -87,7 +87,7 @@ extern struct bt_ctf_field *bt_ctf_field_structure_get_field_by_index(
 /*
  * bt_ctf_field_array_get_field: get an array's field at position "index".
  *
- * Return the array's field at position "index". bt_ctf_field_put() must be
+ * Return the array's field at position "index". bt_put() must be
  * called on the returned value.
  *
  * @param array Array field instance.
@@ -130,7 +130,7 @@ extern int bt_ctf_field_sequence_set_length(struct bt_ctf_field *sequence,
  * Return the sequence's field at position "index". The sequence's length must
  * have been set prior to calling this function using
  * bt_ctf_field_sequence_set_length().
- * bt_ctf_field_put() must be called on the returned value.
+ * bt_put() must be called on the returned value.
  *
  * @param array Sequence field instance.
  * @param index Position of the sequence's desired element.
@@ -144,7 +144,7 @@ extern struct bt_ctf_field *bt_ctf_field_sequence_get_field(
  * bt_ctf_field_variant_get_field: get a variant's selected field.
  *
  * Return the variant's selected field. The "tag" field is the selector enum
- * field. bt_ctf_field_put() must be called on the returned value.
+ * field. bt_put() must be called on the returned value.
  *
  * @param variant Variant field instance.
  * @param tag Selector enumeration field.
@@ -170,11 +170,27 @@ extern struct bt_ctf_field *bt_ctf_field_variant_get_field(
 extern struct bt_ctf_field *bt_ctf_field_variant_get_current_field(
                struct bt_ctf_field *variant);
 
+/*
+ * bt_ctf_field_variant_get_tag: get the tag field of a variant.
+ *
+ * Return the variant's associated tag field. This function, unlike
+ * bt_ctf_field_variant_get_field(), does not create any field; it
+ * returns NULL if there's no current selected field yet (and, thus, no
+ * associated tag).
+ *
+ * @param variant Variant field instance.
+ *
+ * Returns a field instance (enumeration) on success, NULL on error or when
+ * there is no currently selected field.
+ */
+extern struct bt_ctf_field *bt_ctf_field_variant_get_tag(
+               struct bt_ctf_field *variant);
+
 /*
  * bt_ctf_field_enumeration_get_container: get an enumeration field's container.
  *
  * Return the enumeration's underlying container field (an integer).
- * bt_ctf_field_put() must be called on the returned value.
+ * bt_put() must be called on the returned value.
  *
  * @param enumeration Enumeration field instance.
  *
@@ -188,7 +204,7 @@ extern struct bt_ctf_field *bt_ctf_field_enumeration_get_container(
  *     name.
  *
  * Return the enumeration's underlying container field (an integer).
- * bt_ctf_field_put() must be called on the returned value.
+ * bt_put() must be called on the returned value.
  *
  * @param enumeration Enumeration field instance.
  *
@@ -460,25 +476,6 @@ extern int bt_ctf_field_is_variant(struct bt_ctf_field *field);
  */
 extern struct bt_ctf_field *bt_ctf_field_copy(struct bt_ctf_field *field);
 
-/*
- * bt_ctf_field_get and bt_ctf_field_put: increment and decrement the
- * field's reference count.
- *
- * You may also use bt_ctf_get() and bt_ctf_put() with field objects.
- *
- * These functions ensure that the field won't be destroyed when it
- * is in use. The same number of get and put (plus one extra put to
- * release the initial reference done at creation) have to be done to
- * destroy a field.
- *
- * When the field's reference count is decremented to 0 by a bt_ctf_field_put,
- * the field is freed.
- *
- * @param field Field instance.
- */
-extern void bt_ctf_field_get(struct bt_ctf_field *field);
-extern void bt_ctf_field_put(struct bt_ctf_field *field);
-
 #ifdef __cplusplus
 }
 #endif