* http://www.efficios.com/ctf
*/
+/* For bt_bool */
+#include <babeltrace/types.h>
+
#include <stdint.h>
+#include <stddef.h>
#ifdef __cplusplus
extern "C" {
@endcode
A CTF IR <strong><em>field type</em></strong> is a field type that you
-can use to create concrete \link ctfirfields CTF IR fields\endlink.
+can use to create concrete @fields.
-You can create a CTF IR field object from a CTF IR field type object
+You can create a @field object from a CTF IR field type object
with bt_ctf_field_create().
In the CTF IR hierarchy, you can set the root field types of three
- Event payload field type: bt_ctf_event_class_set_payload_type().
As of Babeltrace \btversion, those six previous "root" field types
-\em must be structure field types.
+\em must be @structft objects.
-If, at any level within a given root field type, you add a sequence or a
-variant field type, you do not need to specify its associated length
+If, at any level within a given root field type, you add a @seqft or a
+@varft, you do not need to specify its associated length
or tag field type: the length or tag string is enough for the Babeltrace
-system to resolve the appropriate field type depending on where this
+system to resolve the needed field type depending on where this
dynamic field type is located within the whole hierarchy. It is
guaranteed that this automatic resolving is performed for all the field
types contained in a given
<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().
- bt_ctf_event_create() freezes the root field types of its event class
parameter and of ther parent stream class of this event class.
+You cannot modify a frozen field type object: it is considered
+immutable, except for \link refs reference counting\endlink.
+
@sa ctfirfields
+@sa \ref ctfirfieldtypesexamples "Examples"
@file
-@brief CTF IR field type type and functions.
+@brief CTF IR field types type and functions.
@sa ctfirfieldtypes
@addtogroup ctfirfieldtypes
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 CTF IR field type.
+@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,
};
/**
-@brief Returns the type ID of the CTF IR field type \p field_type.
+@brief Returns the type ID of the @ft \p field_type.
@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 an integer field type.
+ field type is a @intft.
@sa bt_ctf_field_type_is_floating_point(): Returns whether or not a
- given field type is a floating point number field type.
+ given field type is a @floatft.
@sa bt_ctf_field_type_is_enumeration(): Returns whether or not a given
- field type is an enumeration field type.
+ field type is a @enumft.
@sa bt_ctf_field_type_is_string(): Returns whether or not a given
- field type is a string field type.
+ field type is a @stringft.
@sa bt_ctf_field_type_is_structure(): Returns whether or not a given
- field type is a structure field type.
+ field type is a @structft.
@sa bt_ctf_field_type_is_array(): Returns whether or not a given
- field type is an array field type.
+ field type is a @arrayft.
@sa bt_ctf_field_type_is_sequence(): Returns whether or not a given
- field type is a sequence field type.
+ field type is a @seqft.
@sa bt_ctf_field_type_is_variant(): Returns whether or not a given
- field type is a variant field type.
+ 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 CTF IR field type \p field_type is
- an integer 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 CTF IR field type \p field_type is
- a floating point number 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 CTF IR field type \p field_type is
- an enumeration 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 CTF IR field type \p field_type is
- a string 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 CTF IR field type \p field_type is
- a structure 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 CTF IR field type \p field_type is
- an array 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 CTF IR field type \p field_type is
- a sequence 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 CTF IR field type \p field_type is
- a variant 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);
/** @} */
/**
@brief <a href="https://en.wikipedia.org/wiki/Endianness">Byte order</a>
- of a CTF IR field type.
+ of a @ft.
*/
enum bt_ctf_byte_order {
/// Unknown, used for errors.
/// 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,
};
/**
-@brief String encoding of a CTF IR field type.
+@brief String encoding of a @ft.
*/
enum bt_ctf_string_encoding {
/// Unknown, used for errors.
};
/**
-@brief Returns the alignment of the CTF IR fields described by
- the CTF IR field type \p field_type.
+@brief Returns the alignment of the @fields described by
+ the @ft \p field_type.
@param[in] field_type Field type which describes the
fields of which to get the alignment.
struct bt_ctf_field_type *field_type);
/**
-@brief Sets the alignment of the CTF IR fields described by the
- CTF IR field type \p field_type to \p alignment.
+@brief Sets the alignment of the @fields described by the
+ @ft \p field_type to \p alignment.
\p alignment \em must be greater than 0 and a power of two.
unsigned int alignment);
/**
-@brief Returns the byte order of the CTF IR fields described by
- the CTF IR field type \p field_type.
+@brief Returns the byte order of the @fields described by
+ the @ft \p field_type.
-You can only call this function if \p field_type is a
-\link ctfirintfieldtype CTF IR integer field type\endlink,
-a \link ctfirfloatfieldtype CTF IR floating point number field type\endlink,
-or a \link ctfirenumfieldtype CTF IR enumeration field type\endlink.
+You can only call this function if \p field_type is a @intft, a
+@floatft, or a @enumft.
@param[in] field_type Field type which describes the
fields of which to get the byte order.
error.
@prenotnull{field_type}
-@pre \p field_type is an integer field type, a floating point number
- field type, or an enumeration field type.
+@pre \p field_type is a @intft, a @floatft, or a @enumft.
@postrefcountsame{field_type}
@sa bt_ctf_field_type_set_byte_order(): Sets the byte order
struct bt_ctf_field_type *field_type);
/**
-@brief Sets the byte order of the CTF IR fields described by the
- CTF IR field type \p field_type to \p byte_order.
+@brief Sets the byte order of the @fields described by the
+ @ft \p field_type to \p byte_order.
If \p field_type is a compound field type, this function also
recursively sets the byte order of its children to \p byte_order.
@pre \p byte_order is #BT_CTF_BYTE_ORDER_NATIVE,
#BT_CTF_BYTE_ORDER_LITTLE_ENDIAN, #BT_CTF_BYTE_ORDER_BIG_ENDIAN,
or #BT_CTF_BYTE_ORDER_NETWORK.
-@postrefcountsame{field_type}F
+@postrefcountsame{field_type}
@sa bt_ctf_field_type_get_byte_order(): Returns the byte order of the
fields described by a given field type.
*/
/**
-@brief Returns whether or not the CTF IR field type \p field_type_a
+@brief Returns whether or not the @ft \p field_type_a
is equivalent to the field type \p field_type_b.
You \em must use this function to compare two field types: it is not
struct bt_ctf_field_type *field_type_b);
/**
-@brief Creates a \em deep copy of the CTF IR field type \p field_type.
+@brief Creates a \em deep copy of the @ft \p field_type.
You can copy a frozen field type: the resulting copy is
<em>not frozen</em>.
-This function resets the tag field type of the copied
-\link ctfirvarfieldtype CTF IR variant field types\endlink. The
+This function resets the tag field type of a copied @varft. The
automatic field resolving which some functions of the API perform
can set it again when the returned field type is used (learn more
in the detailed description of this module).
@prenotnull{field_type}
@postrefcountsame{field_type}
@postsuccessrefcountret1
+@post <strong>On success</strong>, the returned field type is not frozen.
*/
extern struct bt_ctf_field_type *bt_ctf_field_type_copy(
struct bt_ctf_field_type *field_type);
@endcode
A CTF IR <strong><em>integer field type</em></strong> is a field type that
-you can use to create concrete
-\link ctfirintfield CTF IR integer fields\endlink.
+you can use to create concrete @intfield objects.
You can create an integer field type
with bt_ctf_field_type_integer_create().
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
<td><strong>Mapped
\link ctfirclockclass CTF IR clock class\endlink</strong>
<td>None
- <td>bt_ctf_field_type_integer_get_mapped_clock()
- <td>bt_ctf_field_type_integer_set_mapped_clock()
+ <td>bt_ctf_field_type_integer_get_mapped_clock_class()
+ <td>bt_ctf_field_type_integer_set_mapped_clock_class()
</tr>
</table>
@sa ctfirintfield
@sa ctfirfieldtypes
+@sa \ref ctfirfieldtypesexamples_intfieldtype "Examples"
@addtogroup ctfirintfieldtype
@{
*/
/**
-@brief Preferred display base (radix) of a
- \link ctfirintfieldtype CTF IR integer field type\endlink.
+@brief Preferred display base (radix) of a @intft.
*/
enum bt_ctf_integer_base {
/// 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 CTF IR integer field type with \p size bits
- as the storage size of the CTF IR integer fields it describes.
+@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.
unsigned int size);
/**
-@brief Returns the storage size, in bits, of the CTF IR integer fields
- described by the CTF IR integer field type \p int_field_type.
+@brief Returns 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 get the
@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 Returns whether or not the CTF IR integer fields
- described by the CTF IR integer field type \p int_field_type
- are signed.
+@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 CTF IR integer fields described by
- the CTF IR integer field type \p int_field_type are signed.
+@brief Sets 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 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 CTF IR integer
- fields described by the CTF IR integer field type
- \p int_field_type.
+@brief Returns the preferred display base (radix) 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 get the
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}
struct bt_ctf_field_type *int_field_type);
/**
-@brief Sets the preferred display base (radix) of the CTF IR integer
- fields described by the CTF IR integer field type
- \p int_field_type to \p base.
+@brief Sets the preferred display base (radix) of the @intfields
+ described by the @intft \p int_field_type to \p base.
@param[in] int_field_type Integer field type which describes the
integer fields of which to set the
@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
enum bt_ctf_integer_base base);
/**
-@brief Returns the encoding of the CTF IR integer fields described by
- the CTF IR integer field type \p int_field_type.
+@brief Returns the encoding 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 get the
struct bt_ctf_field_type *int_field_type);
/**
-@brief Sets the encoding of the CTF IR integer fields
- described by the CTF IR integer field type \p int_field_type
- to \p encoding.
+@brief Sets the encoding of the @intfields described by the @intft
+ \p int_field_type to \p encoding.
-You can use this property, in CTF IR, to create "text" array or sequence
-field types. A text array field type is an
-\link ctfirarrayfieldtype array field type\endlink with an unsigned,
+You can use this property, in CTF IR, to create "text" @arrayfts or
+@seqfts. A text array field type is array field type with an unsigned,
8-bit integer field type having an encoding as its element field type.
@param[in] int_field_type Integer field type which describes the
enum bt_ctf_string_encoding encoding);
/**
-@brief Returns the CTF IR clock class mapped to the CTF IR integer
- field type \p int_field_type.
+@brief Returns the \link ctfirclockclass CTF IR clock class\endlink
+ mapped to the @intft \p int_field_type.
The mapped clock class, if any, indicates the class of the clock which
-an integer field described by \p int_field_type should sample or update.
+an @intfield described by \p int_field_type should sample or update.
This mapped clock class is only indicative.
@param[in] int_field_type Integer field type of which to get the
@postrefcountsame{int_field_type}
@postsuccessrefcountretinc
-@sa bt_ctf_field_type_integer_set_mapped_clock(): Sets the mapped
+@sa bt_ctf_field_type_integer_set_mapped_clock_class(): Sets the mapped
clock class of a given integer field type.
*/
-extern struct bt_ctf_clock *bt_ctf_field_type_integer_get_mapped_clock(
+extern struct bt_ctf_clock_class *bt_ctf_field_type_integer_get_mapped_clock_class(
struct bt_ctf_field_type *int_field_type);
/**
-@brief Sets the CTF IR clock class mapped to the CTF IR integer field
- type \p int_field_type to \p mapped_clock.
+@brief Sets the \link ctfirclockclass CTF IR clock class\endlink mapped
+ to the @intft \p int_field_type to \p clock_class.
The mapped clock class, if any, indicates the class of the clock which
an integer field described by \p int_field_type should sample or update.
@postrefcountsame{int_field_type}
@postsuccessrefcountinc{clock_class}
-@sa bt_ctf_field_type_integer_get_mapped_clock(): Returns the mapped
+@sa bt_ctf_field_type_integer_get_mapped_clock_class(): Returns the mapped
clock class of a given integer field type.
*/
-extern int bt_ctf_field_type_integer_set_mapped_clock(
+extern int bt_ctf_field_type_integer_set_mapped_clock_class(
struct bt_ctf_field_type *int_field_type,
- struct bt_ctf_clock *clock_class);
+ struct bt_ctf_clock_class *clock_class);
/** @} */
@endcode
A CTF IR <strong><em>floating point number field type</em></strong> is
-a field type that you can use to create concrete
-\link ctfirfloatfield CTF IR floating point number fields\endlink.
+a field type that you can use to create concrete @floatfields.
You can create a floating point number field type
with bt_ctf_field_type_floating_point_create().
@sa ctfirfloatfield
@sa ctfirfieldtypes
+@sa \ref ctfirfieldtypesexamples_floatfieldtype "Examples"
@addtogroup ctfirfloatfieldtype
@{
*/
/**
-@brief Creates a default CTF IR floating point number field type.
+@brief Creates a default @floatft.
@returns Created floating point number field type,
or \c NULL on error.
extern struct bt_ctf_field_type *bt_ctf_field_type_floating_point_create(void);
/**
-@brief Returns the exponent storage size of the CTF IR floating point
- number fields described by the CTF IR floating point number
- field type \p float_field_type.
+@brief Returns the exponent storage size of the @floatfields
+ described by the @floatft \p float_field_type.
@param[in] float_field_type Floating point number field type which
describes the floating point number
struct bt_ctf_field_type *float_field_type);
/**
-@brief Sets the exponent storage size of the CTF IR floating point
- number fields described by the CTF IR floating point number
- field type \p float_field_type to \p exponent_size.
+@brief Sets the exponent storage size of the @floatfields described by
+ the @floatft \p float_field_type to \p exponent_size.
As of Babeltrace \btversion, \p exponent_size can only be 8 or 11.
unsigned int exponent_size);
/**
-@brief Returns the mantissa and sign storage size of the CTF IR
- floating point number fields described by the CTF IR floating
- point number field type \p float_field_type.
+@brief Returns the mantissa and sign storage size of the @floatfields
+ described by the @floatft \p float_field_type.
On success, the returned value is the sum of the mantissa \em and
sign storage sizes.
struct bt_ctf_field_type *float_field_type);
/**
-@brief Sets the mantissa and sign storage size of the CTF IR floating
- point number fields described by the CTF IR floating point
- number field type \p float_field_type to \p mantissa_sign_size.
+@brief Sets the mantissa and sign storage size of the @floatfields
+ described by the @floatft \p float_field_type to \p
+ mantissa_sign_size.
As of Babeltrace \btversion, \p mantissa_sign_size can only be 24 or 53.
@endcode
A CTF IR <strong><em>enumeration field type</em></strong> is
-a field type that you can use to create concrete
-\link ctfirenumfield CTF IR enumeration fields\endlink.
+a field type that you can use to create concrete @enumfields.
-You can create an enumeration field type
-with bt_ctf_field_type_enumeration_create(). This function needs
-a \link ctfirintfieldtype CTF IR integer field type\endlink which
-represents the storage field type of the created enumeration field type.
-In other words, an enumeration field type wraps an integer field type
-and adds label-value mappings to it.
+You can create an enumeration field type with
+bt_ctf_field_type_enumeration_create(). This function needs a @intft
+which represents the storage field type of the created enumeration field
+type. In other words, an enumeration field type wraps an integer field
+type and adds label-value mappings to it.
An enumeration mapping has:
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 integer field type.
+signedness of the wrapped @intft.
+
+You can find mappings by name or by value with the following find
+operations:
-Many mappings can share the same name, but the ranges of a given
-enumeration field type <strong>must not overlap</strong>. For example,
+- 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:
@verbatim
APPLE -> [ 55, 55]
@endverbatim
-The following set of mappings is \em not valid, however:
+The following set of mappings is also valid:
@verbatim
APPLE -> [ 3, 19]
Here, the range of the second \c APPLE mapping overlaps the range of
the \c CHERRY mapping.
+@sa ctfirenumftmappingiter
@sa ctfirenumfield
@sa ctfirfieldtypes
*/
/**
-@brief Creates a default CTF IR enumeration field type wrapping the
- \link ctfirintfieldtype CTF IR integer field type\endlink
- \p int_field_type.
+@brief Creates a default @enumft wrapping the @intft \p int_field_type.
@param[in] int_field_type Integer field type wrapped by the
created enumeration field type.
struct bt_ctf_field_type *int_field_type);
/**
-@brief Returns the
- \link ctfirintfieldtype CTF IR integer field type\endlink
- wrapped by the CTF IR enumeration field type \p enum_field_type.
+@brief Returns the @intft wrapped by the @enumft \p enum_field_type.
@param[in] enum_field_type Enumeration field type of which to get
the wrapped integer field type.
struct bt_ctf_field_type *enum_field_type);
/**
-@brief Returns the number of mappings contained in the
- CTF IR enumeration field type \p enum_field_type.
+@brief Returns the number of mappings contained in the
+ @enumft \p enum_field_type.
@param[in] enum_field_type Enumeration field type of which to get
the number of contained mappings.
@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);
/**
-@brief Returns the signed mapping of the CTF IR enumeration field type
+@brief Returns the signed mapping of the @enumft
\p enum_field_type at index \p index.
-The \link ctfirintfieldtype CTF IR integer field type\endlink wrapped by
-\p enum_field_type, as returned by
-bt_ctf_field_type_enumeration_get_container_type(), must be
-\b signed to use this function.
+The @intft wrapped by \p enum_field_type, as returned by
+bt_ctf_field_type_enumeration_get_container_type(), must be \b signed
+to use this function.
On success, \p enum_field_type remains the sole owner of \p *name.
@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.
@prenotnull{range_begin}
@prenotnull{range_end}
@preisenumft{enum_field_type}
-@pre The wrapped integer field type of \p enum_field_type is signed.
+@pre The wrapped @intft of \p enum_field_type is signed.
@pre \p index is lesser than the number of mappings contained in the
enumeration field type \p enum_field_type (see
bt_ctf_field_type_enumeration_get_mapping_count()).
unsigned mapping contained by a given enumeration field type
at a given index.
*/
-extern int bt_ctf_field_type_enumeration_get_mapping(
- struct bt_ctf_field_type *enum_field_type, int index,
+extern int bt_ctf_field_type_enumeration_get_mapping_signed(
+ struct bt_ctf_field_type *enum_field_type, uint64_t index,
const char **name, int64_t *range_begin, int64_t *range_end);
/**
-@brief Returns the unsigned mapping of the CTF IR enumeration field
- type \p enum_field_type at index \p index.
+@brief Returns the unsigned mapping of the @enumft
+ \p enum_field_type at index \p index.
-The \link ctfirintfieldtype CTF IR integer field type\endlink wrapped by
-\p enum_field_type, as returned by
+The @intft wrapped by \p enum_field_type, as returned by
bt_ctf_field_type_enumeration_get_container_type(), must be
\b unsigned to use this function.
@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.
@prenotnull{range_begin}
@prenotnull{range_end}
@preisenumft{enum_field_type}
-@pre The wrapped integer field type of \p enum_field_type is unsigned.
+@pre The wrapped @intft of \p enum_field_type is unsigned.
@pre \p index is lesser than the number of mappings contained in the
enumeration field type \p enum_field_type (see
bt_ctf_field_type_enumeration_get_mapping_count()).
@postrefcountsame{enum_field_type}
-@sa bt_ctf_field_type_enumeration_get_mapping(): Returns the
+@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);
-/** @cond DOCUMENT */
-/*
- * TODO: Document once we know what to do with this function (return
- * the first match?).
- */
-extern int bt_ctf_field_type_enumeration_get_mapping_index_by_name(
- struct bt_ctf_field_type *enum_field_type, const char *name);
-/** @endcond */
-
/**
-@brief Returns the index of the signed mapping of the CTF IR
- enumeration field type \p field_type which contains the
- value \p value.
+@brief Finds the mappings of the @enumft \p enum_field_type which
+ are named \p name.
-The \link ctfirintfieldtype CTF IR integer field type\endlink wrapped by
-\p enum_field_type, as returned by
-bt_ctf_field_type_enumeration_get_container_type(), must be
-\b signed to use this function.
+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 get
- the index of the mapping which contains
- \p value.
-@param[in] value Value of the mapping to find.
-@returns Index of the mapping of
- \p enum_field_type which contains
- \p value, or a negative value if the
- function cannot find such a mapping or
+@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}
-@pre The wrapped integer field type of \p enum_field_type is signed.
@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_get_mapping_index_by_unsigned_value():
- Finds the index of an unsigned mapping of a given enumeration
- field type by value.
+@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 int bt_ctf_field_type_enumeration_get_mapping_index_by_value(
- struct bt_ctf_field_type *enum_field_type, int64_t value);
+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 Returns the index of the unsigned mapping of the CTF IR
- enumeration field type \p field_type which contains the
- value \p value.
+@brief Finds the mappings of the @enumft \p enum_field_type which
+ contain the signed value \p value in their range.
-The \link ctfirintfieldtype CTF IR integer field type\endlink wrapped by
-\p enum_field_type, as returned by
-bt_ctf_field_type_enumeration_get_container_type(), must be
-\b unsigned to use this function.
+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 get
- the index of the mapping which contains
- \p value.
-@param[in] value Value of the mapping to find.
-@returns Index of the mapping of
- \p enum_field_type which contains
- \p value, or a negative value if the
- function cannot find such a mapping or
+@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}
-@pre The wrapped integer field type of \p enum_field_type is unsigned.
@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_get_mapping_index_by_unsigned_value():
- Finds the index of a signed mapping of a given enumeration
- field type by value.
+@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 int bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value(
- struct bt_ctf_field_type *enum_field_type, uint64_t value);
+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 CTF IR enumeration field type
- \p enum_field_type which maps the name \p name to the signed
- range \p range_begin (included) to \p range_end (included).
+@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
+ \p range_end (included).
Make \p range_begin and \p range_end the same value to add a mapping
to a single value.
-The \link ctfirintfieldtype CTF IR integer field type\endlink wrapped by
-\p enum_field_type, as returned by
+The @intft wrapped by \p enum_field_type, as returned by
bt_ctf_field_type_enumeration_get_container_type(), must be
\b signed to use this function.
-A mapping in \p enum_field_type can exist with the name \p name, but
-there must be no overlap amongst all the ranges of
-\p enum_field_type.
+A mapping in \p enum_field_type can exist with the name \p name.
@param[in] enum_field_type Enumeration field type to which to add
a mapping.
@prenotnull{enum_field_type}
@prenotnull{name}
+@prehot{enum_field_type}
@preisenumft{enum_field_type}
-@pre The wrapped integer field type of \p enum_field_type is signed.
+@pre The wrapped @intft of \p enum_field_type is signed.
@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_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 CTF IR enumeration field type
- \p enum_field_type which maps the name \p name to the unsigned
+@brief Adds a mapping to the @enumft \p enum_field_type which maps
+ the name \p name to the unsigned
range \p range_begin (included) to \p range_end (included).
Make \p range_begin and \p range_end the same value to add a mapping
to a single value.
-The \link ctfirintfieldtype CTF IR integer field type\endlink wrapped by
-\p enum_field_type, as returned by
+The @intft wrapped by \p enum_field_type, as returned by
bt_ctf_field_type_enumeration_get_container_type(), must be
\b unsigned to use this function.
-A mapping in \p enum_field_type can exist with the name \p name, but
-there must be no overlap amongst all the ranges of
-\p enum_field_type.
+A mapping in \p enum_field_type can exist with the name \p name.
@param[in] enum_field_type Enumeration field type to which to add
a mapping.
@prenotnull{enum_field_type}
@prenotnull{name}
+@prehot{enum_field_type}
@preisenumft{enum_field_type}
-@pre The wrapped integer field type of \p enum_field_type is unsigned.
+@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
@endcode
A CTF IR <strong><em>string field type</em></strong> is a field type that
-you can use to create concrete
-\link ctfirstringfield CTF IR string fields\endlink.
+you can use to create concrete @stringfields.
You can create a string field type
with bt_ctf_field_type_string_create().
A string field type has only one property: the \b encoding of its
-described string fields. By default, the encoding of the string fields
+described @stringfields. By default, the encoding of the string fields
described by a string field type is #BT_CTF_STRING_ENCODING_UTF8. You
can set the encoding of the string fields described by a string field
type with bt_ctf_field_type_string_set_encoding().
*/
/**
-@brief Creates a default CTF IR string field type.
+@brief Creates a default @stringft.
@returns Created string field type, or \c NULL on error.
extern struct bt_ctf_field_type *bt_ctf_field_type_string_create(void);
/**
-@brief Returns the encoding of the CTF IR string fields described by
- the CTF IR string field type \p string_field_type.
+@brief Returns the encoding of the @stringfields described by
+ the @stringft \p string_field_type.
@param[in] string_field_type String field type which describes the
string fields of which to get the
struct bt_ctf_field_type *string_field_type);
/**
-@brief Sets the encoding of the CTF IR string fields
- described by the CTF IR string field type \p string_field_type
- to \p encoding.
+@brief Sets the encoding of the @stringfields described by the
+ @stringft \p string_field_type to \p encoding.
@param[in] string_field_type String field type which describes the
string fields of which to set the
@endcode
A CTF IR <strong><em>structure field type</em></strong> is
-a field type that you can use to create concrete
-\link ctfirstructfield CTF IR structure fields\endlink.
+a field type that you can use to create concrete @structfields.
You can create a structure field type
with bt_ctf_field_type_structure_create(). This function creates
of the structure fields described by a structure field type, as per
<a href="http://diamon.org/ctf/">CTF</a>, is the \em maximum value amongst
the effective alignments of all its fields. Note that the effective
-alignment of CTF IR variant fields is always 1.
+alignment of @varfields is always 1.
You can set the byte order of <em>all the contained fields</em>,
recursively, of a structure field type with the common
*/
/**
-@brief Creates a default, empty CTF IR structure field type.
+@brief Creates a default, empty @structft.
@returns Created structure field type,
or \c NULL on error.
extern struct bt_ctf_field_type *bt_ctf_field_type_structure_create(void);
/**
-@brief Returns the number of fields contained in the CTF IR
- structure field type \p struct_field_type.
+@brief Returns the number of fields contained in the
+ @structft \p struct_field_type.
@param[in] struct_field_type Structure field type of which to get
the number of contained fields.
@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);
/**
-@brief Returns the field of the CTF IR structure field type
- \p struct_field_type at index \p index.
+@brief Returns the field of the @structft \p struct_field_type
+ at index \p index.
On success, the field's type is placed in \p *field_type if
\p field_type is not \c NULL. The field's name is placed in
@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
- the CTF IR structure field type \p struct_field_type.
+ the @structft \p struct_field_type.
@param[in] struct_field_type Structure field type of which to get
a field's type.
@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
const char *field_name);
/**
-@brief Adds a field named \p field_name with the CTF IR field type
- \p field_type to the CTF IR structure field type
- \p struct_field_type.
+@brief Adds a field named \p field_name with the @ft
+ \p field_type to the @structft \p struct_field_type.
On success, \p field_type becomes the child of \p struct_field_type.
@endcode
A CTF IR <strong><em>array field type</em></strong> is a field type that
-you can use to create concrete
-\link ctfirarrayfield CTF IR array fields\endlink.
+you can use to create concrete @arrayfields.
You can create an array field type
with bt_ctf_field_type_array_create(). This function needs
-the field type of the fields contained by the array fields
-described by the array field type to create.
+the @ft of the fields contained by the array fields described by the
+array field type to create.
@sa ctfirarrayfield
@sa ctfirfieldtypes
*/
/**
-@brief Creates a default CTF IR array field type with
+@brief Creates a default @arrayft with
\p element_field_type as the field type of the fields contained
- in its described array fields of length \p length.
+ in its described @arrayfields of length \p length.
@param[in] element_field_type Field type of the fields contained in
the array fields described by the
unsigned int length);
/**
-@brief Returns the CTF IR field type of the CTF IR fields contained in
- the CTF IR array fields described by the CTF IR array field type
- \p array_field_type.
+@brief Returns the @ft of the @fields contained in
+ the @arrayfields described by the @arrayft \p array_field_type.
@param[in] array_field_type Array field type of which to get
the type of the fields contained in its
struct bt_ctf_field_type *array_field_type);
/**
-@brief Returns the number of CTF IR fields contained in the
- CTF IR array fields described by the CTF IR array field type
- \p array_field_type.
+@brief Returns the number of @fields contained in the
+ @arrayfields described by the @arrayft \p array_field_type.
@param[in] array_field_type Array field type of which to get
the number of fields contained in its
@endcode
A CTF IR <strong><em>sequence field type</em></strong> is
-a field type that you can use to create concrete
-\link ctfirseqfield CTF IR sequence fields\endlink.
+a field type that you can use to create concrete @seqfields.
You can create a sequence field type with
-bt_ctf_field_type_sequence_create(). This function needs the field type
+bt_ctf_field_type_sequence_create(). This function needs the @ft
of the fields contained by the sequence fields described by the created
sequence field type. This function also needs the length name of the
sequence field type to create. The length name is used to automatically
*/
/**
-@brief Creates a default CTF IR sequence field type with
- \p element_field_type as the field type of the fields contained
- in its described sequence fields with the length name
- \p length_name.
+@brief Creates a default @seqft with \p element_field_type as the
+ @ft of the @fields contained in its described @seqfields
+ with the length name \p length_name.
\p length_name can be an absolute or relative reference. See
<a href="http://diamon.org/ctf/">CTF</a> for more details.
const char *length_name);
/**
-@brief Returns the CTF IR field type of the CTF IR fields contained in
- the CTF IR sequence fields described by the CTF IR sequence
- field type \p sequence_field_type.
+@brief Returns the @ft of the @fields contained in the @seqft
+ described by the @seqft \p sequence_field_type.
@param[in] sequence_field_type Sequence field type of which to get
the type of the fields contained in its
struct bt_ctf_field_type *sequence_field_type);
/**
-@brief Returns the length name of the CTF IR sequence
- field type \p sequence_field_type.
+@brief Returns the length name of the @seqft \p sequence_field_type.
On success, \p sequence_field_type remains the sole owner of
the returned string.
struct bt_ctf_field_type *sequence_field_type);
/**
-@brief Returns the length's CTF IR field path of the CTF IR sequence
- field type \p sequence_field_type.
+@brief Returns the length's CTF IR field path of the @seqft
+ \p sequence_field_type.
The length's field path of a sequence field type is set when automatic
resolving is performed (see \ref ctfirfieldtypes).
@endcode
A CTF IR <strong><em>variant field type</em></strong> is
-a field type that you can use to create concrete
-\link ctfirvarfield CTF IR variant fields\endlink.
-
-You can create a variant field type
-with bt_ctf_field_type_variant_create(). This function expects you to
-pass both the tag's
-\link ctfirenumfieldtype CTF IR enumeration field type\endlink and
-the tag name of the variant field type to create. The tag's field type
-is optional, as the Babeltrace system can automatically resolve it using
-the tag name. You can leave the tag name to \c NULL initially, and set
-it later with bt_ctf_field_type_variant_set_tag_name(). The tag name
-must be set when the variant field type is frozen. See \ref
-ctfirfieldtypes to learn more about the automatic resolving and the
-conditions under which a field type can be frozen.
+a field type that you can use to create concrete @varfields.
+
+You can create a variant field type with
+bt_ctf_field_type_variant_create(). This function expects you to pass
+both the tag's @enumft and the tag name of the variant field type to
+create. The tag's field type is optional, as the Babeltrace system can
+automatically resolve it using the tag name. You can leave the tag name
+to \c NULL initially, and set it later with
+bt_ctf_field_type_variant_set_tag_name(). The tag name must be set when
+the variant field type is frozen. See \ref ctfirfieldtypes to learn more
+about the automatic resolving and the conditions under which a field
+type can be frozen.
You can add a field to a variant field type with
bt_ctf_field_type_variant_add_field(). All the field names of a
-variant field type \em must exist as mapping names in its tag's
-enumeration field type.
+variant field type \em must exist as mapping names in its tag's @enumft.
-The effective alignment of the CTF IR variant fields described by a
+The effective alignment of the @varfields described by a
variant field type is always 1, but the individual fields of a
-CTF IR variant field can have custom alignments.
+@varfield can have custom alignments.
You can set the byte order of <em>all the contained fields</em>,
recursively, of a variant field type with the common
*/
/**
-@brief Creates a default, empty CTF IR variant field type with the
- tag's \link ctfirenumfieldtype CTF IR enumeration field type\endlink
+@brief Creates a default, empty @varft with the tag's @enumft
\p tag_field_type and the tag name \p tag_name.
\p tag_field_type can be \c NULL; the tag's field type can be
const char *tag_name);
/**
-@brief Returns the tag's
- \link ctfirenumfieldtype CTF IR enumeration field type\endlink
- of the CTF IR variant field type \p variant_field_type.
+@brief Returns the tag's @enumft of the @varft \p variant_field_type.
@param[in] variant_field_type Variant field type of which to get
the tag's enumeration field type.
struct bt_ctf_field_type *variant_field_type);
/**
-@brief Returns the tag name of the CTF IR variant
- field type \p variant_field_type.
+@brief Returns the tag name of the @varft \p variant_field_type.
On success, \p variant_field_type remains the sole owner of
the returned string.
struct bt_ctf_field_type *variant_field_type);
/**
-@brief Sets the tag name of the CTF IR variant field type
- \p variant_field_type.
+@brief Sets the tag name of the @varft \p variant_field_type.
\p tag_name can be an absolute or relative reference. See
<a href="http://diamon.org/ctf/">CTF</a> for more details.
const char *tag_name);
/**
-@brief Returns the tag's CTF IR field path of the CTF IR variant
- field type \p variant_field_type.
+@brief Returns the tag's CTF IR field path of the @varft
+ \p variant_field_type.
The tag's field path of a variant field type is set when automatic
resolving is performed (see \ref ctfirfieldtypes).
struct bt_ctf_field_type *variant_field_type);
/**
-@brief Returns the number of fields contained in the CTF IR
- variant field type \p variant_field_type.
+@brief Returns the number of fields (choices) contained in the @varft
+ \p variant_field_type.
@param[in] variant_field_type Variant field type of which to get
the number of contained fields.
@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);
/**
-@brief Returns the field (choice) of the CTF IR variant field type
- \p variant_field_type at index \p index.
+@brief Returns the field (choice) of the @varft \p variant_field_type
+ at index \p index.
On success, the field's type is placed in \p *field_type if
\p field_type is not \c NULL. The field's name is placed in
@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
- found in the CTF IR variant field type \p variant_field_type.
+ found in the @varft \p variant_field_type.
@param[in] variant_field_type Variant field type of which to get
a field's type.
@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.
/**
@brief Returns the type of the field (choice) selected by the value of
- the \link ctfirenumfield CTF IR enumeration field\endlink
- \p tag_field in the CTF IR variant field type
- \p variant_field_type.
+ the @enumfield \p tag_field in the @varft \p variant_field_type.
\p tag_field is the 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.
struct bt_ctf_field *tag_field);
/**
-@brief Adds a field (a choice) named \p field_name with the CTF IR
- field type \p field_type to the CTF IR variant field type
- \p variant_field_type.
+@brief Adds a field (a choice) named \p field_name with the @ft
+ \p field_type to the @varft \p variant_field_type.
On success, \p field_type becomes the child of \p variant_field_type.