X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Ffield-types.h;h=f1f6ef7acbe1bb17b57aeb40c8a1bf6bbc665acd;hb=3dca22768a95bef664012559aa9ac977091de6ac;hp=de4346481bf4f00ba3d014eb78cce159e965f14c;hpb=cfb61c11ca4199917f6cd0e12a3d3951929dbe83;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/field-types.h b/include/babeltrace/ctf-ir/field-types.h index de434648..f1f6ef7a 100644 --- a/include/babeltrace/ctf-ir/field-types.h +++ b/include/babeltrace/ctf-ir/field-types.h @@ -30,7 +30,11 @@ * http://www.efficios.com/ctf */ +/* For bt_bool */ +#include + #include +#include #ifdef __cplusplus extern "C" { @@ -49,23 +53,23 @@ A CTF IR field type is a field type that you can use to create concrete @fields. You can create a @field object from a CTF IR field type object -with bt_ctf_field_create(). +with bt_field_create(). In the CTF IR hierarchy, you can set the root field types of three objects: - \ref ctfirtraceclass - - Trace packet header field type: bt_ctf_trace_set_packet_header_type(). + - Trace packet header field type: bt_trace_set_packet_header_field_type(). - \ref ctfirstreamclass - Stream packet context field type: - bt_ctf_stream_class_set_packet_context_type(). + bt_stream_class_set_packet_context_field_type(). - Stream event header field type: - bt_ctf_stream_class_set_event_header_type(). + bt_stream_class_set_event_header_field_type(). - Stream event context field type: - bt_ctf_stream_class_set_event_context_type(). + bt_stream_class_set_event_context_field_type(). - \ref ctfireventclass - - Event context field type: bt_ctf_event_class_set_context_type(). - - Event payload field type: bt_ctf_event_class_set_payload_type(). + - Event context field type: bt_event_class_set_context_field_type(). + - Event payload field type: bt_event_class_set_payload_field_type(). As of Babeltrace \btversion, those six previous "root" field types \em must be @structft objects. @@ -80,10 +84,10 @@ types contained in a given \link ctfirstreamclass CTF IR stream class\endlink (and in its children \link ctfireventclass CTF IR event classes\endlink) once you add it to a \link ctfirtraceclass CTF IR trace class\endlink with -bt_ctf_trace_add_stream_class(). Once a stream class is the child of +bt_trace_add_stream_class(). Once a stream class is the child of a trace class, this automatic resolving is performed for the field types of an event class when you add it with -bt_ctf_stream_class_add_event_class(). If the system cannot find a path +bt_stream_class_add_event_class(). If the system cannot find a path to a field in the hierarchy for a dynamic field type, the adding function fails. @@ -96,59 +100,59 @@ The standard CTF field types are: CTF IR field which you can create from this field type - #BT_CTF_TYPE_ID_INTEGER + #BT_FIELD_TYPE_ID_INTEGER \ref ctfirintfieldtype \ref ctfirintfield - #BT_CTF_TYPE_ID_FLOAT + #BT_FIELD_TYPE_ID_FLOAT \ref ctfirfloatfieldtype \ref ctfirfloatfield - #BT_CTF_TYPE_ID_ENUM + #BT_FIELD_TYPE_ID_ENUM \ref ctfirenumfieldtype \ref ctfirenumfield - #BT_CTF_TYPE_ID_STRING + #BT_FIELD_TYPE_ID_STRING \ref ctfirstringfieldtype \ref ctfirstringfield - #BT_CTF_TYPE_ID_STRUCT + #BT_FIELD_TYPE_ID_STRUCT \ref ctfirstructfieldtype \ref ctfirstructfield - #BT_CTF_TYPE_ID_ARRAY + #BT_FIELD_TYPE_ID_ARRAY \ref ctfirarrayfieldtype \ref ctfirarrayfield - #BT_CTF_TYPE_ID_SEQUENCE + #BT_FIELD_TYPE_ID_SEQUENCE \ref ctfirseqfieldtype \ref ctfirseqfield - #BT_CTF_TYPE_ID_VARIANT + #BT_FIELD_TYPE_ID_VARIANT \ref ctfirvarfieldtype \ref ctfirvarfield Each field type has its own type ID (see -#bt_ctf_type_id). You get the type ID of a field type object -with bt_ctf_field_type_get_type_id(). +#bt_field_type_id). You get the type ID of a field type object +with bt_field_type_get_type_id(). -You can get a deep copy of a field type with bt_ctf_field_type_copy(). +You can get a deep copy of a field type with bt_field_type_copy(). This function resets, in the field type copy, the resolved field type of the dynamic field types. The automatic resolving can be done again -when you eventually call bt_ctf_event_create(), -bt_ctf_stream_class_add_event_class(), or -bt_ctf_trace_add_stream_class(). +when you eventually call bt_event_create(), +bt_stream_class_add_event_class(), or +bt_trace_add_stream_class(). -You \em must always use bt_ctf_field_type_compare() to compare two +You \em must always use bt_field_type_compare() to compare two field types. Since some parts of the Babeltrace system can copy field types behind the scenes, you \em cannot rely on a simple field type pointer comparison. @@ -160,18 +164,18 @@ management of Babeltrace objects. The following functions can \em freeze field type objects: -- bt_ctf_field_create() freezes its field type parameter. -- bt_ctf_stream_class_add_event_class(), if its +- bt_field_create() freezes its field type parameter. +- bt_stream_class_add_event_class(), if its \link ctfirstreamclass CTF IR stream class\endlink parameter has a \link ctfirtraceclass CTF IR trace class\endlink parent, freezes the root field types of its \link ctfireventclass CTF IR event class\endlink parameter. -- bt_ctf_trace_add_stream_class() freezes the root field types of the +- bt_trace_add_stream_class() freezes the root field types of the whole trace class hierarchy (trace class, children stream classes, and their children event classes). -- bt_ctf_writer_create_stream() freezes the root field types of the +- bt_writer_create_stream() freezes the root field types of the whole CTF writer's trace class hierarchy. -- bt_ctf_event_create() freezes the root field types of its event class +- bt_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 @@ -189,80 +193,45 @@ immutable, except for \link refs reference counting\endlink. */ /** -@struct bt_ctf_field_type +@struct bt_field_type @brief A CTF IR field type. @sa ctfirfieldtypes */ -struct bt_ctf_field_type; -struct bt_ctf_event_class; -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 - * 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, - NR_CTF_TYPES, -}; - -/* - * Old enum. - */ -enum ctf_string_encoding { - CTF_STRING_NONE = 0, - CTF_STRING_UTF8, - CTF_STRING_ASCII, - CTF_STRING_UNKNOWN, -}; - -/** @endcond */ +struct bt_field_type; +struct bt_event_class; +struct bt_event; +struct bt_field; +struct bt_field_path; +struct bt_field_type_enumeration_mapping_iterator; /** @brief CTF scope. */ -enum bt_ctf_scope { +enum bt_scope { /// Unknown, used for errors. - BT_CTF_SCOPE_UNKNOWN = -1, + BT_SCOPE_UNKNOWN = -1, /// Trace packet header. - BT_CTF_SCOPE_TRACE_PACKET_HEADER = 1, + BT_SCOPE_TRACE_PACKET_HEADER = 1, /// Stream packet context. - BT_CTF_SCOPE_STREAM_PACKET_CONTEXT = 2, + BT_SCOPE_STREAM_PACKET_CONTEXT = 2, /// Stream event header. - BT_CTF_SCOPE_STREAM_EVENT_HEADER = 3, + BT_SCOPE_STREAM_EVENT_HEADER = 3, /// Stream event context. - BT_CTF_SCOPE_STREAM_EVENT_CONTEXT = 4, + BT_SCOPE_STREAM_EVENT_CONTEXT = 4, /// Event context. - BT_CTF_SCOPE_EVENT_CONTEXT = 5, + BT_SCOPE_EVENT_CONTEXT = 5, /// Event payload. - BT_CTF_SCOPE_EVENT_PAYLOAD = 6, + BT_SCOPE_EVENT_PAYLOAD = 6, /// @cond DOCUMENT - BT_CTF_SCOPE_ENV = 0, - BT_CTF_SCOPE_EVENT_FIELDS = 6, + BT_SCOPE_ENV = 0, + BT_SCOPE_EVENT_FIELDS = 6, /// @endcond }; @@ -274,40 +243,36 @@ enum bt_ctf_scope { /** @brief Type ID of a @ft. */ -enum bt_ctf_type_id { +enum bt_field_type_id { /// Unknown, used for errors. - BT_CTF_TYPE_ID_UNKNOWN = CTF_TYPE_UNKNOWN, + BT_FIELD_TYPE_ID_UNKNOWN = -1, /// \ref ctfirintfieldtype - BT_CTF_TYPE_ID_INTEGER = CTF_TYPE_INTEGER, + BT_FIELD_TYPE_ID_INTEGER = 0, /// \ref ctfirfloatfieldtype - BT_CTF_TYPE_ID_FLOAT = CTF_TYPE_FLOAT, + BT_FIELD_TYPE_ID_FLOAT = 1, /// \ref ctfirenumfieldtype - BT_CTF_TYPE_ID_ENUM = CTF_TYPE_ENUM, + BT_FIELD_TYPE_ID_ENUM = 2, /// \ref ctfirstringfieldtype - BT_CTF_TYPE_ID_STRING = CTF_TYPE_STRING, + BT_FIELD_TYPE_ID_STRING = 3, /// \ref ctfirstructfieldtype - BT_CTF_TYPE_ID_STRUCT = CTF_TYPE_STRUCT, - - /// @cond DOCUMENT - BT_CTF_TYPE_ID_UNTAGGED_VARIANT = CTF_TYPE_UNTAGGED_VARIANT, - /// @endcond + BT_FIELD_TYPE_ID_STRUCT = 4, /// \ref ctfirarrayfieldtype - BT_CTF_TYPE_ID_ARRAY = CTF_TYPE_ARRAY, + BT_FIELD_TYPE_ID_ARRAY = 6, /// \ref ctfirseqfieldtype - BT_CTF_TYPE_ID_SEQUENCE = CTF_TYPE_SEQUENCE, + BT_FIELD_TYPE_ID_SEQUENCE = 7, /// \ref ctfirvarfieldtype - BT_CTF_TYPE_ID_VARIANT = CTF_TYPE_VARIANT, + BT_FIELD_TYPE_ID_VARIANT = 5, /// Number of enumeration entries. - BT_CTF_NR_TYPE_IDS = NR_CTF_TYPES, + BT_FIELD_TYPE_ID_NR = 8, }; /** @@ -315,153 +280,161 @@ enum bt_ctf_type_id { @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_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_is_integer(): Returns whether or not a given +@sa #bt_field_type_id: CTF IR field type ID. +@sa bt_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_field_type_is_floating_point(): Returns whether or not a given field type is a @floatft. -@sa bt_ctf_field_type_is_enumeration(): Returns whether or not a given +@sa bt_field_type_is_enumeration(): Returns whether or not a given field type is a @enumft. -@sa bt_ctf_field_type_is_string(): Returns whether or not a given +@sa bt_field_type_is_string(): Returns whether or not a given field type is a @stringft. -@sa bt_ctf_field_type_is_structure(): Returns whether or not a given +@sa bt_field_type_is_structure(): Returns whether or not a given field type is a @structft. -@sa bt_ctf_field_type_is_array(): Returns whether or not a given +@sa bt_field_type_is_array(): Returns whether or not a given field type is a @arrayft. -@sa bt_ctf_field_type_is_sequence(): Returns whether or not a given +@sa bt_field_type_is_sequence(): Returns whether or not a given field type is a @seqft. -@sa bt_ctf_field_type_is_variant(): Returns whether or not a given +@sa bt_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( - struct bt_ctf_field_type *field_type); +extern enum bt_field_type_id bt_field_type_get_type_id( + struct bt_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} @postrefcountsame{field_type} -@sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given +@sa bt_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_field_type_is_integer( + struct bt_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). @postrefcountsame{field_type} -@sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given +@sa bt_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_field_type_is_floating_point( + struct bt_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 +@sa bt_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_field_type_is_enumeration( + struct bt_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 +@sa bt_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_field_type_is_string( + struct bt_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 +@sa bt_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_field_type_is_structure( + struct bt_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 +@sa bt_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_field_type_is_array( + struct bt_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 +@sa bt_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_field_type_is_sequence( + struct bt_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 +@sa bt_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_field_type_is_variant( + struct bt_field_type *field_type); /** @} */ @@ -474,9 +447,9 @@ extern int bt_ctf_field_type_is_variant(struct bt_ctf_field_type *field_type); @brief Byte order of a @ft. */ -enum bt_ctf_byte_order { +enum bt_byte_order { /// Unknown, used for errors. - BT_CTF_BYTE_ORDER_UNKNOWN = -1, + BT_BYTE_ORDER_UNKNOWN = -1, /* * Note that native, in the context of the CTF specification, is defined @@ -484,33 +457,39 @@ enum bt_ctf_byte_order { * host's endianness will be used. */ /// Native (default) byte order. - BT_CTF_BYTE_ORDER_NATIVE = 0, + BT_BYTE_ORDER_NATIVE = 0, + + /** + Unspecified byte order; the initial native byte order of a + \link ctfirtraceclass CTF IR trace class\endlink. + */ + BT_BYTE_ORDER_UNSPECIFIED, /// Little-endian. - BT_CTF_BYTE_ORDER_LITTLE_ENDIAN, + BT_BYTE_ORDER_LITTLE_ENDIAN, /// Big-endian. - BT_CTF_BYTE_ORDER_BIG_ENDIAN, + BT_BYTE_ORDER_BIG_ENDIAN, /// Network byte order (big-endian). - BT_CTF_BYTE_ORDER_NETWORK, + BT_BYTE_ORDER_NETWORK, }; /** @brief String encoding of a @ft. */ -enum bt_ctf_string_encoding { +enum bt_string_encoding { /// Unknown, used for errors. - BT_CTF_STRING_ENCODING_UNKNOWN = CTF_STRING_UNKNOWN, + BT_STRING_ENCODING_UNKNOWN = -1, /// No encoding. - BT_CTF_STRING_ENCODING_NONE = CTF_STRING_NONE, + BT_STRING_ENCODING_NONE, /// UTF-8. - BT_CTF_STRING_ENCODING_UTF8 = CTF_STRING_UTF8, + BT_STRING_ENCODING_UTF8, /// ASCII. - BT_CTF_STRING_ENCODING_ASCII = CTF_STRING_ASCII, + BT_STRING_ENCODING_ASCII, }; /** @@ -525,11 +504,11 @@ enum bt_ctf_string_encoding { @prenotnull{field_type} @postrefcountsame{field_type} -@sa bt_ctf_field_type_set_alignment(): Sets the alignment +@sa bt_field_type_set_alignment(): Sets the alignment of the fields described by a given field type. */ -extern int bt_ctf_field_type_get_alignment( - struct bt_ctf_field_type *field_type); +extern int bt_field_type_get_alignment( + struct bt_field_type *field_type); /** @brief Sets the alignment of the @fields described by the @@ -548,10 +527,10 @@ extern int bt_ctf_field_type_get_alignment( @pre \p alignment is greater than 0 and a power of two. @postrefcountsame{field_type} -@sa bt_ctf_field_type_get_alignment(): Returns the alignment of the +@sa bt_field_type_get_alignment(): Returns the alignment of the fields described by a given field type. */ -extern int bt_ctf_field_type_set_alignment(struct bt_ctf_field_type *field_type, +extern int bt_field_type_set_alignment(struct bt_field_type *field_type, unsigned int alignment); /** @@ -564,18 +543,18 @@ You can only call this function if \p field_type is a @intft, a @param[in] field_type Field type which describes the fields of which to get the byte order. @returns Byte order of the fields described by - \p field_type, or #BT_CTF_BYTE_ORDER_UNKNOWN on + \p field_type, or #BT_BYTE_ORDER_UNKNOWN on error. @prenotnull{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 +@sa bt_field_type_set_byte_order(): Sets the byte order of the fields described by a given field type. */ -extern enum bt_ctf_byte_order bt_ctf_field_type_get_byte_order( - struct bt_ctf_field_type *field_type); +extern enum bt_byte_order bt_field_type_get_byte_order( + struct bt_field_type *field_type); /** @brief Sets the byte order of the @fields described by the @@ -592,17 +571,17 @@ recursively sets the byte order of its children to \p byte_order. @prenotnull{field_type} @prehot{field_type} -@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. +@pre \p byte_order is #BT_BYTE_ORDER_NATIVE, + #BT_BYTE_ORDER_LITTLE_ENDIAN, #BT_BYTE_ORDER_BIG_ENDIAN, + or #BT_BYTE_ORDER_NETWORK. @postrefcountsame{field_type} -@sa bt_ctf_field_type_get_byte_order(): Returns the byte order of the +@sa bt_field_type_get_byte_order(): Returns the byte order of the fields described by a given field type. */ -extern int bt_ctf_field_type_set_byte_order( - struct bt_ctf_field_type *field_type, - enum bt_ctf_byte_order byte_order); +extern int bt_field_type_set_byte_order( + struct bt_field_type *field_type, + enum bt_byte_order byte_order); /** @} */ @@ -631,8 +610,8 @@ and discard the original ones. @postrefcountsame{field_type_a} @postrefcountsame{field_type_b} */ -extern int bt_ctf_field_type_compare(struct bt_ctf_field_type *field_type_a, - struct bt_ctf_field_type *field_type_b); +extern int bt_field_type_compare(struct bt_field_type *field_type_a, + struct bt_field_type *field_type_b); /** @brief Creates a \em deep copy of the @ft \p field_type. @@ -654,8 +633,8 @@ in the detailed description of this module). @postsuccessrefcountret1 @post On success, 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); +extern struct bt_field_type *bt_field_type_copy( + struct bt_field_type *field_type); /** @} */ @@ -674,7 +653,7 @@ A CTF IR integer field type is a field type that you can use to create concrete @intfield objects. You can create an integer field type -with bt_ctf_field_type_integer_create(). +with bt_field_type_integer_create(). An integer field type has the following properties: @@ -688,47 +667,47 @@ An integer field type has the following properties: \b Alignment (bits) of the described integer fields 1 - bt_ctf_field_type_get_alignment() - bt_ctf_field_type_set_alignment() + bt_field_type_get_alignment() + bt_field_type_set_alignment() Byte order of the described integer fields - #BT_CTF_BYTE_ORDER_NATIVE - bt_ctf_field_type_get_byte_order() - bt_ctf_field_type_set_byte_order() + #BT_BYTE_ORDER_NATIVE + bt_field_type_get_byte_order() + bt_field_type_set_byte_order() Storage size (bits) of the described integer fields Specified at creation - bt_ctf_field_type_integer_get_size() - None: specified at creation (bt_ctf_field_type_integer_create()) + bt_field_type_integer_get_size() + bt_field_type_integer_set_size() Signedness of the described integer fields Unsigned - bt_ctf_field_type_integer_get_signed() - bt_ctf_field_type_integer_set_signed() + bt_field_type_integer_is_signed() + bt_field_type_integer_set_is_signed() Preferred display base of the described integer fields - #BT_CTF_INTEGER_BASE_DECIMAL - bt_ctf_field_type_integer_get_base() - bt_ctf_field_type_integer_set_base() + #BT_INTEGER_BASE_DECIMAL + bt_field_type_integer_get_base() + bt_field_type_integer_set_base() \b Encoding of the described integer fields - #BT_CTF_STRING_ENCODING_NONE - bt_ctf_field_type_integer_get_encoding() - bt_ctf_field_type_integer_set_encoding() + #BT_STRING_ENCODING_NONE + bt_field_type_integer_get_encoding() + bt_field_type_integer_set_encoding() Mapped \link ctfirclockclass CTF IR clock class\endlink None - bt_ctf_field_type_integer_get_mapped_clock_class() - bt_ctf_field_type_integer_set_mapped_clock_class() + bt_field_type_integer_get_mapped_clock_class() + bt_field_type_integer_set_mapped_clock_class() @@ -743,34 +722,41 @@ An integer field type has the following properties: /** @brief Preferred display base (radix) of a @intft. */ -enum bt_ctf_integer_base { +enum bt_integer_base { /// Unknown, used for errors. - BT_CTF_INTEGER_BASE_UNKNOWN = -1, + BT_INTEGER_BASE_UNKNOWN = -1, + + /// Unspecified by the tracer. + BT_INTEGER_BASE_UNSPECIFIED = 0, /// Binary. - BT_CTF_INTEGER_BASE_BINARY = 2, + BT_INTEGER_BASE_BINARY = 2, /// Octal. - BT_CTF_INTEGER_BASE_OCTAL = 8, + BT_INTEGER_BASE_OCTAL = 8, /// Decimal. - BT_CTF_INTEGER_BASE_DECIMAL = 10, + BT_INTEGER_BASE_DECIMAL = 10, /// Hexadecimal. - BT_CTF_INTEGER_BASE_HEXADECIMAL = 16, + BT_INTEGER_BASE_HEXADECIMAL = 16, }; /** @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_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. @pre \p size is greater than 0 and lesser than or equal to 64. @postsuccessrefcountret1 */ -extern struct bt_ctf_field_type *bt_ctf_field_type_integer_create( +extern struct bt_field_type *bt_field_type_integer_create( unsigned int size); /** @@ -787,9 +773,35 @@ extern struct bt_ctf_field_type *bt_ctf_field_type_integer_create( @prenotnull{int_field_type} @preisintft{int_field_type} @postrefcountsame{int_field_type} + +@sa bt_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); +extern int bt_field_type_integer_get_size( + struct bt_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_field_type_integer_get_size(): Returns the storage size of + the integer fields described by a given integer field type. +*/ +extern int bt_field_type_integer_set_size( + struct bt_field_type *int_field_type, unsigned int size); /** @brief Returns whether or not the @intfields described by the @intft @@ -798,20 +810,19 @@ extern int bt_ctf_field_type_integer_get_size( @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_field_type_integer_set_is_signed(): Sets the signedness of the integer fields described by a given integer field type. */ -extern int bt_ctf_field_type_integer_get_signed( - struct bt_ctf_field_type *int_field_type); +extern bt_bool bt_field_type_integer_is_signed( + struct bt_field_type *int_field_type); /** @brief Sets whether or not the @intfields described by @@ -821,21 +832,20 @@ extern int bt_ctf_field_type_integer_get_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_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_field_type_integer_set_is_signed( + struct bt_field_type *int_field_type, bt_bool is_signed); /** @brief Returns the preferred display base (radix) of the @intfields @@ -846,19 +856,20 @@ extern int bt_ctf_field_type_integer_set_signed( 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_INTEGER_BASE_UNSPECIFIED if + not specified, or + #BT_INTEGER_BASE_UNKNOWN on error. @prenotnull{int_field_type} @preisintft{int_field_type} @postrefcountsame{int_field_type} -@sa bt_ctf_field_type_integer_set_base(): Sets the preferred display +@sa bt_field_type_integer_set_base(): Sets the preferred display base of the integer fields described by a given integer field type. */ -extern enum bt_ctf_integer_base bt_ctf_field_type_integer_get_base( - struct bt_ctf_field_type *int_field_type); +extern enum bt_integer_base bt_field_type_integer_get_base( + struct bt_field_type *int_field_type); /** @brief Sets the preferred display base (radix) of the @intfields @@ -874,18 +885,18 @@ extern enum bt_ctf_integer_base bt_ctf_field_type_integer_get_base( @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_INTEGER_BASE_UNSPECIFIED, + #BT_INTEGER_BASE_BINARY, #BT_INTEGER_BASE_OCTAL, + #BT_INTEGER_BASE_DECIMAL, or #BT_INTEGER_BASE_HEXADECIMAL. @postrefcountsame{int_field_type} -@sa bt_ctf_field_type_integer_get_base(): Returns the preferred display +@sa bt_field_type_integer_get_base(): Returns the preferred display base of the integer fields described by a given integer field type. */ -extern int bt_ctf_field_type_integer_set_base( - struct bt_ctf_field_type *int_field_type, - enum bt_ctf_integer_base base); +extern int bt_field_type_integer_set_base( + struct bt_field_type *int_field_type, + enum bt_integer_base base); /** @brief Returns the encoding of the @intfields described by @@ -896,18 +907,18 @@ extern int bt_ctf_field_type_integer_set_base( encoding. @returns Encoding of the integer fields described by \p int_field_type, - or #BT_CTF_STRING_ENCODING_UNKNOWN on + or #BT_STRING_ENCODING_UNKNOWN on error. @prenotnull{int_field_type} @preisintft{int_field_type} @postrefcountsame{int_field_type} -@sa bt_ctf_field_type_integer_set_encoding(): Sets the encoding +@sa bt_field_type_integer_set_encoding(): Sets the encoding of the integer fields described by a given integer field type. */ -extern enum bt_ctf_string_encoding bt_ctf_field_type_integer_get_encoding( - struct bt_ctf_field_type *int_field_type); +extern enum bt_string_encoding bt_field_type_integer_get_encoding( + struct bt_field_type *int_field_type); /** @brief Sets the encoding of the @intfields described by the @intft @@ -927,17 +938,17 @@ You can use this property, in CTF IR, to create "text" @arrayfts or @prenotnull{int_field_type} @preisintft{int_field_type} @prehot{int_field_type} -@pre \p encoding is #BT_CTF_STRING_ENCODING_NONE, - #BT_CTF_STRING_ENCODING_ASCII, or - #BT_CTF_STRING_ENCODING_UTF8. +@pre \p encoding is #BT_STRING_ENCODING_NONE, + #BT_STRING_ENCODING_ASCII, or + #BT_STRING_ENCODING_UTF8. @postrefcountsame{int_field_type} -@sa bt_ctf_field_type_integer_get_encoding(): Returns the encoding of +@sa bt_field_type_integer_get_encoding(): Returns the encoding of the integer fields described by a given integer field type. */ -extern int bt_ctf_field_type_integer_set_encoding( - struct bt_ctf_field_type *int_field_type, - enum bt_ctf_string_encoding encoding); +extern int bt_field_type_integer_set_encoding( + struct bt_field_type *int_field_type, + enum bt_string_encoding encoding); /** @brief Returns the \link ctfirclockclass CTF IR clock class\endlink @@ -958,11 +969,11 @@ This mapped clock class is only indicative. @postrefcountsame{int_field_type} @postsuccessrefcountretinc -@sa bt_ctf_field_type_integer_set_mapped_clock_class(): Sets the mapped +@sa bt_field_type_integer_set_mapped_clock_class(): Sets the mapped clock class of a given integer field type. */ -extern struct bt_ctf_clock_class *bt_ctf_field_type_integer_get_mapped_clock_class( - struct bt_ctf_field_type *int_field_type); +extern struct bt_clock_class *bt_field_type_integer_get_mapped_clock_class( + struct bt_field_type *int_field_type); /** @brief Sets the \link ctfirclockclass CTF IR clock class\endlink mapped @@ -984,12 +995,12 @@ This mapped clock class is only indicative. @postrefcountsame{int_field_type} @postsuccessrefcountinc{clock_class} -@sa bt_ctf_field_type_integer_get_mapped_clock_class(): Returns the mapped +@sa bt_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_class( - struct bt_ctf_field_type *int_field_type, - struct bt_ctf_clock_class *clock_class); +extern int bt_field_type_integer_set_mapped_clock_class( + struct bt_field_type *int_field_type, + struct bt_clock_class *clock_class); /** @} */ @@ -1006,7 +1017,7 @@ A CTF IR floating point number field type is 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(). +with bt_field_type_floating_point_create(). A floating point number field type has the following properties: @@ -1021,29 +1032,29 @@ A floating point number field type has the following properties: \b Alignment (bits) of the described floating point number fields 1 - bt_ctf_field_type_get_alignment() - bt_ctf_field_type_set_alignment() + bt_field_type_get_alignment() + bt_field_type_set_alignment() Byte order of the described floating point number fields - #BT_CTF_BYTE_ORDER_NATIVE - bt_ctf_field_type_get_byte_order() - bt_ctf_field_type_set_byte_order() + #BT_BYTE_ORDER_NATIVE + bt_field_type_get_byte_order() + bt_field_type_set_byte_order() Exponent storage size (bits) of the described floating point number fields 8 - bt_ctf_field_type_floating_point_get_exponent_digits() - bt_ctf_field_type_floating_point_set_exponent_digits() + bt_field_type_floating_point_get_exponent_digits() + bt_field_type_floating_point_set_exponent_digits() Mantissa and sign storage size (bits) of the described floating point number fields 24 (23-bit mantissa, 1-bit sign) - bt_ctf_field_type_floating_point_get_mantissa_digits() - bt_ctf_field_type_floating_point_set_mantissa_digits() + bt_field_type_floating_point_get_mantissa_digits() + bt_field_type_floating_point_set_mantissa_digits() @@ -1063,7 +1074,7 @@ A floating point number field type has the following properties: @postsuccessrefcountret1 */ -extern struct bt_ctf_field_type *bt_ctf_field_type_floating_point_create(void); +extern struct bt_field_type *bt_field_type_floating_point_create(void); /** @brief Returns the exponent storage size of the @floatfields @@ -1082,12 +1093,12 @@ extern struct bt_ctf_field_type *bt_ctf_field_type_floating_point_create(void); @preisfloatft{float_field_type} @postrefcountsame{float_field_type} -@sa bt_ctf_field_type_floating_point_set_exponent_digits(): Sets the +@sa bt_field_type_floating_point_set_exponent_digits(): Sets the exponent storage size of the floating point number fields described by a given floating point number field type. */ -extern int bt_ctf_field_type_floating_point_get_exponent_digits( - struct bt_ctf_field_type *float_field_type); +extern int bt_field_type_floating_point_get_exponent_digits( + struct bt_field_type *float_field_type); /** @brief Sets the exponent storage size of the @floatfields described by @@ -1110,12 +1121,12 @@ As of Babeltrace \btversion, \p exponent_size can only be 8 or 11. @pre \p exponent_size is 8 or 11. @postrefcountsame{float_field_type} -@sa bt_ctf_field_type_floating_point_get_exponent_digits(): Returns the +@sa bt_field_type_floating_point_get_exponent_digits(): Returns the exponent storage size of the floating point number fields described by a given floating point number field type. */ -extern int bt_ctf_field_type_floating_point_set_exponent_digits( - struct bt_ctf_field_type *float_field_type, +extern int bt_field_type_floating_point_set_exponent_digits( + struct bt_field_type *float_field_type, unsigned int exponent_size); /** @@ -1138,12 +1149,12 @@ sign storage sizes. @preisfloatft{float_field_type} @postrefcountsame{float_field_type} -@sa bt_ctf_field_type_floating_point_set_mantissa_digits(): Sets the +@sa bt_field_type_floating_point_set_mantissa_digits(): Sets the mantissa and size storage size of the floating point number fields described by a given floating point number field type. */ -extern int bt_ctf_field_type_floating_point_get_mantissa_digits( - struct bt_ctf_field_type *float_field_type); +extern int bt_field_type_floating_point_get_mantissa_digits( + struct bt_field_type *float_field_type); /** @brief Sets the mantissa and sign storage size of the @floatfields @@ -1167,12 +1178,12 @@ As of Babeltrace \btversion, \p mantissa_sign_size can only be 24 or 53. @pre \p mantissa_sign_size is 24 or 53. @postrefcountsame{float_field_type} -@sa bt_ctf_field_type_floating_point_get_mantissa_digits(): Returns the +@sa bt_field_type_floating_point_get_mantissa_digits(): Returns the mantissa and sign storage size of the floating point number fields described by a given floating point number field type. */ -extern int bt_ctf_field_type_floating_point_set_mantissa_digits( - struct bt_ctf_field_type *float_field_type, +extern int bt_field_type_floating_point_set_mantissa_digits( + struct bt_field_type *float_field_type, unsigned int mantissa_sign_size); /** @} */ @@ -1190,7 +1201,7 @@ A CTF IR enumeration field type is 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 @intft +bt_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. @@ -1202,10 +1213,24 @@ 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_unsigned(), depending on the +bt_field_type_enumeration_signed_add_mapping() or +bt_field_type_enumeration_unsigned_add_mapping(), depending on the signedness of the wrapped @intft. +You can find mappings by name or by value with the following find +operations: + +- bt_field_type_enumeration_find_mappings_by_name(): Finds the + mappings with a given name. +- bt_field_type_enumeration_unsigned_find_mappings_by_value(): + Finds the mappings which contain a given unsigned value in their + range. +- bt_field_type_enumeration_signed_find_mappings_by_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: @@ -1229,9 +1254,9 @@ APPLE -> [ 30, 55] Here, the range of the second \c APPLE mapping overlaps the range of the \c CHERRY mapping. +@sa ctfirenumftmappingiter @sa ctfirenumfield @sa ctfirfieldtypes -@sa ctfirenummappingiter @addtogroup ctfirenumfieldtype @{ @@ -1250,8 +1275,8 @@ the \c CHERRY mapping. @postsuccessrefcountinc{int_field_type} @postsuccessrefcountret1 */ -extern struct bt_ctf_field_type *bt_ctf_field_type_enumeration_create( - struct bt_ctf_field_type *int_field_type); +extern struct bt_field_type *bt_field_type_enumeration_create( + struct bt_field_type *int_field_type); /** @brief Returns the @intft wrapped by the @enumft \p enum_field_type. @@ -1268,8 +1293,8 @@ extern struct bt_ctf_field_type *bt_ctf_field_type_enumeration_create( @postsuccessrefcountretinc */ extern -struct bt_ctf_field_type *bt_ctf_field_type_enumeration_get_container_type( - struct bt_ctf_field_type *enum_field_type); +struct bt_field_type *bt_field_type_enumeration_get_container_field_type( + struct bt_field_type *enum_field_type); /** @brief Returns the number of mappings contained in the @@ -1285,15 +1310,15 @@ struct bt_ctf_field_type *bt_ctf_field_type_enumeration_get_container_type( @preisenumft{enum_field_type} @postrefcountsame{enum_field_type} */ -extern int bt_ctf_field_type_enumeration_get_mapping_count( - struct bt_ctf_field_type *enum_field_type); +extern int64_t bt_field_type_enumeration_get_mapping_count( + struct bt_field_type *enum_field_type); /** @brief Returns the signed mapping of the @enumft \p enum_field_type at index \p index. The @intft wrapped by \p enum_field_type, as returned by -bt_ctf_field_type_enumeration_get_container_type(), must be \b signed +bt_field_type_enumeration_get_container_field_type(), must be \b signed to use this function. On success, \p enum_field_type remains the sole owner of \p *name. @@ -1319,15 +1344,15 @@ On success, \p enum_field_type remains the sole owner of \p *name. @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()). + bt_field_type_enumeration_get_mapping_count()). @postrefcountsame{enum_field_type} -@sa bt_ctf_field_type_enumeration_get_mapping_unsigned(): Returns the +@sa bt_field_type_enumeration_unsigned_get_mapping_by_index(): 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, +extern int bt_field_type_enumeration_signed_get_mapping_by_index( + struct bt_field_type *enum_field_type, uint64_t index, const char **name, int64_t *range_begin, int64_t *range_end); /** @@ -1335,7 +1360,7 @@ extern int bt_ctf_field_type_enumeration_get_mapping_signed( \p enum_field_type at index \p index. The @intft wrapped by \p enum_field_type, as returned by -bt_ctf_field_type_enumeration_get_container_type(), must be +bt_field_type_enumeration_get_container_field_type(), must be \b unsigned to use this function. On success, \p enum_field_type remains the sole owner of \p *name. @@ -1361,79 +1386,123 @@ On success, \p enum_field_type remains the sole owner of \p *name. @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()). + bt_field_type_enumeration_get_mapping_count()). @postrefcountsame{enum_field_type} -@sa bt_ctf_field_type_enumeration_get_mapping_signed(): Returns the +@sa bt_field_type_enumeration_signed_get_mapping_by_index(): 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, +extern int bt_field_type_enumeration_unsigned_get_mapping_by_index( + struct bt_field_type *enum_field_type, uint64_t index, const char **name, uint64_t *range_begin, uint64_t *range_end); /** -@brief Returns a @enumiter on the mappings of the @enumft - \p enum_field_type that match \p name. +@brief Finds the mappings of the @enumft \p enum_field_type which + are named \p name. -@param[in] enum_field_type Enumeration field type of which to get - the mapping at index \p index. -@param[in] name Name of the mappings to find. -@returns @enumiter that - match \p name, or \c NULL on error. +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 -*/ -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, +@post On success, the returned @enumftiter can iterate + on at least one mapping. + +@sa bt_field_type_enumeration_signed_find_mappings_by_value(): Finds + the mappings of a given enumeration field type which contain + a given signed value in their range. +@sa bt_field_type_enumeration_unsigned_find_mappings_by_value(): Finds + the mappings of a given enumeration field type which contain + a given unsigned value in their range. +*/ +extern struct bt_field_type_enumeration_mapping_iterator * +bt_field_type_enumeration_find_mappings_by_name( + struct bt_field_type *enum_field_type, const char *name); /** -@brief Returns the mappings of the @enumft - \p enum_field_type that match \p value. +@brief Finds the mappings of the @enumft \p enum_field_type which + contain the signed value \p value in their range. -@param[in] enum_field_type Enumeration field type of which to get - the mapping at index \p index. -@param[in] value Signed value of the mappings to find. -@returns Iterator on enumeration mappings that - match \p value, or \c NULL on error. +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} -@prenotnull{name} @preisenumft{enum_field_type} @postrefcountsame{enum_field_type} @postsuccessrefcountret1 -*/ -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, +@post On success, the returned @enumftiter can iterate + on at least one mapping. + +@sa bt_field_type_enumeration_find_mappings_by_name(): Finds the + mappings of a given enumeration field type which have a given + name. +@sa bt_field_type_enumeration_unsigned_find_mappings_by_value(): Finds + the mappings of a given enumeration field type which contain + a given unsigned value in their range. +*/ +extern struct bt_field_type_enumeration_mapping_iterator * +bt_field_type_enumeration_signed_find_mappings_by_value( + struct bt_field_type *enum_field_type, int64_t value); /** -@brief Returns the mappings of the @enumft - \p enum_field_type that match \p value. +@brief Finds the mappings of the @enumft \p enum_field_type which + contain the unsigned value \p value in their range. -@param[in] enum_field_type Enumeration field type of which to get - the mapping at index \p index. -@param[in] value Unsigned value of the mappings to find. -@returns Iterator on enumeration mappings that - match \p value, or \c NULL on error. +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} -@prenotnull{name} @preisenumft{enum_field_type} @postrefcountsame{enum_field_type} @postsuccessrefcountret1 -*/ -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, +@post On success, the returned @enumftiter can iterate + on at least one mapping. + +@sa bt_field_type_enumeration_find_mappings_by_name(): Finds the + mappings of a given enumeration field type which have a given + name. +@sa bt_field_type_enumeration_signed_find_mappings_by_value(): Finds + the mappings of a given enumeration field type which contain + a given unsigned value in their range. +*/ +extern struct bt_field_type_enumeration_mapping_iterator * +bt_field_type_enumeration_unsigned_find_mappings_by_value( + struct bt_field_type *enum_field_type, uint64_t value); /** @@ -1445,7 +1514,7 @@ Make \p range_begin and \p range_end the same value to add a mapping to a single value. The @intft wrapped by \p enum_field_type, as returned by -bt_ctf_field_type_enumeration_get_container_type(), must be +bt_field_type_enumeration_get_container_field_type(), must be \b signed to use this function. A mapping in \p enum_field_type can exist with the name \p name. @@ -1462,16 +1531,17 @@ A mapping in \p enum_field_type can exist with the name \p name. @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. @postrefcountsame{enum_field_type} -@sa bt_ctf_field_type_enumeration_add_mapping_unsigned(): Adds an +@sa bt_field_type_enumeration_unsigned_add_mapping(): Adds an unsigned mapping to a given enumeration field type. */ -extern int bt_ctf_field_type_enumeration_add_mapping( - struct bt_ctf_field_type *enum_field_type, const char *name, +extern int bt_field_type_enumeration_signed_add_mapping( + struct bt_field_type *enum_field_type, const char *name, int64_t range_begin, int64_t range_end); /** @@ -1483,7 +1553,7 @@ Make \p range_begin and \p range_end the same value to add a mapping to a single value. The @intft wrapped by \p enum_field_type, as returned by -bt_ctf_field_type_enumeration_get_container_type(), must be +bt_field_type_enumeration_get_container_field_type(), must be \b unsigned to use this function. A mapping in \p enum_field_type can exist with the name \p name. @@ -1500,150 +1570,179 @@ A mapping in \p enum_field_type can exist with the name \p name. @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_field_type_enumeration_signed_add_mapping(): Adds a signed mapping to a given enumeration field type. */ -extern int bt_ctf_field_type_enumeration_add_mapping_unsigned( - struct bt_ctf_field_type *enum_field_type, const char *name, +extern int bt_field_type_enumeration_unsigned_add_mapping( + struct bt_field_type *enum_field_type, const char *name, uint64_t range_begin, uint64_t range_end); /** @} */ /** -@defgroup ctfirenummappingiter CTF IR enumeration mapping iterator -@ingroup ctfirfieldtypes -@brief CTF IR enumeration mapping iterator. -@struct bt_ctf_field_type_enumeration_mapping_iterator +@defgroup ctfirenumftmappingiter CTF IR enumeration field type mapping iterator +@ingroup ctfirenumfieldtype +@brief CTF IR enumeration field type mapping iterator. @code #include @endcode -A CTF IR enumeration mapping iterator is an -iterator on @enumft mappings. - -You can obtain an enumeration mapping iterator using one of the mapping -query functions:bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(), -bt_ctf_field_type_enumeration_find_mappings_by_signed_value(), and -bt_ctf_field_type_enumeration_find_mappings_by_name(). - -You can query an enumeration mapping's name from an iterator -using bt_ctf_field_type_enumeration_mapping_iterator_get_name(). - -You can also query an enumeration mapping's value range -from an iterator 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 wrapped @intft. - -An enumeration mapping iterator's position can -be advanced using -bt_ctf_field_type_enumeration_mapping_iterator_next(). +A CTF IR enumeration field type mapping +iterator 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_field_type_enumeration_find_mappings_by_name(): Finds the + mappings with a given name. + - bt_field_type_enumeration_unsigned_find_mappings_by_value(): + Finds the mappings which contain a given unsigned value in their + range. + - bt_field_type_enumeration_signed_find_mappings_by_value(): + Finds the mappings which contain a given signed value in their range. +- bt_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_field_type_enumeration_mapping_iterator_signed_get() +or +bt_field_type_enumeration_mapping_iterator_unsigned_get(), +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_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 reference +counts. See \ref refs to learn more about the reference counting +management of Babeltrace objects. @sa ctfirenumfieldtype -@sa ctfirenumfield -@addtogroup ctfirenummappingiter +@addtogroup ctfirenumftmappingiter @{ */ /** -@brief Returns the name of the @enumft mapping pointed to by - \p iter. - -On success, the returned \p mapping_name is valid as long as a reference -is held on \p iter and its position is not changed. - -@param[in] iter Enumeration mapping iterator. -@param[out] mapping_name Returned name of the mapping pointed to - by \p iter. -@returns 0 on success, or a negative value on error. - -@prenotnull{iter} -@prenotnull{mapping_name} -@postrefcountsame{iter} +@struct bt_field_type_enumeration_mapping_iterator +@brief A CTF IR enumeration field type mapping iterator. +@sa ctfirenumftmappingiter */ -extern int bt_ctf_field_type_enumeration_mapping_iterator_get_name( - struct bt_ctf_field_type_enumeration_mapping_iterator *iter, - const char **mapping_name); /** -@brief Returns the range of the signed @enumft mapping pointed to by - \p iter. +@brief Returns the name and the range of the current (signed) mapping + of the @enumftiter \p iter. -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. +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_field_type_enumeration_get_container_field_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. -@param[in] iter Enumeration mapping iterator. +On success, if \p name is not \c NULL, \p *name remains valid as long +as \p iter exists and +bt_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 mapping pointed to by - \p iter. -@param[out] range_end Returned end of the range (included) of - the mapping pointed to by \p iter. + (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} -@prenotnull{range_begin} -@prenotnull{range_end} @postrefcountsame{iter} -@sa bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(): Returns - the range of the unsigned enumeration mapping pointed by an enumeration - mapping iterator. +@sa bt_field_type_enumeration_mapping_iterator_unsigned_get(): + 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 **mapping_name, - int64_t *range_begin, int64_t *range_end); +extern int bt_field_type_enumeration_mapping_iterator_signed_get( + struct bt_field_type_enumeration_mapping_iterator *iter, + const char **name, int64_t *range_begin, int64_t *range_end); /** -@brief Returns the range of the unsigned @enumft mapping pointed to by - \p iter. +@brief Returns the name and the range of the current (unsigned) mapping + of the @enumftiter \p iter. -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. +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_field_type_enumeration_get_container_field_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_field_type_enumeration_mapping_iterator_next() is +\em not called on \p iter. -@param[in] iter Enumeration mapping iterator. +@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 mapping pointed to by - \p iter. -@param[out] range_end Returned end of the range (included) of - the mapping pointed to by \p iter. + (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} -@prenotnull{range_begin} -@prenotnull{range_end} @postrefcountsame{iter} -@sa bt_ctf_field_type_enumeration_mapping_iterator_get_signed(): Returns the - range of the signed enumeration mapping pointed by an enumeration - mapping iterator. +@sa + bt_field_type_enumeration_mapping_iterator_signed_get(): + 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 **mapping_name, - uint64_t *range_begin, uint64_t *range_end); +extern int bt_field_type_enumeration_mapping_iterator_unsigned_get( + struct bt_field_type_enumeration_mapping_iterator *iter, + const char **name, uint64_t *range_begin, uint64_t *range_end); /** -@brief Advance the position of the @enumiter \p iter. +@brief Advances the @enumftiter \p iter to the next mapping. -@param[in] iter Enumeration mapping iterator. -@returns 0 on success, or a negative value on error or - end of mappings set. +@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); +extern int bt_field_type_enumeration_mapping_iterator_next( + struct bt_field_type_enumeration_mapping_iterator *iter); /** @} */ @@ -1660,13 +1759,13 @@ A CTF IR string field type is a field type that you can use to create concrete @stringfields. You can create a string field type -with bt_ctf_field_type_string_create(). +with bt_field_type_string_create(). A string field type has only one property: the \b encoding of its described @stringfields. By default, the encoding of the string fields -described by a string field type is #BT_CTF_STRING_ENCODING_UTF8. You +described by a string field type is #BT_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(). +type with bt_field_type_string_set_encoding(). @sa ctfirstringfield @sa ctfirfieldtypes @@ -1682,7 +1781,7 @@ type with bt_ctf_field_type_string_set_encoding(). @postsuccessrefcountret1 */ -extern struct bt_ctf_field_type *bt_ctf_field_type_string_create(void); +extern struct bt_field_type *bt_field_type_string_create(void); /** @brief Returns the encoding of the @stringfields described by @@ -1693,18 +1792,18 @@ extern struct bt_ctf_field_type *bt_ctf_field_type_string_create(void); encoding. @returns Encoding of the string fields described by \p string_field_type, - or #BT_CTF_STRING_ENCODING_UNKNOWN on + or #BT_STRING_ENCODING_UNKNOWN on error. @prenotnull{string_field_type} @preisstringft{string_field_type} @postrefcountsame{string_field_type} -@sa bt_ctf_field_type_string_set_encoding(): Sets the encoding +@sa bt_field_type_string_set_encoding(): Sets the encoding of the string fields described by a given string field type. */ -extern enum bt_ctf_string_encoding bt_ctf_field_type_string_get_encoding( - struct bt_ctf_field_type *string_field_type); +extern enum bt_string_encoding bt_field_type_string_get_encoding( + struct bt_field_type *string_field_type); /** @brief Sets the encoding of the @stringfields described by the @@ -1720,16 +1819,16 @@ extern enum bt_ctf_string_encoding bt_ctf_field_type_string_get_encoding( @prenotnull{string_field_type} @preisstringft{string_field_type} @prehot{string_field_type} -@pre \p encoding is #BT_CTF_STRING_ENCODING_ASCII or - #BT_CTF_STRING_ENCODING_UTF8. +@pre \p encoding is #BT_STRING_ENCODING_ASCII or + #BT_STRING_ENCODING_UTF8. @postrefcountsame{string_field_type} -@sa bt_ctf_field_type_string_get_encoding(): Returns the encoding of +@sa bt_field_type_string_get_encoding(): Returns the encoding of the string fields described by a given string field type. */ -extern int bt_ctf_field_type_string_set_encoding( - struct bt_ctf_field_type *string_field_type, - enum bt_ctf_string_encoding encoding); +extern int bt_field_type_string_set_encoding( + struct bt_field_type *string_field_type, + enum bt_string_encoding encoding); /** @} */ @@ -1746,16 +1845,16 @@ A CTF IR structure field type is 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 +with bt_field_type_structure_create(). This function creates an empty structure field type, with no fields. You can add a field to a structure field type with -bt_ctf_field_type_structure_add_field(). Two fields in a structure +bt_field_type_structure_add_field(). Two fields in a structure field type cannot have the same name. You can set the \em minimum alignment of the structure fields described by a structure field type with the common -bt_ctf_field_type_set_alignment() function. The \em effective alignment +bt_field_type_set_alignment() function. The \em effective alignment of the structure fields described by a structure field type, as per CTF, is the \em maximum value amongst the effective alignments of all its fields. Note that the effective @@ -1763,7 +1862,7 @@ alignment of @varfields is always 1. You can set the byte order of all the contained fields, recursively, of a structure field type with the common -bt_ctf_field_type_set_byte_order() function. +bt_field_type_set_byte_order() function. @sa ctfirstructfield @sa ctfirfieldtypes @@ -1780,7 +1879,7 @@ bt_ctf_field_type_set_byte_order() function. @postsuccessrefcountret1 */ -extern struct bt_ctf_field_type *bt_ctf_field_type_structure_create(void); +extern struct bt_field_type *bt_field_type_structure_create(void); /** @brief Returns the number of fields contained in the @@ -1796,8 +1895,8 @@ extern struct bt_ctf_field_type *bt_ctf_field_type_structure_create(void); @preisstructft{struct_field_type} @postrefcountsame{struct_field_type} */ -extern int bt_ctf_field_type_structure_get_field_count( - struct bt_ctf_field_type *struct_field_type); +extern int64_t bt_field_type_structure_get_field_count( + struct bt_field_type *struct_field_type); /** @brief Returns the field of the @structft \p struct_field_type @@ -1822,18 +1921,18 @@ On success, the field's type is placed in \p *field_type if @preisstructft{struct_field_type} @pre \p index is lesser than the number of fields contained in the structure field type \p struct_field_type (see - bt_ctf_field_type_structure_get_field_count()). + bt_field_type_structure_get_field_count()). @postrefcountsame{struct_field_type} @post On success, the returned field's type is placed in \p *field_type and its reference count is incremented. -@sa bt_ctf_field_type_structure_get_field_type_by_name(): Finds a +@sa bt_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( - struct bt_ctf_field_type *struct_field_type, - const char **field_name, struct bt_ctf_field_type **field_type, - int index); +extern int bt_field_type_structure_get_field_by_index( + struct bt_field_type *struct_field_type, + const char **field_name, struct bt_field_type **field_type, + uint64_t index); /** @brief Returns the type of the field named \p field_name found in @@ -1852,12 +1951,12 @@ extern int bt_ctf_field_type_structure_get_field( @postrefcountsame{struct_field_type} @postsuccessrefcountretinc -@sa bt_ctf_field_type_structure_get_field(): Finds a +@sa bt_field_type_structure_get_field_by_index(): Finds a structure field type's field by index. */ extern -struct bt_ctf_field_type *bt_ctf_field_type_structure_get_field_type_by_name( - struct bt_ctf_field_type *struct_field_type, +struct bt_field_type *bt_field_type_structure_get_field_type_by_name( + struct bt_field_type *struct_field_type, const char *field_name); /** @@ -1891,9 +1990,9 @@ field named \p field_name in \p struct_field_type. @postrefcountsame{struct_field_type} @postsuccessrefcountinc{field_type} */ -extern int bt_ctf_field_type_structure_add_field( - struct bt_ctf_field_type *struct_field_type, - struct bt_ctf_field_type *field_type, +extern int bt_field_type_structure_add_field( + struct bt_field_type *struct_field_type, + struct bt_field_type *field_type, const char *field_name); /** @} */ @@ -1911,7 +2010,7 @@ A CTF IR array field type is a field type that you can use to create concrete @arrayfields. You can create an array field type -with bt_ctf_field_type_array_create(). This function needs +with bt_field_type_array_create(). This function needs the @ft of the fields contained by the array fields described by the array field type to create. @@ -1939,8 +2038,8 @@ array field type to create. @postsuccessrefcountinc{element_field_type} @postsuccessrefcountret1 */ -extern struct bt_ctf_field_type *bt_ctf_field_type_array_create( - struct bt_ctf_field_type *element_field_type, +extern struct bt_field_type *bt_field_type_array_create( + struct bt_field_type *element_field_type, unsigned int length); /** @@ -1960,8 +2059,8 @@ extern struct bt_ctf_field_type *bt_ctf_field_type_array_create( @postrefcountsame{array_field_type} @postsuccessrefcountretinc */ -extern struct bt_ctf_field_type *bt_ctf_field_type_array_get_element_type( - struct bt_ctf_field_type *array_field_type); +extern struct bt_field_type *bt_field_type_array_get_element_field_type( + struct bt_field_type *array_field_type); /** @brief Returns the number of @fields contained in the @@ -1979,8 +2078,8 @@ extern struct bt_ctf_field_type *bt_ctf_field_type_array_get_element_type( @preisarrayft{array_field_type} @postrefcountsame{array_field_type} */ -extern int64_t bt_ctf_field_type_array_get_length( - struct bt_ctf_field_type *array_field_type); +extern int64_t bt_field_type_array_get_length( + struct bt_field_type *array_field_type); /** @} */ @@ -1997,7 +2096,7 @@ A CTF IR sequence field type is 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 @ft +bt_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 @@ -2031,8 +2130,8 @@ about the automatic resolving. @postsuccessrefcountinc{element_field_type} @postsuccessrefcountret1 */ -extern struct bt_ctf_field_type *bt_ctf_field_type_sequence_create( - struct bt_ctf_field_type *element_field_type, +extern struct bt_field_type *bt_field_type_sequence_create( + struct bt_field_type *element_field_type, const char *length_name); /** @@ -2052,8 +2151,8 @@ extern struct bt_ctf_field_type *bt_ctf_field_type_sequence_create( @postrefcountsame{sequence_field_type} @postsuccessrefcountretinc */ -extern struct bt_ctf_field_type *bt_ctf_field_type_sequence_get_element_type( - struct bt_ctf_field_type *sequence_field_type); +extern struct bt_field_type *bt_field_type_sequence_get_element_field_type( + struct bt_field_type *sequence_field_type); /** @brief Returns the length name of the @seqft \p sequence_field_type. @@ -2069,11 +2168,11 @@ the returned string. @prenotnull{sequence_field_type} @preisseqft{sequence_field_type} -@sa bt_ctf_field_type_sequence_get_length_field_path(): Returns the +@sa bt_field_type_sequence_get_length_field_path(): Returns the length's CTF IR field path of a given sequence field type. */ -extern const char *bt_ctf_field_type_sequence_get_length_field_name( - struct bt_ctf_field_type *sequence_field_type); +extern const char *bt_field_type_sequence_get_length_field_name( + struct bt_field_type *sequence_field_type); /** @brief Returns the length's CTF IR field path of the @seqft @@ -2093,11 +2192,11 @@ resolving is performed (see \ref ctfirfieldtypes). @preisseqft{sequence_field_type} @postsuccessrefcountretinc -@sa bt_ctf_field_type_sequence_get_length_field_name(): Returns the +@sa bt_field_type_sequence_get_length_field_name(): Returns the length's name of a given sequence field type. */ -extern struct bt_ctf_field_path *bt_ctf_field_type_sequence_get_length_field_path( - struct bt_ctf_field_type *sequence_field_type); +extern struct bt_field_path *bt_field_type_sequence_get_length_field_path( + struct bt_field_type *sequence_field_type); /** @} */ @@ -2114,18 +2213,18 @@ A CTF IR variant field type is 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 +bt_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 +bt_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 +bt_field_type_variant_add_field(). All the field names of a variant field type \em must exist as mapping names in its tag's @enumft. The effective alignment of the @varfields described by a @@ -2134,7 +2233,7 @@ variant field type is always 1, but the individual fields of a You can set the byte order of all the contained fields, recursively, of a variant field type with the common -bt_ctf_field_type_set_byte_order() function. +bt_field_type_set_byte_order() function. @sa ctfirvarfield @sa ctfirfieldtypes @@ -2150,7 +2249,7 @@ bt_ctf_field_type_set_byte_order() function. \p tag_field_type can be \c NULL; the tag's field type can be automatically resolved from the variant field type's tag name (see \ref ctfirfieldtypes). If \p tag_name is \c NULL, it \em must be set -with bt_ctf_field_type_variant_set_tag_name() \em before the variant +with bt_field_type_variant_set_tag_name() \em before the variant field type is frozen. \p tag_name can be an absolute or relative reference. See @@ -2168,8 +2267,8 @@ field type is frozen. its reference count is incremented. @postsuccessrefcountret1 */ -extern struct bt_ctf_field_type *bt_ctf_field_type_variant_create( - struct bt_ctf_field_type *tag_field_type, +extern struct bt_field_type *bt_field_type_variant_create( + struct bt_field_type *tag_field_type, const char *tag_name); /** @@ -2187,8 +2286,8 @@ extern struct bt_ctf_field_type *bt_ctf_field_type_variant_create( @postrefcountsame{variant_field_type} @postsuccessrefcountretinc */ -extern struct bt_ctf_field_type *bt_ctf_field_type_variant_get_tag_type( - struct bt_ctf_field_type *variant_field_type); +extern struct bt_field_type *bt_field_type_variant_get_tag_field_type( + struct bt_field_type *variant_field_type); /** @brief Returns the tag name of the @varft \p variant_field_type. @@ -2205,13 +2304,13 @@ the returned string. @prenotnull{variant_field_type} @preisvarft{variant_field_type} -@sa bt_ctf_field_type_variant_set_tag_name(): Sets the tag name of +@sa bt_field_type_variant_set_tag_name(): Sets the tag name of a given variant field type. -@sa bt_ctf_field_type_variant_get_tag_field_path(): Returns the tag's +@sa bt_field_type_variant_get_tag_field_path(): Returns the tag's CTF IR field path of a given variant field type. */ -extern const char *bt_ctf_field_type_variant_get_tag_name( - struct bt_ctf_field_type *variant_field_type); +extern const char *bt_field_type_variant_get_tag_name( + struct bt_field_type *variant_field_type); /** @brief Sets the tag name of the @varft \p variant_field_type. @@ -2230,11 +2329,11 @@ extern const char *bt_ctf_field_type_variant_get_tag_name( @prehot{variant_field_type} @postrefcountsame{variant_field_type} -@sa bt_ctf_field_type_variant_get_tag_name(): Returns the tag name of +@sa bt_field_type_variant_get_tag_name(): Returns the tag name of a given variant field type. */ -extern int bt_ctf_field_type_variant_set_tag_name( - struct bt_ctf_field_type *variant_field_type, +extern int bt_field_type_variant_set_tag_name( + struct bt_field_type *variant_field_type, const char *tag_name); /** @@ -2255,11 +2354,11 @@ resolving is performed (see \ref ctfirfieldtypes). @preisvarft{variant_field_type} @postsuccessrefcountretinc -@sa bt_ctf_field_type_variant_get_tag_name(): Returns the tag's +@sa bt_field_type_variant_get_tag_name(): Returns the tag's name of a given variant field type. */ -extern struct bt_ctf_field_path *bt_ctf_field_type_variant_get_tag_field_path( - struct bt_ctf_field_type *variant_field_type); +extern struct bt_field_path *bt_field_type_variant_get_tag_field_path( + struct bt_field_type *variant_field_type); /** @brief Returns the number of fields (choices) contained in the @varft @@ -2275,8 +2374,8 @@ extern struct bt_ctf_field_path *bt_ctf_field_type_variant_get_tag_field_path( @preisvarft{variant_field_type} @postrefcountsame{variant_field_type} */ -extern int bt_ctf_field_type_variant_get_field_count( - struct bt_ctf_field_type *variant_field_type); +extern int64_t bt_field_type_variant_get_field_count( + struct bt_field_type *variant_field_type); /** @brief Returns the field (choice) of the @varft \p variant_field_type @@ -2301,20 +2400,20 @@ On success, the field's type is placed in \p *field_type if @preisvarft{variant_field_type} @pre \p index is lesser than the number of fields contained in the variant field type \p variant_field_type (see - bt_ctf_field_type_variant_get_field_count()). + bt_field_type_variant_get_field_count()). @postrefcountsame{variant_field_type} @post On success, the returned field's type is placed in \p *field_type and its reference count is incremented. -@sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant +@sa bt_field_type_variant_get_field_type_by_name(): Finds a variant field type's field by name. -@sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant +@sa bt_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( - struct bt_ctf_field_type *variant_field_type, +extern int bt_field_type_variant_get_field_by_index( + struct bt_field_type *variant_field_type, const char **field_name, - struct bt_ctf_field_type **field_type, int index); + struct bt_field_type **field_type, uint64_t index); /** @brief Returns the type of the field (choice) named \p field_name @@ -2333,14 +2432,14 @@ extern int bt_ctf_field_type_variant_get_field( @postrefcountsame{variant_field_type} @postsuccessrefcountretinc -@sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's +@sa bt_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 +@sa bt_field_type_variant_get_field_type_from_tag(): Finds a variant field type's field by current tag value. */ extern -struct bt_ctf_field_type *bt_ctf_field_type_variant_get_field_type_by_name( - struct bt_ctf_field_type *variant_field_type, +struct bt_field_type *bt_field_type_variant_get_field_type_by_name( + struct bt_field_type *variant_field_type, const char *field_name); /** @@ -2349,9 +2448,9 @@ struct bt_ctf_field_type *bt_ctf_field_type_variant_get_field_type_by_name( \p tag_field is the current tag value. -The field type of \p tag_field, as returned by bt_ctf_field_get_type(), +The field type of \p tag_field, as returned by bt_field_get_type(), \em must be equivalent to the field type returned by -bt_ctf_field_type_variant_get_tag_type() for \p variant_field_type. +bt_field_type_variant_get_tag_field_type() for \p variant_field_type. @param[in] variant_field_type Variant field type of which to get a field's type. @@ -2369,15 +2468,15 @@ bt_ctf_field_type_variant_get_tag_type() for \p variant_field_type. @postrefcountsame{tag_field} @postsuccessrefcountretinc -@sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's +@sa bt_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 +@sa bt_field_type_variant_get_field_type_by_name(): Finds a variant field type's field by name. */ extern -struct bt_ctf_field_type *bt_ctf_field_type_variant_get_field_type_from_tag( - struct bt_ctf_field_type *variant_field_type, - struct bt_ctf_field *tag_field); +struct bt_field_type *bt_field_type_variant_get_field_type_from_tag( + struct bt_field_type *variant_field_type, + struct bt_field *tag_field); /** @brief Adds a field (a choice) named \p field_name with the @ft @@ -2410,9 +2509,9 @@ enumeration field type of \p variant_field_type. @postrefcountsame{variant_field_type} @postsuccessrefcountinc{field_type} */ -extern int bt_ctf_field_type_variant_add_field( - struct bt_ctf_field_type *variant_field_type, - struct bt_ctf_field_type *field_type, +extern int bt_field_type_variant_add_field( + struct bt_field_type *variant_field_type, + struct bt_field_type *field_type, const char *field_name); /** @} */