* http://www.efficios.com/ctf
*/
+/* For bt_bool */
+#include <babeltrace/types.h>
+
#include <stdint.h>
+#include <stddef.h>
#ifdef __cplusplus
extern "C" {
<th>CTF IR field which you can create from this field type
</tr>
<tr>
- <td>#BT_CTF_TYPE_ID_INTEGER
+ <td>#BT_CTF_FIELD_TYPE_ID_INTEGER
<td>\ref ctfirintfieldtype
<td>\ref ctfirintfield
</tr>
<tr>
- <td>#BT_CTF_TYPE_ID_FLOAT
+ <td>#BT_CTF_FIELD_TYPE_ID_FLOAT
<td>\ref ctfirfloatfieldtype
<td>\ref ctfirfloatfield
</tr>
<tr>
- <td>#BT_CTF_TYPE_ID_ENUM
+ <td>#BT_CTF_FIELD_TYPE_ID_ENUM
<td>\ref ctfirenumfieldtype
<td>\ref ctfirenumfield
</tr>
<tr>
- <td>#BT_CTF_TYPE_ID_STRING
+ <td>#BT_CTF_FIELD_TYPE_ID_STRING
<td>\ref ctfirstringfieldtype
<td>\ref ctfirstringfield
</tr>
<tr>
- <td>#BT_CTF_TYPE_ID_STRUCT
+ <td>#BT_CTF_FIELD_TYPE_ID_STRUCT
<td>\ref ctfirstructfieldtype
<td>\ref ctfirstructfield
</tr>
<tr>
- <td>#BT_CTF_TYPE_ID_ARRAY
+ <td>#BT_CTF_FIELD_TYPE_ID_ARRAY
<td>\ref ctfirarrayfieldtype
<td>\ref ctfirarrayfield
</tr>
<tr>
- <td>#BT_CTF_TYPE_ID_SEQUENCE
+ <td>#BT_CTF_FIELD_TYPE_ID_SEQUENCE
<td>\ref ctfirseqfieldtype
<td>\ref ctfirseqfield
</tr>
<tr>
- <td>#BT_CTF_TYPE_ID_VARIANT
+ <td>#BT_CTF_FIELD_TYPE_ID_VARIANT
<td>\ref ctfirvarfieldtype
<td>\ref ctfirvarfield
</tr>
</table>
Each field type has its own <strong>type ID</strong> (see
-#bt_ctf_type_id). You get the type ID of a field type object
+#bt_ctf_field_type_id). You get the type ID of a field type object
with bt_ctf_field_type_get_type_id().
You can get a deep copy of a field type with bt_ctf_field_type_copy().
struct bt_ctf_event;
struct bt_ctf_field;
struct bt_ctf_field_path;
+struct bt_ctf_field_type_enumeration_mapping_iterator;
/** @cond DOCUMENT */
/*
* Babeltrace 1.x enumerations that were also used in CTF writer's API.
* They are left here for backward compatibility reasons, but
- * enum bt_ctf_type_id and enum bt_ctf_string_encoding should be used
+ * enum bt_ctf_field_type_id and enum bt_ctf_string_encoding should be used
* in new code. Both new enumerations are compatible with their legacy
* counterpart.
*/
enum ctf_type_id {
- CTF_TYPE_UNKNOWN = 0,
- CTF_TYPE_INTEGER,
- CTF_TYPE_FLOAT,
- CTF_TYPE_ENUM,
- CTF_TYPE_STRING,
- CTF_TYPE_STRUCT,
- CTF_TYPE_UNTAGGED_VARIANT,
- CTF_TYPE_VARIANT,
- CTF_TYPE_ARRAY,
- CTF_TYPE_SEQUENCE,
+ CTF_TYPE_UNKNOWN = -1,
+ CTF_TYPE_INTEGER = 0,
+ CTF_TYPE_FLOAT = 1,
+ CTF_TYPE_ENUM = 2,
+ CTF_TYPE_STRING = 3,
+ CTF_TYPE_STRUCT = 4,
+ CTF_TYPE_UNTAGGED_VARIANT = 5,
+ CTF_TYPE_VARIANT = 5,
+ CTF_TYPE_ARRAY = 6,
+ CTF_TYPE_SEQUENCE = 7,
NR_CTF_TYPES,
};
/**
@brief Type ID of a @ft.
*/
-enum bt_ctf_type_id {
+enum bt_ctf_field_type_id {
/// Unknown, used for errors.
- BT_CTF_TYPE_ID_UNKNOWN = CTF_TYPE_UNKNOWN,
+ BT_CTF_FIELD_TYPE_ID_UNKNOWN = CTF_TYPE_UNKNOWN,
/// \ref ctfirintfieldtype
- BT_CTF_TYPE_ID_INTEGER = CTF_TYPE_INTEGER,
+ BT_CTF_FIELD_TYPE_ID_INTEGER = CTF_TYPE_INTEGER,
/// \ref ctfirfloatfieldtype
- BT_CTF_TYPE_ID_FLOAT = CTF_TYPE_FLOAT,
+ BT_CTF_FIELD_TYPE_ID_FLOAT = CTF_TYPE_FLOAT,
/// \ref ctfirenumfieldtype
- BT_CTF_TYPE_ID_ENUM = CTF_TYPE_ENUM,
+ BT_CTF_FIELD_TYPE_ID_ENUM = CTF_TYPE_ENUM,
/// \ref ctfirstringfieldtype
- BT_CTF_TYPE_ID_STRING = CTF_TYPE_STRING,
+ BT_CTF_FIELD_TYPE_ID_STRING = CTF_TYPE_STRING,
/// \ref ctfirstructfieldtype
- BT_CTF_TYPE_ID_STRUCT = CTF_TYPE_STRUCT,
-
- /// @cond DOCUMENT
- BT_CTF_TYPE_ID_UNTAGGED_VARIANT = CTF_TYPE_UNTAGGED_VARIANT,
- /// @endcond
+ BT_CTF_FIELD_TYPE_ID_STRUCT = CTF_TYPE_STRUCT,
/// \ref ctfirarrayfieldtype
- BT_CTF_TYPE_ID_ARRAY = CTF_TYPE_ARRAY,
+ BT_CTF_FIELD_TYPE_ID_ARRAY = CTF_TYPE_ARRAY,
/// \ref ctfirseqfieldtype
- BT_CTF_TYPE_ID_SEQUENCE = CTF_TYPE_SEQUENCE,
+ BT_CTF_FIELD_TYPE_ID_SEQUENCE = CTF_TYPE_SEQUENCE,
/// \ref ctfirvarfieldtype
- BT_CTF_TYPE_ID_VARIANT = CTF_TYPE_VARIANT,
+ BT_CTF_FIELD_TYPE_ID_VARIANT = CTF_TYPE_VARIANT,
/// Number of enumeration entries.
BT_CTF_NR_TYPE_IDS = NR_CTF_TYPES,
@param[in] field_type Field type of which to get the type ID.
@returns Type ID of \p field_type,
- or #BT_CTF_TYPE_ID_UNKNOWN on error.
+ or #BT_CTF_FIELD_TYPE_ID_UNKNOWN on error.
@prenotnull{field_type}
@postrefcountsame{field_type}
-@sa #bt_ctf_type_id: CTF IR field type ID.
+@sa #bt_ctf_field_type_id: CTF IR field type ID.
@sa bt_ctf_field_type_is_integer(): Returns whether or not a given
field type is a @intft.
@sa bt_ctf_field_type_is_floating_point(): Returns whether or not a
@sa bt_ctf_field_type_is_variant(): Returns whether or not a given
field type is a @varft.
*/
-extern enum bt_ctf_type_id bt_ctf_field_type_get_type_id(
+extern enum bt_ctf_field_type_id bt_ctf_field_type_get_type_id(
struct bt_ctf_field_type *field_type);
/**
@brief Returns whether or not the @ft \p field_type is a @intft.
@param[in] field_type Field type to check (can be \c NULL).
-@returns 1 if \p field_type is an integer field type,
- or 0 otherwise (including if \p field_type is
+@returns #BT_TRUE if \p field_type is an integer field type,
+ or #BT_FALSE otherwise (including if \p field_type is
\c NULL).
@prenotnull{field_type}
@sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
field type.
*/
-extern int bt_ctf_field_type_is_integer(struct bt_ctf_field_type *field_type);
+extern bt_bool bt_ctf_field_type_is_integer(
+ struct bt_ctf_field_type *field_type);
/**
@brief Returns whether or not the @ft \p field_type is a @floatft.
@param[in] field_type Field type to check (can be \c NULL).
-@returns 1 if \p field_type is a floating point
- number field type,
+@returns #BT_TRUE if \p field_type is a floating point
+ #BT_FALSE field type,
or 0 otherwise (including if \p field_type is
\c NULL).
@sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
field type.
*/
-extern int bt_ctf_field_type_is_floating_point(struct bt_ctf_field_type *field_type);
+extern bt_bool bt_ctf_field_type_is_floating_point(
+ struct bt_ctf_field_type *field_type);
/**
@brief Returns whether or not the @ft \p field_type is a @enumft.
@param[in] field_type Field type to check (can be \c NULL).
-@returns 1 if \p field_type is an enumeration field type,
- or 0 otherwise (including if \p field_type is
+@returns #BT_TRUE if \p field_type is an enumeration field type,
+ or #BT_FALSE otherwise (including if \p field_type is
\c NULL).
@postrefcountsame{field_type}
@sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
field type.
*/
-extern int bt_ctf_field_type_is_enumeration(struct bt_ctf_field_type *field_type);
+extern bt_bool bt_ctf_field_type_is_enumeration(
+ struct bt_ctf_field_type *field_type);
/**
@brief Returns whether or not the @ft \p field_type is a @stringft.
@param[in] field_type Field type to check (can be \c NULL).
-@returns 1 if \p field_type is a string field type,
- or 0 otherwise (including if \p field_type is
+@returns #BT_TRUE if \p field_type is a string field type,
+ or #BT_FALSE otherwise (including if \p field_type is
\c NULL).
@postrefcountsame{field_type}
@sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
field type.
*/
-extern int bt_ctf_field_type_is_string(struct bt_ctf_field_type *field_type);
+extern bt_bool bt_ctf_field_type_is_string(
+ struct bt_ctf_field_type *field_type);
/**
@brief Returns whether or not the @ft \p field_type is a @structft.
@param[in] field_type Field type to check (can be \c NULL).
-@returns 1 if \p field_type is a structure field type,
- or 0 otherwise (including if \p field_type is
+@returns #BT_TRUE if \p field_type is a structure field type,
+ or #BT_FALSE otherwise (including if \p field_type is
\c NULL).
@postrefcountsame{field_type}
@sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
field type.
*/
-extern int bt_ctf_field_type_is_structure(struct bt_ctf_field_type *field_type);
+extern bt_bool bt_ctf_field_type_is_structure(
+ struct bt_ctf_field_type *field_type);
/**
@brief Returns whether or not the @ft \p field_type is a @arrayft.
@param[in] field_type Field type to check (can be \c NULL).
-@returns 1 if \p field_type is an array field type,
- or 0 otherwise (including if \p field_type is
+@returns #BT_TRUE if \p field_type is an array field type,
+ or #BT_FALSE otherwise (including if \p field_type is
\c NULL).
@postrefcountsame{field_type}
@sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
field type.
*/
-extern int bt_ctf_field_type_is_array(struct bt_ctf_field_type *field_type);
+extern bt_bool bt_ctf_field_type_is_array(
+ struct bt_ctf_field_type *field_type);
/**
@brief Returns whether or not the @ft \p field_type is a @seqft.
@param[in] field_type Field type to check (can be \c NULL).
-@returns 1 if \p field_type is a sequence field type,
- or 0 otherwise (including if \p field_type is
+@returns #BT_TRUE if \p field_type is a sequence field type,
+ or #BT_FALSE otherwise (including if \p field_type is
\c NULL).
@postrefcountsame{field_type}
@sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
field type.
*/
-extern int bt_ctf_field_type_is_sequence(struct bt_ctf_field_type *field_type);
+extern bt_bool bt_ctf_field_type_is_sequence(
+ struct bt_ctf_field_type *field_type);
/**
@brief Returns whether or not the @ft \p field_type is a @varft.
@param[in] field_type Field type to check (can be \c NULL).
-@returns 1 if \p field_type is a variant field type,
- or 0 otherwise (including if \p field_type is
+@returns #BT_TRUE if \p field_type is a variant field type,
+ or #BT_FALSE otherwise (including if \p field_type is
\c NULL).
@postrefcountsame{field_type}
@sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
field type.
*/
-extern int bt_ctf_field_type_is_variant(struct bt_ctf_field_type *field_type);
+extern bt_bool bt_ctf_field_type_is_variant(
+ struct bt_ctf_field_type *field_type);
/** @} */
/// Native (default) byte order.
BT_CTF_BYTE_ORDER_NATIVE = 0,
+ /**
+ Unspecified byte order; the initial native byte order of a
+ \link ctfirtraceclass CTF IR trace class\endlink.
+ */
+ BT_CTF_BYTE_ORDER_UNSPECIFIED,
+
/// Little-endian.
BT_CTF_BYTE_ORDER_LITTLE_ENDIAN,
integer fields
<td>Specified at creation
<td>bt_ctf_field_type_integer_get_size()
- <td>None: specified at creation (bt_ctf_field_type_integer_create())
+ <td>bt_ctf_field_type_integer_set_size()
</tr>
<tr>
<td><strong>Signedness</strong> of the described integer fields
<td>Unsigned
- <td>bt_ctf_field_type_integer_get_signed()
- <td>bt_ctf_field_type_integer_set_signed()
+ <td>bt_ctf_field_type_integer_is_signed()
+ <td>bt_ctf_field_type_integer_set_is_signed()
</tr>
<tr>
<td><strong>Preferred display base</strong> of the described
/// Unknown, used for errors.
BT_CTF_INTEGER_BASE_UNKNOWN = -1,
+ /// Unspecified by the tracer.
+ BT_CTF_INTEGER_BASE_UNSPECIFIED = 0,
+
/// Binary.
BT_CTF_INTEGER_BASE_BINARY = 2,
@brief Creates a default @intft with \p size bits as the storage size
of the @intfields it describes.
+You can change the storage size of the integer fields described by
+the created integer field type later with
+bt_ctf_field_type_integer_set_size().
+
@param[in] size Storage size (bits) of the described integer fields.
@returns Created integer field type, or \c NULL on error.
@prenotnull{int_field_type}
@preisintft{int_field_type}
@postrefcountsame{int_field_type}
+
+@sa bt_ctf_field_type_integer_set_size(): Sets the storage size of the
+ integer fields described by a given integer field type.
*/
extern int bt_ctf_field_type_integer_get_size(
struct bt_ctf_field_type *int_field_type);
+/**
+@brief Sets the storage size, in bits, of the @intfields described by
+ the @intft \p int_field_type.
+
+@param[in] int_field_type Integer field type which describes the
+ integer fields of which to set the
+ storage size.
+@param[in] size Storage size (bits) of the integer fields
+ described by \p int_field_type.
+@returns 0 on success, or a negative value on error.
+
+@prenotnull{int_field_type}
+@preisintft{int_field_type}
+@prehot{int_field_type}
+@pre \p size is greater than 0 and lesser than or equal to 64.
+@postrefcountsame{int_field_type}
+
+@sa bt_ctf_field_type_integer_get_size(): Returns the storage size of
+ the integer fields described by a given integer field type.
+*/
+extern int bt_ctf_field_type_integer_set_size(
+ struct bt_ctf_field_type *int_field_type, unsigned int size);
+
/**
@brief Returns whether or not the @intfields described by the @intft
\p int_field_type are signed.
@param[in] int_field_type Integer field type which describes the
integer fields of which to get the
signedness.
-@returns 1 if the integer fields described by
- \p int_field_type are signed, 0 if they
- are unsigned, or a negative value on
- error.
+@returns #BT_TRUE if the integer fields described by
+ \p int_field_type are signed, #BT_FALSE if they
+ are unsigned.
@prenotnull{int_field_type}
@preisintft{int_field_type}
@postrefcountsame{int_field_type}
-@sa bt_ctf_field_type_integer_set_signed(): Sets the signedness of the
+@sa bt_ctf_field_type_integer_set_is_signed(): Sets the signedness of the
integer fields described by a given integer field type.
*/
+extern bt_bool bt_ctf_field_type_integer_is_signed(
+ struct bt_ctf_field_type *int_field_type);
+
+/** @cond DOCUMENT */
+
extern int bt_ctf_field_type_integer_get_signed(
struct bt_ctf_field_type *int_field_type);
+/** @endcond */
+
/**
@brief Sets whether or not the @intfields described by
the @intft \p int_field_type are signed.
integer fields of which to set the
signedness.
@param[in] is_signed Signedness of the integer fields
- described by \p int_field_type; 0 means
- \em unsigned, 1 means \em signed.
+ described by \p int_field_type; #BT_FALSE means
+ \em unsigned, #BT_TRUE means \em signed.
@returns 0 on success, or a negative value on error.
@prenotnull{int_field_type}
@preisintft{int_field_type}
@prehot{int_field_type}
-@pre \p is_signed is 0 or 1.
-@postrefcountsame{event_class}
+@postrefcountsame{int_field_type}
-@sa bt_ctf_field_type_integer_get_signed(): Returns the signedness of
+@sa bt_ctf_field_type_integer_is_signed(): Returns the signedness of
the integer fields described by a given integer field type.
*/
-extern int bt_ctf_field_type_integer_set_signed(
- struct bt_ctf_field_type *int_field_type, int is_signed);
+extern int bt_ctf_field_type_integer_set_is_signed(
+ struct bt_ctf_field_type *int_field_type, bt_bool is_signed);
+
+/* Pre-2.0 CTF writer compatibility */
+#define bt_ctf_field_type_integer_set_signed bt_ctf_field_type_integer_set_is_signed
/**
@brief Returns the preferred display base (radix) of the @intfields
preferred display base.
@returns Preferred display base of the integer
fields described by \p int_field_type,
- or #BT_CTF_INTEGER_BASE_UNKNOWN on
- error.
+ #BT_CTF_INTEGER_BASE_UNSPECIFIED if
+ not specified, or
+ #BT_CTF_INTEGER_BASE_UNKNOWN on error.
@prenotnull{int_field_type}
@preisintft{int_field_type}
@prenotnull{int_field_type}
@preisintft{int_field_type}
@prehot{int_field_type}
-@pre \p base is #BT_CTF_INTEGER_BASE_BINARY, #BT_CTF_INTEGER_BASE_OCTAL,
- #BT_CTF_INTEGER_BASE_DECIMAL, or
- #BT_CTF_INTEGER_BASE_HEXADECIMAL.
+@pre \p base is #BT_CTF_INTEGER_BASE_UNSPECIFIED,
+ #BT_CTF_INTEGER_BASE_BINARY, #BT_CTF_INTEGER_BASE_OCTAL,
+ #BT_CTF_INTEGER_BASE_DECIMAL, or #BT_CTF_INTEGER_BASE_HEXADECIMAL.
@postrefcountsame{int_field_type}
@sa bt_ctf_field_type_integer_get_base(): Returns the preferred display
/** @} */
-struct bt_ctf_field_type_enumeration_mapping_iterator *
- bt_ctf_field_type_enumeration_find_mappings_by_name(
- struct bt_ctf_field_type *type,
- const char *name);
-
-struct bt_ctf_field_type_enumeration_mapping_iterator *
- bt_ctf_field_type_enumeration_find_mappings_by_signed_value(
- struct bt_ctf_field_type *type,
- int64_t value);
-
-struct bt_ctf_field_type_enumeration_mapping_iterator *
- bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(
- struct bt_ctf_field_type *type,
- uint64_t value);
-
-int bt_ctf_field_type_enumeration_mapping_iterator_get_name(
- struct bt_ctf_field_type_enumeration_mapping_iterator *iter,
- const char **mapping_name);
-
-int bt_ctf_field_type_enumeration_mapping_iterator_get_signed(
- struct bt_ctf_field_type_enumeration_mapping_iterator *iter,
- const char **mapping_name, int64_t *lower, int64_t *upper);
-
-int bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(
- struct bt_ctf_field_type_enumeration_mapping_iterator *iter,
- const char **mapping_name, uint64_t *lower, uint64_t *upper);
-
-int bt_ctf_field_type_enumeration_mapping_iterator_next(
- struct bt_ctf_field_type_enumeration_mapping_iterator *iter);
-
/**
@defgroup ctfirenumfieldtype CTF IR enumeration field type
@ingroup ctfirfieldtypes
value, both included in the range.
You can add a mapping to an enumeration field type with
-bt_ctf_field_type_enumeration_add_mapping() or
+bt_ctf_field_type_enumeration_add_mapping_signed() or
bt_ctf_field_type_enumeration_add_mapping_unsigned(), depending on the
signedness of the wrapped @intft.
+You can find mappings by name or by value with the following find
+operations:
+
+- bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
+ mappings with a given name.
+- bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value():
+ Finds the mappings which contain a given unsigned value in their
+ range.
+- bt_ctf_field_type_enumeration_find_mappings_by_signed_value():
+ Finds the mappings which contain a given signed value in their range.
+
+Those functions return a @enumftiter on the result set of the find
+operation.
+
Many mappings can share the same name, and the ranges of a given
enumeration field type are allowed to overlap. For example,
this is a valid set of mappings:
Here, the range of the second \c APPLE mapping overlaps the range of
the \c CHERRY mapping.
+@sa ctfirenumftmappingiter
@sa ctfirenumfield
@sa ctfirfieldtypes
@preisenumft{enum_field_type}
@postrefcountsame{enum_field_type}
*/
-extern int bt_ctf_field_type_enumeration_get_mapping_count(
+extern int64_t bt_ctf_field_type_enumeration_get_mapping_count(
struct bt_ctf_field_type *enum_field_type);
/**
@param[in] enum_field_type Enumeration field type of which to get
the mapping at index \p index.
-@param[in] index Index of the mapping to get from
+@param[in] index Index of the mapping to get from
\p enum_field_type.
@param[out] name Returned name of the mapping at index
\p index.
bt_ctf_field_type_enumeration_get_mapping_count()).
@postrefcountsame{enum_field_type}
-@sa bt_ctf_field_type_enumeration_get_mapping_signed(): Returns the
- signed mapping contained by a given enumeration field type
+@sa bt_ctf_field_type_enumeration_get_mapping_unsigned(): Returns the
+ unsigned mapping contained by a given enumeration field type
at a given index.
*/
extern int bt_ctf_field_type_enumeration_get_mapping_signed(
- struct bt_ctf_field_type *enum_field_type, int index,
+ struct bt_ctf_field_type *enum_field_type, uint64_t index,
const char **name, int64_t *range_begin, int64_t *range_end);
/**
@param[in] enum_field_type Enumeration field type of which to get
the mapping at index \p index.
-@param[in] index Index of the mapping to get from
+@param[in] index Index of the mapping to get from
\p enum_field_type.
@param[out] name Returned name of the mapping at index
\p index.
bt_ctf_field_type_enumeration_get_mapping_count()).
@postrefcountsame{enum_field_type}
-@sa bt_ctf_field_type_enumeration_get_mapping_unsigned(): Returns the
- unsigned mapping contained by a given enumeration field type
+@sa bt_ctf_field_type_enumeration_get_mapping_signed(): Returns the
+ signed mapping contained by a given enumeration field type
at a given index.
*/
extern int bt_ctf_field_type_enumeration_get_mapping_unsigned(
- struct bt_ctf_field_type *enum_field_type, int index,
+ struct bt_ctf_field_type *enum_field_type, uint64_t index,
const char **name, uint64_t *range_begin,
uint64_t *range_end);
+/**
+@brief Finds the mappings of the @enumft \p enum_field_type which
+ are named \p name.
+
+This function returns an iterator on the result set of this find
+operation. See \ref ctfirenumftmappingiter for more details.
+
+@param[in] enum_field_type Enumeration field type of which to find
+ the mappings named \p name.
+@param[in] name Name of the mappings to find in
+ \p enum_field_type.
+@returns @enumftiter on the set of mappings named
+ \p name in \p enum_field_type, or
+ \c NULL if no mappings were found or
+ on error.
+
+@prenotnull{enum_field_type}
+@prenotnull{name}
+@preisenumft{enum_field_type}
+@postrefcountsame{enum_field_type}
+@postsuccessrefcountret1
+@post <strong>On success</strong>, the returned @enumftiter can iterate
+ on at least one mapping.
+
+@sa bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): Finds
+ the mappings of a given enumeration field type which contain
+ a given signed value in their range.
+@sa bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): Finds
+ the mappings of a given enumeration field type which contain
+ a given unsigned value in their range.
+*/
+extern struct bt_ctf_field_type_enumeration_mapping_iterator *
+bt_ctf_field_type_enumeration_find_mappings_by_name(
+ struct bt_ctf_field_type *enum_field_type,
+ const char *name);
+
+/**
+@brief Finds the mappings of the @enumft \p enum_field_type which
+ contain the signed value \p value in their range.
+
+This function returns an iterator on the result set of this find
+operation. See \ref ctfirenumftmappingiter for more details.
+
+@param[in] enum_field_type Enumeration field type of which to find
+ the mappings which contain \p value.
+@param[in] value Value to find in the ranges of the
+ mappings of \p enum_field_type.
+@returns @enumftiter on the set of mappings of
+ \p enum_field_type which contain
+ \p value in their range, or \c NULL if
+ no mappings were found or on error.
+
+@prenotnull{enum_field_type}
+@preisenumft{enum_field_type}
+@postrefcountsame{enum_field_type}
+@postsuccessrefcountret1
+@post <strong>On success</strong>, the returned @enumftiter can iterate
+ on at least one mapping.
+
+@sa bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
+ mappings of a given enumeration field type which have a given
+ name.
+@sa bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): Finds
+ the mappings of a given enumeration field type which contain
+ a given unsigned value in their range.
+*/
+extern struct bt_ctf_field_type_enumeration_mapping_iterator *
+bt_ctf_field_type_enumeration_find_mappings_by_signed_value(
+ struct bt_ctf_field_type *enum_field_type,
+ int64_t value);
+
+/**
+@brief Finds the mappings of the @enumft \p enum_field_type which
+ contain the unsigned value \p value in their range.
+
+This function returns an iterator on the result set of this find
+operation. See \ref ctfirenumftmappingiter for more details.
+
+@param[in] enum_field_type Enumeration field type of which to find
+ the mappings which contain \p value.
+@param[in] value Value to find in the ranges of the
+ mappings of \p enum_field_type.
+@returns @enumftiter on the set of mappings of
+ \p enum_field_type which contain
+ \p value in their range, or \c NULL
+ if no mappings were found or
+ on error.
+
+@prenotnull{enum_field_type}
+@preisenumft{enum_field_type}
+@postrefcountsame{enum_field_type}
+@postsuccessrefcountret1
+@post <strong>On success</strong>, the returned @enumftiter can iterate
+ on at least one mapping.
+
+@sa bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
+ mappings of a given enumeration field type which have a given
+ name.
+@sa bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): Finds
+ the mappings of a given enumeration field type which contain
+ a given unsigned value in their range.
+*/
+extern struct bt_ctf_field_type_enumeration_mapping_iterator *
+bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(
+ struct bt_ctf_field_type *enum_field_type,
+ uint64_t value);
+
/**
@brief Adds a mapping to the @enumft \p enum_field_type which maps the
name \p name to the signed range \p range_begin (included) to
@prenotnull{enum_field_type}
@prenotnull{name}
+@prehot{enum_field_type}
@preisenumft{enum_field_type}
@pre The wrapped @intft of \p enum_field_type is signed.
@pre \p range_end is greater than or equal to \p range_begin.
@sa bt_ctf_field_type_enumeration_add_mapping_unsigned(): Adds an
unsigned mapping to a given enumeration field type.
*/
-extern int bt_ctf_field_type_enumeration_add_mapping(
+extern int bt_ctf_field_type_enumeration_add_mapping_signed(
struct bt_ctf_field_type *enum_field_type, const char *name,
int64_t range_begin, int64_t range_end);
+/* Pre-2.0 CTF writer compatibility */
+#define bt_ctf_field_type_enumeration_add_mapping bt_ctf_field_type_enumeration_add_mapping_signed
+
/**
@brief Adds a mapping to the @enumft \p enum_field_type which maps
the name \p name to the unsigned
@prenotnull{enum_field_type}
@prenotnull{name}
+@prehot{enum_field_type}
@preisenumft{enum_field_type}
@pre The wrapped @intft of \p enum_field_type is unsigned.
@pre \p range_end is greater than or equal to \p range_begin.
@postrefcountsame{enum_field_type}
-@sa bt_ctf_field_type_enumeration_add_mapping(): Adds a signed
+@sa bt_ctf_field_type_enumeration_add_mapping_signed(): Adds a signed
mapping to a given enumeration field type.
*/
extern int bt_ctf_field_type_enumeration_add_mapping_unsigned(
/** @} */
+/**
+@defgroup ctfirenumftmappingiter CTF IR enumeration field type mapping iterator
+@ingroup ctfirenumfieldtype
+@brief CTF IR enumeration field type mapping iterator.
+
+@code
+#include <babeltrace/ctf-ir/field-types.h>
+@endcode
+
+A CTF IR <strong><em>enumeration field type mapping
+iterator</em></strong> is an iterator on @enumft mappings.
+
+You can get an enumeration mapping iterator from one of the following
+functions:
+
+- Find operations of an @enumft object:
+ - bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
+ mappings with a given name.
+ - bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value():
+ Finds the mappings which contain a given unsigned value in their
+ range.
+ - bt_ctf_field_type_enumeration_find_mappings_by_signed_value():
+ Finds the mappings which contain a given signed value in their range.
+- bt_ctf_field_enumeration_get_mappings(): Finds the mappings in the
+ @enumft of an @enumfield containing its current integral value in
+ their range.
+
+Those functions guarantee that the returned iterator can iterate on
+at least one mapping. Otherwise, they return \c NULL.
+
+You can get the name and the range of a mapping iterator's current
+mapping with
+bt_ctf_field_type_enumeration_mapping_iterator_get_signed()
+or
+bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(),
+depending on the signedness of the @intft wrapped by the
+@enumft. If you only need the name of the current mapping, you can
+use any of the two functions and set the \p range_begin and \p range_end
+parameters to \c NULL.
+
+You can advance an enumeration field type mapping iterator to the next
+mapping with
+bt_ctf_field_type_enumeration_mapping_iterator_next(). This
+function returns a negative value when you reach the end of the
+result set.
+
+As with any Babeltrace object, CTF IR enumeration field type mapping
+iterator objects have <a
+href="https://en.wikipedia.org/wiki/Reference_counting">reference
+counts</a>. See \ref refs to learn more about the reference counting
+management of Babeltrace objects.
+
+@sa ctfirenumfieldtype
+
+@addtogroup ctfirenumftmappingiter
+@{
+*/
+
+/**
+@struct bt_ctf_field_type_enumeration_mapping_iterator
+@brief A CTF IR enumeration field type mapping iterator.
+@sa ctfirenumftmappingiter
+*/
+
+/**
+@brief Returns the name and the range of the current (signed) mapping
+ of the @enumftiter \p iter.
+
+If one of \p range_begin or \p range_end is not \c NULL, the @intft
+wrapped by the @enumft from which \p iter was obtained, as returned by
+bt_ctf_field_type_enumeration_get_container_type(), must be
+\b signed to use this function. Otherwise, if you only need to get the
+name of the current mapping, set \p range_begin and \p range_end to
+\c NULL.
+
+On success, if \p name is not \c NULL, \p *name remains valid as long
+as \p iter exists and
+bt_ctf_field_type_enumeration_mapping_iterator_next() is
+\em not called on \p iter.
+
+@param[in] iter Enumeration field type mapping iterator
+ of which to get the range of the current
+ mapping.
+@param[out] name Returned name of the current mapping of
+ \p iter (can be \c NULL to ignore).
+@param[out] range_begin Returned beginning of the range
+ (included) of the current mapping of
+ \p iter (can be \c NULL to ignore).
+@param[out] range_end Returned end of the range
+ (included) of the current mapping of
+ \p iter (can be \c NULL to ignore).
+@returns 0 on success, or a negative value on error.
+
+@prenotnull{iter}
+@postrefcountsame{iter}
+
+@sa bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned():
+ Returns the name and the unsigned range of the current mapping
+ of a given enumeration field type mapping iterator.
+*/
+extern int bt_ctf_field_type_enumeration_mapping_iterator_get_signed(
+ struct bt_ctf_field_type_enumeration_mapping_iterator *iter,
+ const char **name, int64_t *range_begin, int64_t *range_end);
+
+/**
+@brief Returns the name and the range of the current (unsigned) mapping
+ of the @enumftiter \p iter.
+
+If one of \p range_begin or \p range_end is not \c NULL, the @intft
+wrapped by the @enumft from which \p iter was obtained, as returned by
+bt_ctf_field_type_enumeration_get_container_type(), must be
+\b unsigned to use this function. Otherwise, if you only need to get the
+name of the current mapping, set \p range_begin and \p range_end to
+\c NULL.
+
+On success, if \p name is not \c NULL, \p *name remains valid as long
+as \p iter exists and
+bt_ctf_field_type_enumeration_mapping_iterator_next() is
+\em not called on \p iter.
+
+@param[in] iter Enumeration field type mapping iterator
+ of which to get the range of the current
+ mapping.
+@param[out] name Returned name of the current mapping of
+ \p iter (can be \c NULL to ignore).
+@param[out] range_begin Returned beginning of the range
+ (included) of the current mapping of
+ \p iter (can be \c NULL to ignore).
+@param[out] range_end Returned end of the range
+ (included) of the current mapping of
+ \p iter (can be \c NULL to ignore).
+@returns 0 on success, or a negative value on error.
+
+@prenotnull{iter}
+@postrefcountsame{iter}
+
+@sa
+ bt_ctf_field_type_enumeration_mapping_iterator_get_signed():
+ Returns the name and the signed range of the current mapping of
+ a given enumeration field type mapping iterator.
+*/
+extern int bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(
+ struct bt_ctf_field_type_enumeration_mapping_iterator *iter,
+ const char **name, uint64_t *range_begin, uint64_t *range_end);
+
+/**
+@brief Advances the @enumftiter \p iter to the next mapping.
+
+@param[in] iter Enumeration field type mapping iterator to
+ advance.
+@returns 0 on success, or a negative value on error or
+ when you reach the end of the set.
+
+@prenotnull{iter}
+@postrefcountsame{iter}
+*/
+extern int bt_ctf_field_type_enumeration_mapping_iterator_next(
+ struct bt_ctf_field_type_enumeration_mapping_iterator *iter);
+
+/** @} */
+
/**
@defgroup ctfirstringfieldtype CTF IR string field type
@ingroup ctfirfieldtypes
@preisstructft{struct_field_type}
@postrefcountsame{struct_field_type}
*/
-extern int bt_ctf_field_type_structure_get_field_count(
+extern int64_t bt_ctf_field_type_structure_get_field_count(
struct bt_ctf_field_type *struct_field_type);
/**
@sa bt_ctf_field_type_structure_get_field_type_by_name(): Finds a
structure field type's field by name.
*/
-extern int bt_ctf_field_type_structure_get_field(
+extern int bt_ctf_field_type_structure_get_field_by_index(
struct bt_ctf_field_type *struct_field_type,
const char **field_name, struct bt_ctf_field_type **field_type,
- int index);
+ uint64_t index);
+
+/* Pre-2.0 CTF writer compatibility */
+#define bt_ctf_field_type_structure_get_field bt_ctf_field_type_structure_get_field_by_index
/**
@brief Returns the type of the field named \p field_name found in
@postrefcountsame{struct_field_type}
@postsuccessrefcountretinc
-@sa bt_ctf_field_type_structure_get_field(): Finds a
+@sa bt_ctf_field_type_structure_get_field_by_index(): Finds a
structure field type's field by index.
*/
extern
@preisvarft{variant_field_type}
@postrefcountsame{variant_field_type}
*/
-extern int bt_ctf_field_type_variant_get_field_count(
+extern int64_t bt_ctf_field_type_variant_get_field_count(
struct bt_ctf_field_type *variant_field_type);
/**
@sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant
field type's field by current tag value.
*/
-extern int bt_ctf_field_type_variant_get_field(
+extern int bt_ctf_field_type_variant_get_field_by_index(
struct bt_ctf_field_type *variant_field_type,
const char **field_name,
- struct bt_ctf_field_type **field_type, int index);
+ struct bt_ctf_field_type **field_type, uint64_t index);
+
+/* Pre-2.0 CTF writer compatibility */
+#define bt_ctf_field_type_variant_get_field bt_ctf_field_type_variant_get_field_by_index
/**
@brief Returns the type of the field (choice) named \p field_name
@postrefcountsame{variant_field_type}
@postsuccessrefcountretinc
-@sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's
+@sa bt_ctf_field_type_variant_get_field_by_index(): Finds a variant field type's
field by index.
@sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant
field type's field by current tag value.
@postrefcountsame{tag_field}
@postsuccessrefcountretinc
-@sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's
+@sa bt_ctf_field_type_variant_get_field_by_index(): Finds a variant field type's
field by index.
@sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant
field type's field by name.
projects / babeltrace.git / blobdiff