1 #ifndef BABELTRACE_CTF_IR_FIELD_TYPES_H
2 #define BABELTRACE_CTF_IR_FIELD_TYPES_H
5 * BabelTrace - CTF IR: Event field types
7 * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
9 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
11 * Permission is hereby granted, free of charge, to any person obtaining a copy
12 * of this software and associated documentation files (the "Software"), to deal
13 * in the Software without restriction, including without limitation the rights
14 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15 * copies of the Software, and to permit persons to whom the Software is
16 * furnished to do so, subject to the following conditions:
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
29 * The Common Trace Format (CTF) Specification is available at
30 * http://www.efficios.com/ctf
41 @defgroup ctfirfieldtypes CTF IR field types
43 @brief CTF IR field types.
46 #include <babeltrace/ctf-ir/field-types.h>
49 A CTF IR <strong><em>field type</em></strong> is a field type that you
50 can use to create concrete @fields.
52 You can create a @field object from a CTF IR field type object
53 with bt_ctf_field_create().
55 In the CTF IR hierarchy, you can set the root field types of three
58 - \ref ctfirtraceclass
59 - Trace packet header field type: bt_ctf_trace_set_packet_header_type().
60 - \ref ctfirstreamclass
61 - Stream packet context field type:
62 bt_ctf_stream_class_set_packet_context_type().
63 - Stream event header field type:
64 bt_ctf_stream_class_set_event_header_type().
65 - Stream event context field type:
66 bt_ctf_stream_class_set_event_context_type().
67 - \ref ctfireventclass
68 - Event context field type: bt_ctf_event_class_set_context_type().
69 - Event payload field type: bt_ctf_event_class_set_payload_type().
71 As of Babeltrace \btversion, those six previous "root" field types
72 \em must be @structft objects.
74 If, at any level within a given root field type, you add a @seqft or a
75 @varft, you do not need to specify its associated length
76 or tag field type: the length or tag string is enough for the Babeltrace
77 system to resolve the needed field type depending on where this
78 dynamic field type is located within the whole hierarchy. It is
79 guaranteed that this automatic resolving is performed for all the field
80 types contained in a given
81 \link ctfirstreamclass CTF IR stream class\endlink (and in its
82 children \link ctfireventclass CTF IR event classes\endlink) once you
83 add it to a \link ctfirtraceclass CTF IR trace class\endlink with
84 bt_ctf_trace_add_stream_class(). Once a stream class is the child of
85 a trace class, this automatic resolving is performed for the field
86 types of an event class when you add it with
87 bt_ctf_stream_class_add_event_class(). If the system cannot find a path
88 to a field in the hierarchy for a dynamic field type, the adding
91 The standard CTF field types are:
97 <th>CTF IR field which you can create from this field type
100 <td>#BT_CTF_FIELD_TYPE_ID_INTEGER
101 <td>\ref ctfirintfieldtype
102 <td>\ref ctfirintfield
105 <td>#BT_CTF_FIELD_TYPE_ID_FLOAT
106 <td>\ref ctfirfloatfieldtype
107 <td>\ref ctfirfloatfield
110 <td>#BT_CTF_FIELD_TYPE_ID_ENUM
111 <td>\ref ctfirenumfieldtype
112 <td>\ref ctfirenumfield
115 <td>#BT_CTF_FIELD_TYPE_ID_STRING
116 <td>\ref ctfirstringfieldtype
117 <td>\ref ctfirstringfield
120 <td>#BT_CTF_FIELD_TYPE_ID_STRUCT
121 <td>\ref ctfirstructfieldtype
122 <td>\ref ctfirstructfield
125 <td>#BT_CTF_FIELD_TYPE_ID_ARRAY
126 <td>\ref ctfirarrayfieldtype
127 <td>\ref ctfirarrayfield
130 <td>#BT_CTF_FIELD_TYPE_ID_SEQUENCE
131 <td>\ref ctfirseqfieldtype
132 <td>\ref ctfirseqfield
135 <td>#BT_CTF_FIELD_TYPE_ID_VARIANT
136 <td>\ref ctfirvarfieldtype
137 <td>\ref ctfirvarfield
141 Each field type has its own <strong>type ID</strong> (see
142 #bt_ctf_field_type_id). You get the type ID of a field type object
143 with bt_ctf_field_type_get_type_id().
145 You can get a deep copy of a field type with bt_ctf_field_type_copy().
146 This function resets, in the field type copy, the resolved field type
147 of the dynamic field types. The automatic resolving can be done again
148 when you eventually call bt_ctf_event_create(),
149 bt_ctf_stream_class_add_event_class(), or
150 bt_ctf_trace_add_stream_class().
152 You \em must always use bt_ctf_field_type_compare() to compare two
153 field types. Since some parts of the Babeltrace system can copy field
154 types behind the scenes, you \em cannot rely on a simple field type
157 As with any Babeltrace object, CTF IR field type objects have
158 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
159 counts</a>. See \ref refs to learn more about the reference counting
160 management of Babeltrace objects.
162 The following functions can \em freeze field type objects:
164 - bt_ctf_field_create() freezes its field type parameter.
165 - bt_ctf_stream_class_add_event_class(), if its
166 \link ctfirstreamclass CTF IR stream class\endlink parameter has a
167 \link ctfirtraceclass CTF IR trace class\endlink parent, freezes
168 the root field types of its
169 \link ctfireventclass CTF IR event class\endlink parameter.
170 - bt_ctf_trace_add_stream_class() freezes the root field types of the
171 whole trace class hierarchy (trace class, children stream classes,
172 and their children event classes).
173 - bt_ctf_writer_create_stream() freezes the root field types of the
174 whole CTF writer's trace class hierarchy.
175 - bt_ctf_event_create() freezes the root field types of its event class
176 parameter and of ther parent stream class of this event class.
178 You cannot modify a frozen field type object: it is considered
179 immutable, except for \link refs reference counting\endlink.
182 @sa \ref ctfirfieldtypesexamples "Examples"
185 @brief CTF IR field types type and functions.
188 @addtogroup ctfirfieldtypes
193 @struct bt_ctf_field_type
194 @brief A CTF IR field type.
197 struct bt_ctf_field_type
;
198 struct bt_ctf_event_class
;
201 struct bt_ctf_field_path
;
202 struct bt_ctf_field_type_enumeration_mapping_iterator
;
204 /** @cond DOCUMENT */
207 * Babeltrace 1.x enumerations that were also used in CTF writer's API.
208 * They are left here for backward compatibility reasons, but
209 * enum bt_ctf_field_type_id and enum bt_ctf_string_encoding should be used
210 * in new code. Both new enumerations are compatible with their legacy
214 CTF_TYPE_UNKNOWN
= 0,
220 CTF_TYPE_UNTAGGED_VARIANT
,
230 enum ctf_string_encoding
{
243 /// Unknown, used for errors.
244 BT_CTF_SCOPE_UNKNOWN
= -1,
246 /// Trace packet header.
247 BT_CTF_SCOPE_TRACE_PACKET_HEADER
= 1,
249 /// Stream packet context.
250 BT_CTF_SCOPE_STREAM_PACKET_CONTEXT
= 2,
252 /// Stream event header.
253 BT_CTF_SCOPE_STREAM_EVENT_HEADER
= 3,
255 /// Stream event context.
256 BT_CTF_SCOPE_STREAM_EVENT_CONTEXT
= 4,
259 BT_CTF_SCOPE_EVENT_CONTEXT
= 5,
262 BT_CTF_SCOPE_EVENT_PAYLOAD
= 6,
265 BT_CTF_SCOPE_ENV
= 0,
266 BT_CTF_SCOPE_EVENT_FIELDS
= 6,
271 @name Type information
276 @brief Type ID of a @ft.
278 enum bt_ctf_field_type_id
{
279 /// Unknown, used for errors.
280 BT_CTF_FIELD_TYPE_ID_UNKNOWN
= CTF_TYPE_UNKNOWN
,
282 /// \ref ctfirintfieldtype
283 BT_CTF_FIELD_TYPE_ID_INTEGER
= CTF_TYPE_INTEGER
,
285 /// \ref ctfirfloatfieldtype
286 BT_CTF_FIELD_TYPE_ID_FLOAT
= CTF_TYPE_FLOAT
,
288 /// \ref ctfirenumfieldtype
289 BT_CTF_FIELD_TYPE_ID_ENUM
= CTF_TYPE_ENUM
,
291 /// \ref ctfirstringfieldtype
292 BT_CTF_FIELD_TYPE_ID_STRING
= CTF_TYPE_STRING
,
294 /// \ref ctfirstructfieldtype
295 BT_CTF_FIELD_TYPE_ID_STRUCT
= CTF_TYPE_STRUCT
,
298 BT_CTF_TYPE_ID_UNTAGGED_VARIANT
= CTF_TYPE_UNTAGGED_VARIANT
,
301 /// \ref ctfirarrayfieldtype
302 BT_CTF_FIELD_TYPE_ID_ARRAY
= CTF_TYPE_ARRAY
,
304 /// \ref ctfirseqfieldtype
305 BT_CTF_FIELD_TYPE_ID_SEQUENCE
= CTF_TYPE_SEQUENCE
,
307 /// \ref ctfirvarfieldtype
308 BT_CTF_FIELD_TYPE_ID_VARIANT
= CTF_TYPE_VARIANT
,
310 /// Number of enumeration entries.
311 BT_CTF_NR_TYPE_IDS
= NR_CTF_TYPES
,
315 @brief Returns the type ID of the @ft \p field_type.
317 @param[in] field_type Field type of which to get the type ID.
318 @returns Type ID of \p field_type,
319 or #BT_CTF_FIELD_TYPE_ID_UNKNOWN on error.
321 @prenotnull{field_type}
322 @postrefcountsame{field_type}
324 @sa #bt_ctf_field_type_id: CTF IR field type ID.
325 @sa bt_ctf_field_type_is_integer(): Returns whether or not a given
326 field type is a @intft.
327 @sa bt_ctf_field_type_is_floating_point(): Returns whether or not a
328 given field type is a @floatft.
329 @sa bt_ctf_field_type_is_enumeration(): Returns whether or not a given
330 field type is a @enumft.
331 @sa bt_ctf_field_type_is_string(): Returns whether or not a given
332 field type is a @stringft.
333 @sa bt_ctf_field_type_is_structure(): Returns whether or not a given
334 field type is a @structft.
335 @sa bt_ctf_field_type_is_array(): Returns whether or not a given
336 field type is a @arrayft.
337 @sa bt_ctf_field_type_is_sequence(): Returns whether or not a given
338 field type is a @seqft.
339 @sa bt_ctf_field_type_is_variant(): Returns whether or not a given
340 field type is a @varft.
342 extern enum bt_ctf_field_type_id
bt_ctf_field_type_get_type_id(
343 struct bt_ctf_field_type
*field_type
);
346 @brief Returns whether or not the @ft \p field_type is a @intft.
348 @param[in] field_type Field type to check (can be \c NULL).
349 @returns 1 if \p field_type is an integer field type,
350 or 0 otherwise (including if \p field_type is
353 @prenotnull{field_type}
354 @postrefcountsame{field_type}
356 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
359 extern int bt_ctf_field_type_is_integer(struct bt_ctf_field_type
*field_type
);
362 @brief Returns whether or not the @ft \p field_type is a @floatft.
364 @param[in] field_type Field type to check (can be \c NULL).
365 @returns 1 if \p field_type is a floating point
367 or 0 otherwise (including if \p field_type is
370 @postrefcountsame{field_type}
372 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
375 extern int bt_ctf_field_type_is_floating_point(struct bt_ctf_field_type
*field_type
);
378 @brief Returns whether or not the @ft \p field_type is a @enumft.
380 @param[in] field_type Field type to check (can be \c NULL).
381 @returns 1 if \p field_type is an enumeration field type,
382 or 0 otherwise (including if \p field_type is
385 @postrefcountsame{field_type}
387 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
390 extern int bt_ctf_field_type_is_enumeration(struct bt_ctf_field_type
*field_type
);
393 @brief Returns whether or not the @ft \p field_type is a @stringft.
395 @param[in] field_type Field type to check (can be \c NULL).
396 @returns 1 if \p field_type is a string field type,
397 or 0 otherwise (including if \p field_type is
400 @postrefcountsame{field_type}
402 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
405 extern int bt_ctf_field_type_is_string(struct bt_ctf_field_type
*field_type
);
408 @brief Returns whether or not the @ft \p field_type is a @structft.
410 @param[in] field_type Field type to check (can be \c NULL).
411 @returns 1 if \p field_type is a structure field type,
412 or 0 otherwise (including if \p field_type is
415 @postrefcountsame{field_type}
417 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
420 extern int bt_ctf_field_type_is_structure(struct bt_ctf_field_type
*field_type
);
423 @brief Returns whether or not the @ft \p field_type is a @arrayft.
425 @param[in] field_type Field type to check (can be \c NULL).
426 @returns 1 if \p field_type is an array field type,
427 or 0 otherwise (including if \p field_type is
430 @postrefcountsame{field_type}
432 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
435 extern int bt_ctf_field_type_is_array(struct bt_ctf_field_type
*field_type
);
438 @brief Returns whether or not the @ft \p field_type is a @seqft.
440 @param[in] field_type Field type to check (can be \c NULL).
441 @returns 1 if \p field_type is a sequence field type,
442 or 0 otherwise (including if \p field_type is
445 @postrefcountsame{field_type}
447 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
450 extern int bt_ctf_field_type_is_sequence(struct bt_ctf_field_type
*field_type
);
453 @brief Returns whether or not the @ft \p field_type is a @varft.
455 @param[in] field_type Field type to check (can be \c NULL).
456 @returns 1 if \p field_type is a variant field type,
457 or 0 otherwise (including if \p field_type is
460 @postrefcountsame{field_type}
462 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
465 extern int bt_ctf_field_type_is_variant(struct bt_ctf_field_type
*field_type
);
470 @name Common properties types and functions
475 @brief <a href="https://en.wikipedia.org/wiki/Endianness">Byte order</a>
478 enum bt_ctf_byte_order
{
479 /// Unknown, used for errors.
480 BT_CTF_BYTE_ORDER_UNKNOWN
= -1,
483 * Note that native, in the context of the CTF specification, is defined
484 * as "the byte order described in the trace" and does not mean that the
485 * host's endianness will be used.
487 /// Native (default) byte order.
488 BT_CTF_BYTE_ORDER_NATIVE
= 0,
491 BT_CTF_BYTE_ORDER_LITTLE_ENDIAN
,
494 BT_CTF_BYTE_ORDER_BIG_ENDIAN
,
496 /// Network byte order (big-endian).
497 BT_CTF_BYTE_ORDER_NETWORK
,
501 @brief String encoding of a @ft.
503 enum bt_ctf_string_encoding
{
504 /// Unknown, used for errors.
505 BT_CTF_STRING_ENCODING_UNKNOWN
= CTF_STRING_UNKNOWN
,
508 BT_CTF_STRING_ENCODING_NONE
= CTF_STRING_NONE
,
510 /// <a href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a>.
511 BT_CTF_STRING_ENCODING_UTF8
= CTF_STRING_UTF8
,
513 /// <a href="https://en.wikipedia.org/wiki/ASCII">ASCII</a>.
514 BT_CTF_STRING_ENCODING_ASCII
= CTF_STRING_ASCII
,
518 @brief Returns the alignment of the @fields described by
519 the @ft \p field_type.
521 @param[in] field_type Field type which describes the
522 fields of which to get the alignment.
523 @returns Alignment of the fields described by
524 \p field_type, or a negative value on error.
526 @prenotnull{field_type}
527 @postrefcountsame{field_type}
529 @sa bt_ctf_field_type_set_alignment(): Sets the alignment
530 of the fields described by a given field type.
532 extern int bt_ctf_field_type_get_alignment(
533 struct bt_ctf_field_type
*field_type
);
536 @brief Sets the alignment of the @fields described by the
537 @ft \p field_type to \p alignment.
539 \p alignment \em must be greater than 0 and a power of two.
541 @param[in] field_type Field type which describes the fields of
542 which to set the alignment.
543 @param[in] alignment Alignment of the fields described by
545 @returns 0 on success, or a negative value on error.
547 @prenotnull{field_type}
549 @pre \p alignment is greater than 0 and a power of two.
550 @postrefcountsame{field_type}
552 @sa bt_ctf_field_type_get_alignment(): Returns the alignment of the
553 fields described by a given field type.
555 extern int bt_ctf_field_type_set_alignment(struct bt_ctf_field_type
*field_type
,
556 unsigned int alignment
);
559 @brief Returns the byte order of the @fields described by
560 the @ft \p field_type.
562 You can only call this function if \p field_type is a @intft, a
563 @floatft, or a @enumft.
565 @param[in] field_type Field type which describes the
566 fields of which to get the byte order.
567 @returns Byte order of the fields described by
568 \p field_type, or #BT_CTF_BYTE_ORDER_UNKNOWN on
571 @prenotnull{field_type}
572 @pre \p field_type is a @intft, a @floatft, or a @enumft.
573 @postrefcountsame{field_type}
575 @sa bt_ctf_field_type_set_byte_order(): Sets the byte order
576 of the fields described by a given field type.
578 extern enum bt_ctf_byte_order
bt_ctf_field_type_get_byte_order(
579 struct bt_ctf_field_type
*field_type
);
582 @brief Sets the byte order of the @fields described by the
583 @ft \p field_type to \p byte_order.
585 If \p field_type is a compound field type, this function also
586 recursively sets the byte order of its children to \p byte_order.
588 @param[in] field_type Field type which describes the fields of
589 which to set the byte order.
590 @param[in] byte_order Alignment of the fields described by
592 @returns 0 on success, or a negative value on error.
594 @prenotnull{field_type}
596 @pre \p byte_order is #BT_CTF_BYTE_ORDER_NATIVE,
597 #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN, #BT_CTF_BYTE_ORDER_BIG_ENDIAN,
598 or #BT_CTF_BYTE_ORDER_NETWORK.
599 @postrefcountsame{field_type}
601 @sa bt_ctf_field_type_get_byte_order(): Returns the byte order of the
602 fields described by a given field type.
604 extern int bt_ctf_field_type_set_byte_order(
605 struct bt_ctf_field_type
*field_type
,
606 enum bt_ctf_byte_order byte_order
);
611 @name Utility functions
616 @brief Returns whether or not the @ft \p field_type_a
617 is equivalent to the field type \p field_type_b.
619 You \em must use this function to compare two field types: it is not
620 safe to compare two pointer values directly, because, for internal
621 reasons, some parts of the Babeltrace system can copy user field types
622 and discard the original ones.
624 @param[in] field_type_a Field type to compare to \p field_type_b.
625 @param[in] field_type_b Field type to compare to \p field_type_a.
626 @returns 0 if \p field_type_a is equivalent to
627 \p field_type_b, 1 if they are not equivalent,
628 or a negative value on error.
630 @prenotnull{field_type_a}
631 @prenotnull{field_type_b}
632 @postrefcountsame{field_type_a}
633 @postrefcountsame{field_type_b}
635 extern int bt_ctf_field_type_compare(struct bt_ctf_field_type
*field_type_a
,
636 struct bt_ctf_field_type
*field_type_b
);
639 @brief Creates a \em deep copy of the @ft \p field_type.
641 You can copy a frozen field type: the resulting copy is
644 This function resets the tag field type of a copied @varft. The
645 automatic field resolving which some functions of the API perform
646 can set it again when the returned field type is used (learn more
647 in the detailed description of this module).
649 @param[in] field_type Field type to copy.
650 @returns Deep copy of \p field_type on success,
653 @prenotnull{field_type}
654 @postrefcountsame{field_type}
655 @postsuccessrefcountret1
656 @post <strong>On success</strong>, the returned field type is not frozen.
658 extern struct bt_ctf_field_type
*bt_ctf_field_type_copy(
659 struct bt_ctf_field_type
*field_type
);
666 @defgroup ctfirintfieldtype CTF IR integer field type
667 @ingroup ctfirfieldtypes
668 @brief CTF IR integer field type.
671 #include <babeltrace/ctf-ir/field-types.h>
674 A CTF IR <strong><em>integer field type</em></strong> is a field type that
675 you can use to create concrete @intfield objects.
677 You can create an integer field type
678 with bt_ctf_field_type_integer_create().
680 An integer field type has the following properties:
685 <th>Value at creation
690 <td>\b Alignment (bits) of the described integer fields
692 <td>bt_ctf_field_type_get_alignment()
693 <td>bt_ctf_field_type_set_alignment()
696 <td><strong>Byte order</strong> of the described integer fields
697 <td>#BT_CTF_BYTE_ORDER_NATIVE
698 <td>bt_ctf_field_type_get_byte_order()
699 <td>bt_ctf_field_type_set_byte_order()
702 <td><strong>Storage size</strong> (bits) of the described
704 <td>Specified at creation
705 <td>bt_ctf_field_type_integer_get_size()
706 <td>bt_ctf_field_type_integer_set_size()
709 <td><strong>Signedness</strong> of the described integer fields
711 <td>bt_ctf_field_type_integer_is_signed()
712 <td>bt_ctf_field_type_integer_set_is_signed()
715 <td><strong>Preferred display base</strong> of the described
717 <td>#BT_CTF_INTEGER_BASE_DECIMAL
718 <td>bt_ctf_field_type_integer_get_base()
719 <td>bt_ctf_field_type_integer_set_base()
722 <td>\b Encoding of the described integer fields
723 <td>#BT_CTF_STRING_ENCODING_NONE
724 <td>bt_ctf_field_type_integer_get_encoding()
725 <td>bt_ctf_field_type_integer_set_encoding()
729 \link ctfirclockclass CTF IR clock class\endlink</strong>
731 <td>bt_ctf_field_type_integer_get_mapped_clock_class()
732 <td>bt_ctf_field_type_integer_set_mapped_clock_class()
738 @sa \ref ctfirfieldtypesexamples_intfieldtype "Examples"
740 @addtogroup ctfirintfieldtype
745 @brief Preferred display base (radix) of a @intft.
747 enum bt_ctf_integer_base
{
748 /// Unknown, used for errors.
749 BT_CTF_INTEGER_BASE_UNKNOWN
= -1,
752 BT_CTF_INTEGER_BASE_BINARY
= 2,
755 BT_CTF_INTEGER_BASE_OCTAL
= 8,
758 BT_CTF_INTEGER_BASE_DECIMAL
= 10,
761 BT_CTF_INTEGER_BASE_HEXADECIMAL
= 16,
765 @brief Creates a default @intft with \p size bits as the storage size
766 of the @intfields it describes.
768 You can change the storage size of the integer fields described by
769 the created integer field type later with
770 bt_ctf_field_type_integer_set_size().
772 @param[in] size Storage size (bits) of the described integer fields.
773 @returns Created integer field type, or \c NULL on error.
775 @pre \p size is greater than 0 and lesser than or equal to 64.
776 @postsuccessrefcountret1
778 extern struct bt_ctf_field_type
*bt_ctf_field_type_integer_create(
782 @brief Returns the storage size, in bits, of the @intfields
783 described by the @intft \p int_field_type.
785 @param[in] int_field_type Integer field type which describes the
786 integer fields of which to get the
788 @returns Storage size (bits) of the integer
789 fields described by \p int_field_type,
790 or a negative value on error.
792 @prenotnull{int_field_type}
793 @preisintft{int_field_type}
794 @postrefcountsame{int_field_type}
796 @sa bt_ctf_field_type_integer_set_size(): Sets the storage size of the
797 integer fields described by a given integer field type.
799 extern int bt_ctf_field_type_integer_get_size(
800 struct bt_ctf_field_type
*int_field_type
);
803 @brief Sets the storage size, in bits, of the @intfields described by
804 the @intft \p int_field_type.
806 @param[in] int_field_type Integer field type which describes the
807 integer fields of which to set the
809 @param[in] size Storage size (bits) of the integer fields
810 described by \p int_field_type.
811 @returns 0 on success, or a negative value on error.
813 @prenotnull{int_field_type}
814 @preisintft{int_field_type}
815 @prehot{int_field_type}
816 @pre \p size is greater than 0 and lesser than or equal to 64.
817 @postrefcountsame{int_field_type}
819 @sa bt_ctf_field_type_integer_get_size(): Returns the storage size of
820 the integer fields described by a given integer field type.
822 extern int bt_ctf_field_type_integer_set_size(
823 struct bt_ctf_field_type
*int_field_type
, size_t size
);
826 @brief Returns whether or not the @intfields described by the @intft
827 \p int_field_type are signed.
829 @param[in] int_field_type Integer field type which describes the
830 integer fields of which to get the
832 @returns 1 if the integer fields described by
833 \p int_field_type are signed, 0 if they
834 are unsigned, or a negative value on
837 @prenotnull{int_field_type}
838 @preisintft{int_field_type}
839 @postrefcountsame{int_field_type}
841 @sa bt_ctf_field_type_integer_set_is_signed(): Sets the signedness of the
842 integer fields described by a given integer field type.
844 extern int bt_ctf_field_type_integer_is_signed(
845 struct bt_ctf_field_type
*int_field_type
);
847 /* Pre-2.0 CTF writer compatibility */
848 #define bt_ctf_field_type_integer_get_signed bt_ctf_field_type_integer_is_signed
851 @brief Sets whether or not the @intfields described by
852 the @intft \p int_field_type are signed.
854 @param[in] int_field_type Integer field type which describes the
855 integer fields of which to set the
857 @param[in] is_signed Signedness of the integer fields
858 described by \p int_field_type; 0 means
859 \em unsigned, 1 means \em signed.
860 @returns 0 on success, or a negative value on error.
862 @prenotnull{int_field_type}
863 @preisintft{int_field_type}
864 @prehot{int_field_type}
865 @pre \p is_signed is 0 or 1.
866 @postrefcountsame{int_field_type}
868 @sa bt_ctf_field_type_integer_is_signed(): Returns the signedness of
869 the integer fields described by a given integer field type.
871 extern int bt_ctf_field_type_integer_set_is_signed(
872 struct bt_ctf_field_type
*int_field_type
, int is_signed
);
874 /* Pre-2.0 CTF writer compatibility */
875 #define bt_ctf_field_type_integer_set_signed bt_ctf_field_type_integer_set_is_signed
878 @brief Returns the preferred display base (radix) of the @intfields
879 described by the @intft \p int_field_type.
881 @param[in] int_field_type Integer field type which describes the
882 integer fields of which to get the
883 preferred display base.
884 @returns Preferred display base of the integer
885 fields described by \p int_field_type,
886 or #BT_CTF_INTEGER_BASE_UNKNOWN on
889 @prenotnull{int_field_type}
890 @preisintft{int_field_type}
891 @postrefcountsame{int_field_type}
893 @sa bt_ctf_field_type_integer_set_base(): Sets the preferred display
894 base of the integer fields described by a given integer field
897 extern enum bt_ctf_integer_base
bt_ctf_field_type_integer_get_base(
898 struct bt_ctf_field_type
*int_field_type
);
901 @brief Sets the preferred display base (radix) of the @intfields
902 described by the @intft \p int_field_type to \p base.
904 @param[in] int_field_type Integer field type which describes the
905 integer fields of which to set the
906 preferred display base.
907 @param[in] base Preferred display base of the integer
908 fields described by \p int_field_type.
909 @returns 0 on success, or a negative value on error.
911 @prenotnull{int_field_type}
912 @preisintft{int_field_type}
913 @prehot{int_field_type}
914 @pre \p base is #BT_CTF_INTEGER_BASE_BINARY, #BT_CTF_INTEGER_BASE_OCTAL,
915 #BT_CTF_INTEGER_BASE_DECIMAL, or
916 #BT_CTF_INTEGER_BASE_HEXADECIMAL.
917 @postrefcountsame{int_field_type}
919 @sa bt_ctf_field_type_integer_get_base(): Returns the preferred display
920 base of the integer fields described by a given
923 extern int bt_ctf_field_type_integer_set_base(
924 struct bt_ctf_field_type
*int_field_type
,
925 enum bt_ctf_integer_base base
);
928 @brief Returns the encoding of the @intfields described by
929 the @intft \p int_field_type.
931 @param[in] int_field_type Integer field type which describes the
932 integer fields of which to get the
934 @returns Encoding of the integer
935 fields described by \p int_field_type,
936 or #BT_CTF_STRING_ENCODING_UNKNOWN on
939 @prenotnull{int_field_type}
940 @preisintft{int_field_type}
941 @postrefcountsame{int_field_type}
943 @sa bt_ctf_field_type_integer_set_encoding(): Sets the encoding
944 of the integer fields described by a given integer field type.
946 extern enum bt_ctf_string_encoding
bt_ctf_field_type_integer_get_encoding(
947 struct bt_ctf_field_type
*int_field_type
);
950 @brief Sets the encoding of the @intfields described by the @intft
951 \p int_field_type to \p encoding.
953 You can use this property, in CTF IR, to create "text" @arrayfts or
954 @seqfts. A text array field type is array field type with an unsigned,
955 8-bit integer field type having an encoding as its element field type.
957 @param[in] int_field_type Integer field type which describes the
958 integer fields of which to set the
960 @param[in] encoding Encoding of the integer
961 fields described by \p int_field_type.
962 @returns 0 on success, or a negative value on error.
964 @prenotnull{int_field_type}
965 @preisintft{int_field_type}
966 @prehot{int_field_type}
967 @pre \p encoding is #BT_CTF_STRING_ENCODING_NONE,
968 #BT_CTF_STRING_ENCODING_ASCII, or
969 #BT_CTF_STRING_ENCODING_UTF8.
970 @postrefcountsame{int_field_type}
972 @sa bt_ctf_field_type_integer_get_encoding(): Returns the encoding of
973 the integer fields described by a given integer field type.
975 extern int bt_ctf_field_type_integer_set_encoding(
976 struct bt_ctf_field_type
*int_field_type
,
977 enum bt_ctf_string_encoding encoding
);
980 @brief Returns the \link ctfirclockclass CTF IR clock class\endlink
981 mapped to the @intft \p int_field_type.
983 The mapped clock class, if any, indicates the class of the clock which
984 an @intfield described by \p int_field_type should sample or update.
985 This mapped clock class is only indicative.
987 @param[in] int_field_type Integer field type of which to get the
989 @returns Mapped clock class of \p int_field_type,
990 or \c NULL if there's no mapped clock
993 @prenotnull{int_field_type}
994 @preisintft{int_field_type}
995 @postrefcountsame{int_field_type}
996 @postsuccessrefcountretinc
998 @sa bt_ctf_field_type_integer_set_mapped_clock_class(): Sets the mapped
999 clock class of a given integer field type.
1001 extern struct bt_ctf_clock_class
*bt_ctf_field_type_integer_get_mapped_clock_class(
1002 struct bt_ctf_field_type
*int_field_type
);
1005 @brief Sets the \link ctfirclockclass CTF IR clock class\endlink mapped
1006 to the @intft \p int_field_type to \p clock_class.
1008 The mapped clock class, if any, indicates the class of the clock which
1009 an integer field described by \p int_field_type should sample or update.
1010 This mapped clock class is only indicative.
1012 @param[in] int_field_type Integer field type of which to set the
1014 @param[in] clock_class Mapped clock class of \p int_field_type.
1015 @returns 0 on success, or a negative value on error.
1017 @prenotnull{int_field_type}
1018 @prenotnull{clock_class}
1019 @preisintft{int_field_type}
1020 @prehot{int_field_type}
1021 @postrefcountsame{int_field_type}
1022 @postsuccessrefcountinc{clock_class}
1024 @sa bt_ctf_field_type_integer_get_mapped_clock_class(): Returns the mapped
1025 clock class of a given integer field type.
1027 extern int bt_ctf_field_type_integer_set_mapped_clock_class(
1028 struct bt_ctf_field_type
*int_field_type
,
1029 struct bt_ctf_clock_class
*clock_class
);
1034 @defgroup ctfirfloatfieldtype CTF IR floating point number field type
1035 @ingroup ctfirfieldtypes
1036 @brief CTF IR floating point number field type.
1039 #include <babeltrace/ctf-ir/field-types.h>
1042 A CTF IR <strong><em>floating point number field type</em></strong> is
1043 a field type that you can use to create concrete @floatfields.
1045 You can create a floating point number field type
1046 with bt_ctf_field_type_floating_point_create().
1048 A floating point number field type has the following properties:
1053 <th>Value at creation
1058 <td>\b Alignment (bits) of the described floating point
1061 <td>bt_ctf_field_type_get_alignment()
1062 <td>bt_ctf_field_type_set_alignment()
1065 <td><strong>Byte order</strong> of the described floating point
1067 <td>#BT_CTF_BYTE_ORDER_NATIVE
1068 <td>bt_ctf_field_type_get_byte_order()
1069 <td>bt_ctf_field_type_set_byte_order()
1072 <td><strong>Exponent storage size</strong> (bits) of the described
1073 floating point number fields
1075 <td>bt_ctf_field_type_floating_point_get_exponent_digits()
1076 <td>bt_ctf_field_type_floating_point_set_exponent_digits()
1079 <td><strong>Mantissa and sign storage size</strong> (bits) of the
1080 described floating point number fields
1081 <td>24 (23-bit mantissa, 1-bit sign)
1082 <td>bt_ctf_field_type_floating_point_get_mantissa_digits()
1083 <td>bt_ctf_field_type_floating_point_set_mantissa_digits()
1089 @sa \ref ctfirfieldtypesexamples_floatfieldtype "Examples"
1091 @addtogroup ctfirfloatfieldtype
1096 @brief Creates a default @floatft.
1098 @returns Created floating point number field type,
1099 or \c NULL on error.
1101 @postsuccessrefcountret1
1103 extern struct bt_ctf_field_type
*bt_ctf_field_type_floating_point_create(void);
1106 @brief Returns the exponent storage size of the @floatfields
1107 described by the @floatft \p float_field_type.
1109 @param[in] float_field_type Floating point number field type which
1110 describes the floating point number
1111 fields of which to get the exponent
1113 @returns Exponent storage size of the
1114 floating point number fields
1115 described by \p float_field_type,
1116 or a negative value on error.
1118 @prenotnull{float_field_type}
1119 @preisfloatft{float_field_type}
1120 @postrefcountsame{float_field_type}
1122 @sa bt_ctf_field_type_floating_point_set_exponent_digits(): Sets the
1123 exponent storage size of the floating point number fields
1124 described by a given floating point number field type.
1126 extern int bt_ctf_field_type_floating_point_get_exponent_digits(
1127 struct bt_ctf_field_type
*float_field_type
);
1130 @brief Sets the exponent storage size of the @floatfields described by
1131 the @floatft \p float_field_type to \p exponent_size.
1133 As of Babeltrace \btversion, \p exponent_size can only be 8 or 11.
1135 @param[in] float_field_type Floating point number field type which
1136 describes the floating point number
1137 fields of which to set the exponent
1139 @param[in] exponent_size Exponent storage size of the floating
1140 point number fields described by \p
1142 @returns 0 on success, or a negative value on error.
1144 @prenotnull{float_field_type}
1145 @preisfloatft{float_field_type}
1146 @prehot{float_field_type}
1147 @pre \p exponent_size is 8 or 11.
1148 @postrefcountsame{float_field_type}
1150 @sa bt_ctf_field_type_floating_point_get_exponent_digits(): Returns the
1151 exponent storage size of the floating point number fields
1152 described by a given floating point number field type.
1154 extern int bt_ctf_field_type_floating_point_set_exponent_digits(
1155 struct bt_ctf_field_type
*float_field_type
,
1156 unsigned int exponent_size
);
1159 @brief Returns the mantissa and sign storage size of the @floatfields
1160 described by the @floatft \p float_field_type.
1162 On success, the returned value is the sum of the mantissa \em and
1165 @param[in] float_field_type Floating point number field type which
1166 describes the floating point number
1167 fields of which to get the mantissa and
1169 @returns Mantissa and sign storage size of the
1170 floating point number fields
1171 described by \p float_field_type,
1172 or a negative value on error.
1174 @prenotnull{float_field_type}
1175 @preisfloatft{float_field_type}
1176 @postrefcountsame{float_field_type}
1178 @sa bt_ctf_field_type_floating_point_set_mantissa_digits(): Sets the
1179 mantissa and size storage size of the floating point number
1180 fields described by a given floating point number field type.
1182 extern int bt_ctf_field_type_floating_point_get_mantissa_digits(
1183 struct bt_ctf_field_type
*float_field_type
);
1186 @brief Sets the mantissa and sign storage size of the @floatfields
1187 described by the @floatft \p float_field_type to \p
1190 As of Babeltrace \btversion, \p mantissa_sign_size can only be 24 or 53.
1192 @param[in] float_field_type Floating point number field type which
1193 describes the floating point number
1194 fields of which to set the mantissa and
1196 @param[in] mantissa_sign_size Mantissa and sign storage size of the
1197 floating point number fields described
1198 by \p float_field_type.
1199 @returns 0 on success, or a negative value on error.
1201 @prenotnull{float_field_type}
1202 @preisfloatft{float_field_type}
1203 @prehot{float_field_type}
1204 @pre \p mantissa_sign_size is 24 or 53.
1205 @postrefcountsame{float_field_type}
1207 @sa bt_ctf_field_type_floating_point_get_mantissa_digits(): Returns the
1208 mantissa and sign storage size of the floating point number
1209 fields described by a given floating point number field type.
1211 extern int bt_ctf_field_type_floating_point_set_mantissa_digits(
1212 struct bt_ctf_field_type
*float_field_type
,
1213 unsigned int mantissa_sign_size
);
1218 @defgroup ctfirenumfieldtype CTF IR enumeration field type
1219 @ingroup ctfirfieldtypes
1220 @brief CTF IR enumeration field type.
1223 #include <babeltrace/ctf-ir/field-types.h>
1226 A CTF IR <strong><em>enumeration field type</em></strong> is
1227 a field type that you can use to create concrete @enumfields.
1229 You can create an enumeration field type with
1230 bt_ctf_field_type_enumeration_create(). This function needs a @intft
1231 which represents the storage field type of the created enumeration field
1232 type. In other words, an enumeration field type wraps an integer field
1233 type and adds label-value mappings to it.
1235 An enumeration mapping has:
1237 - A <strong>name</strong>.
1238 - A <strong>range of values</strong> given by a beginning and an ending
1239 value, both included in the range.
1241 You can add a mapping to an enumeration field type with
1242 bt_ctf_field_type_enumeration_add_mapping() or
1243 bt_ctf_field_type_enumeration_add_mapping_unsigned(), depending on the
1244 signedness of the wrapped @intft.
1246 You can find mappings by name or by value with the following find
1249 - bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
1250 mappings with a given name.
1251 - bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value():
1252 Finds the mappings which contain a given unsigned value in their
1254 - bt_ctf_field_type_enumeration_find_mappings_by_signed_value():
1255 Finds the mappings which contain a given signed value in their range.
1257 Those functions return a @enumftiter on the result set of the find
1260 Many mappings can share the same name, and the ranges of a given
1261 enumeration field type are allowed to overlap. For example,
1262 this is a valid set of mappings:
1271 The following set of mappings is also valid:
1280 Here, the range of the second \c APPLE mapping overlaps the range of
1281 the \c CHERRY mapping.
1283 @sa ctfirenumftmappingiter
1287 @addtogroup ctfirenumfieldtype
1292 @brief Creates a default @enumft wrapping the @intft \p int_field_type.
1294 @param[in] int_field_type Integer field type wrapped by the
1295 created enumeration field type.
1296 @returns Created enumeration field type,
1297 or \c NULL on error.
1299 @prenotnull{int_field_type}
1300 @preisintft{int_field_type}
1301 @postsuccessrefcountinc{int_field_type}
1302 @postsuccessrefcountret1
1304 extern struct bt_ctf_field_type
*bt_ctf_field_type_enumeration_create(
1305 struct bt_ctf_field_type
*int_field_type
);
1308 @brief Returns the @intft wrapped by the @enumft \p enum_field_type.
1310 @param[in] enum_field_type Enumeration field type of which to get
1311 the wrapped integer field type.
1312 @returns Integer field type wrapped by
1313 \p enum_field_type, or \c NULL on
1316 @prenotnull{enum_field_type}
1317 @preisenumft{enum_field_type}
1318 @postrefcountsame{enum_field_type}
1319 @postsuccessrefcountretinc
1322 struct bt_ctf_field_type
*bt_ctf_field_type_enumeration_get_container_type(
1323 struct bt_ctf_field_type
*enum_field_type
);
1326 @brief Returns the number of mappings contained in the
1327 @enumft \p enum_field_type.
1329 @param[in] enum_field_type Enumeration field type of which to get
1330 the number of contained mappings.
1331 @returns Number of mappings contained in
1332 \p enum_field_type, or a negative
1335 @prenotnull{enum_field_type}
1336 @preisenumft{enum_field_type}
1337 @postrefcountsame{enum_field_type}
1339 extern int64_t bt_ctf_field_type_enumeration_get_mapping_count(
1340 struct bt_ctf_field_type
*enum_field_type
);
1343 @brief Returns the signed mapping of the @enumft
1344 \p enum_field_type at index \p index.
1346 The @intft wrapped by \p enum_field_type, as returned by
1347 bt_ctf_field_type_enumeration_get_container_type(), must be \b signed
1348 to use this function.
1350 On success, \p enum_field_type remains the sole owner of \p *name.
1352 @param[in] enum_field_type Enumeration field type of which to get
1353 the mapping at index \p index.
1354 @param[in] index Index of the mapping to get from
1356 @param[out] name Returned name of the mapping at index
1358 @param[out] range_begin Returned beginning of the range
1359 (included) of the mapping at index \p
1361 @param[out] range_end Returned end of the range (included) of
1362 the mapping at index \p index.
1363 @returns 0 on success, or a negative value on error.
1365 @prenotnull{enum_field_type}
1367 @prenotnull{range_begin}
1368 @prenotnull{range_end}
1369 @preisenumft{enum_field_type}
1370 @pre The wrapped @intft of \p enum_field_type is signed.
1371 @pre \p index is lesser than the number of mappings contained in the
1372 enumeration field type \p enum_field_type (see
1373 bt_ctf_field_type_enumeration_get_mapping_count()).
1374 @postrefcountsame{enum_field_type}
1376 @sa bt_ctf_field_type_enumeration_get_mapping_unsigned(): Returns the
1377 unsigned mapping contained by a given enumeration field type
1380 extern int bt_ctf_field_type_enumeration_get_mapping_signed(
1381 struct bt_ctf_field_type
*enum_field_type
, int index
,
1382 const char **name
, int64_t *range_begin
, int64_t *range_end
);
1385 @brief Returns the unsigned mapping of the @enumft
1386 \p enum_field_type at index \p index.
1388 The @intft wrapped by \p enum_field_type, as returned by
1389 bt_ctf_field_type_enumeration_get_container_type(), must be
1390 \b unsigned to use this function.
1392 On success, \p enum_field_type remains the sole owner of \p *name.
1394 @param[in] enum_field_type Enumeration field type of which to get
1395 the mapping at index \p index.
1396 @param[in] index Index of the mapping to get from
1398 @param[out] name Returned name of the mapping at index
1400 @param[out] range_begin Returned beginning of the range
1401 (included) of the mapping at index \p
1403 @param[out] range_end Returned end of the range (included) of
1404 the mapping at index \p index.
1405 @returns 0 on success, or a negative value on error.
1407 @prenotnull{enum_field_type}
1409 @prenotnull{range_begin}
1410 @prenotnull{range_end}
1411 @preisenumft{enum_field_type}
1412 @pre The wrapped @intft of \p enum_field_type is unsigned.
1413 @pre \p index is lesser than the number of mappings contained in the
1414 enumeration field type \p enum_field_type (see
1415 bt_ctf_field_type_enumeration_get_mapping_count()).
1416 @postrefcountsame{enum_field_type}
1418 @sa bt_ctf_field_type_enumeration_get_mapping_signed(): Returns the
1419 signed mapping contained by a given enumeration field type
1422 extern int bt_ctf_field_type_enumeration_get_mapping_unsigned(
1423 struct bt_ctf_field_type
*enum_field_type
, int index
,
1424 const char **name
, uint64_t *range_begin
,
1425 uint64_t *range_end
);
1428 @brief Finds the mappings of the @enumft \p enum_field_type which
1431 This function returns an iterator on the result set of this find
1432 operation. See \ref ctfirenumftmappingiter for more details.
1434 @param[in] enum_field_type Enumeration field type of which to find
1435 the mappings named \p name.
1436 @param[in] name Name of the mappings to find in
1438 @returns @enumftiter on the set of mappings named
1439 \p name in \p enum_field_type, or
1440 \c NULL if no mappings were found or
1443 @prenotnull{enum_field_type}
1445 @preisenumft{enum_field_type}
1446 @postrefcountsame{enum_field_type}
1447 @postsuccessrefcountret1
1448 @post <strong>On success</strong>, the returned @enumftiter can iterate
1449 on at least one mapping.
1451 @sa bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): Finds
1452 the mappings of a given enumeration field type which contain
1453 a given signed value in their range.
1454 @sa bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): Finds
1455 the mappings of a given enumeration field type which contain
1456 a given unsigned value in their range.
1458 extern struct bt_ctf_field_type_enumeration_mapping_iterator
*
1459 bt_ctf_field_type_enumeration_find_mappings_by_name(
1460 struct bt_ctf_field_type
*enum_field_type
,
1464 @brief Finds the mappings of the @enumft \p enum_field_type which
1465 contain the signed value \p value in their range.
1467 This function returns an iterator on the result set of this find
1468 operation. See \ref ctfirenumftmappingiter for more details.
1470 @param[in] enum_field_type Enumeration field type of which to find
1471 the mappings which contain \p value.
1472 @param[in] value Value to find in the ranges of the
1473 mappings of \p enum_field_type.
1474 @returns @enumftiter on the set of mappings of
1475 \p enum_field_type which contain
1476 \p value in their range, or \c NULL if
1477 no mappings were found or on error.
1479 @prenotnull{enum_field_type}
1480 @preisenumft{enum_field_type}
1481 @postrefcountsame{enum_field_type}
1482 @postsuccessrefcountret1
1483 @post <strong>On success</strong>, the returned @enumftiter can iterate
1484 on at least one mapping.
1486 @sa bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
1487 mappings of a given enumeration field type which have a given
1489 @sa bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): Finds
1490 the mappings of a given enumeration field type which contain
1491 a given unsigned value in their range.
1493 extern struct bt_ctf_field_type_enumeration_mapping_iterator
*
1494 bt_ctf_field_type_enumeration_find_mappings_by_signed_value(
1495 struct bt_ctf_field_type
*enum_field_type
,
1499 @brief Finds the mappings of the @enumft \p enum_field_type which
1500 contain the unsigned value \p value in their range.
1502 This function returns an iterator on the result set of this find
1503 operation. See \ref ctfirenumftmappingiter for more details.
1505 @param[in] enum_field_type Enumeration field type of which to find
1506 the mappings which contain \p value.
1507 @param[in] value Value to find in the ranges of the
1508 mappings of \p enum_field_type.
1509 @returns @enumftiter on the set of mappings of
1510 \p enum_field_type which contain
1511 \p value in their range, or \c NULL
1512 if no mappings were found or
1515 @prenotnull{enum_field_type}
1516 @preisenumft{enum_field_type}
1517 @postrefcountsame{enum_field_type}
1518 @postsuccessrefcountret1
1519 @post <strong>On success</strong>, the returned @enumftiter can iterate
1520 on at least one mapping.
1522 @sa bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
1523 mappings of a given enumeration field type which have a given
1525 @sa bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): Finds
1526 the mappings of a given enumeration field type which contain
1527 a given unsigned value in their range.
1529 extern struct bt_ctf_field_type_enumeration_mapping_iterator
*
1530 bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(
1531 struct bt_ctf_field_type
*enum_field_type
,
1535 @brief Adds a mapping to the @enumft \p enum_field_type which maps the
1536 name \p name to the signed range \p range_begin (included) to
1537 \p range_end (included).
1539 Make \p range_begin and \p range_end the same value to add a mapping
1542 The @intft wrapped by \p enum_field_type, as returned by
1543 bt_ctf_field_type_enumeration_get_container_type(), must be
1544 \b signed to use this function.
1546 A mapping in \p enum_field_type can exist with the name \p name.
1548 @param[in] enum_field_type Enumeration field type to which to add
1550 @param[in] name Name of the mapping to add (copied
1552 @param[in] range_begin Beginning of the range of the mapping
1554 @param[in] range_end End of the range of the mapping
1556 @returns 0 on success, or a negative value on error.
1558 @prenotnull{enum_field_type}
1560 @prehot{enum_field_type}
1561 @preisenumft{enum_field_type}
1562 @pre The wrapped @intft of \p enum_field_type is signed.
1563 @pre \p range_end is greater than or equal to \p range_begin.
1564 @postrefcountsame{enum_field_type}
1566 @sa bt_ctf_field_type_enumeration_add_mapping_unsigned(): Adds an
1567 unsigned mapping to a given enumeration field type.
1569 extern int bt_ctf_field_type_enumeration_add_mapping(
1570 struct bt_ctf_field_type
*enum_field_type
, const char *name
,
1571 int64_t range_begin
, int64_t range_end
);
1574 @brief Adds a mapping to the @enumft \p enum_field_type which maps
1575 the name \p name to the unsigned
1576 range \p range_begin (included) to \p range_end (included).
1578 Make \p range_begin and \p range_end the same value to add a mapping
1581 The @intft wrapped by \p enum_field_type, as returned by
1582 bt_ctf_field_type_enumeration_get_container_type(), must be
1583 \b unsigned to use this function.
1585 A mapping in \p enum_field_type can exist with the name \p name.
1587 @param[in] enum_field_type Enumeration field type to which to add
1589 @param[in] name Name of the mapping to add (copied
1591 @param[in] range_begin Beginning of the range of the mapping
1593 @param[in] range_end End of the range of the mapping
1595 @returns 0 on success, or a negative value on error.
1597 @prenotnull{enum_field_type}
1599 @prehot{enum_field_type}
1600 @preisenumft{enum_field_type}
1601 @pre The wrapped @intft of \p enum_field_type is unsigned.
1602 @pre \p range_end is greater than or equal to \p range_begin.
1603 @postrefcountsame{enum_field_type}
1605 @sa bt_ctf_field_type_enumeration_add_mapping(): Adds a signed
1606 mapping to a given enumeration field type.
1608 extern int bt_ctf_field_type_enumeration_add_mapping_unsigned(
1609 struct bt_ctf_field_type
*enum_field_type
, const char *name
,
1610 uint64_t range_begin
, uint64_t range_end
);
1615 @defgroup ctfirenumftmappingiter CTF IR enumeration field type mapping iterator
1616 @ingroup ctfirenumfieldtype
1617 @brief CTF IR enumeration field type mapping iterator.
1620 #include <babeltrace/ctf-ir/field-types.h>
1623 A CTF IR <strong><em>enumeration field type mapping
1624 iterator</em></strong> is an iterator on @enumft mappings.
1626 You can get an enumeration mapping iterator from one of the following
1629 - Find operations of an @enumft object:
1630 - bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
1631 mappings with a given name.
1632 - bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value():
1633 Finds the mappings which contain a given unsigned value in their
1635 - bt_ctf_field_type_enumeration_find_mappings_by_signed_value():
1636 Finds the mappings which contain a given signed value in their range.
1637 - bt_ctf_field_enumeration_get_mappings(): Finds the mappings in the
1638 @enumft of an @enumfield containing its current integral value in
1641 Those functions guarantee that the returned iterator can iterate on
1642 at least one mapping. Otherwise, they return \c NULL.
1644 You can get the name and the range of a mapping iterator's current
1646 bt_ctf_field_type_enumeration_mapping_iterator_get_signed()
1648 bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(),
1649 depending on the signedness of the @intft wrapped by the
1650 @enumft. If you only need the name of the current mapping, you can
1651 use any of the two functions and set the \p range_begin and \p range_end
1652 parameters to \c NULL.
1654 You can advance an enumeration field type mapping iterator to the next
1656 bt_ctf_field_type_enumeration_mapping_iterator_next(). This
1657 function returns a negative value when you reach the end of the
1660 As with any Babeltrace object, CTF IR enumeration field type mapping
1661 iterator objects have <a
1662 href="https://en.wikipedia.org/wiki/Reference_counting">reference
1663 counts</a>. See \ref refs to learn more about the reference counting
1664 management of Babeltrace objects.
1666 @sa ctfirenumfieldtype
1668 @addtogroup ctfirenumftmappingiter
1673 @struct bt_ctf_field_type_enumeration_mapping_iterator
1674 @brief A CTF IR enumeration field type mapping iterator.
1675 @sa ctfirenumftmappingiter
1679 @brief Returns the name and the range of the current (signed) mapping
1680 of the @enumftiter \p iter.
1682 If one of \p range_begin or \p range_end is not \c NULL, the @intft
1683 wrapped by the @enumft from which \p iter was obtained, as returned by
1684 bt_ctf_field_type_enumeration_get_container_type(), must be
1685 \b signed to use this function. Otherwise, if you only need to get the
1686 name of the current mapping, set \p range_begin and \p range_end to
1689 On success, if \p name is not \c NULL, \p *name remains valid as long
1690 as \p iter exists and
1691 bt_ctf_field_type_enumeration_mapping_iterator_next() is
1692 \em not called on \p iter.
1694 @param[in] iter Enumeration field type mapping iterator
1695 of which to get the range of the current
1697 @param[out] name Returned name of the current mapping of
1698 \p iter (can be \c NULL to ignore).
1699 @param[out] range_begin Returned beginning of the range
1700 (included) of the current mapping of
1701 \p iter (can be \c NULL to ignore).
1702 @param[out] range_end Returned end of the range
1703 (included) of the current mapping of
1704 \p iter (can be \c NULL to ignore).
1705 @returns 0 on success, or a negative value on error.
1708 @postrefcountsame{iter}
1710 @sa bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned():
1711 Returns the name and the unsigned range of the current mapping
1712 of a given enumeration field type mapping iterator.
1714 extern int bt_ctf_field_type_enumeration_mapping_iterator_get_signed(
1715 struct bt_ctf_field_type_enumeration_mapping_iterator
*iter
,
1716 const char **name
, int64_t *range_begin
, int64_t *range_end
);
1719 @brief Returns the name and the range of the current (unsigned) mapping
1720 of the @enumftiter \p iter.
1722 If one of \p range_begin or \p range_end is not \c NULL, the @intft
1723 wrapped by the @enumft from which \p iter was obtained, as returned by
1724 bt_ctf_field_type_enumeration_get_container_type(), must be
1725 \b unsigned to use this function. Otherwise, if you only need to get the
1726 name of the current mapping, set \p range_begin and \p range_end to
1729 On success, if \p name is not \c NULL, \p *name remains valid as long
1730 as \p iter exists and
1731 bt_ctf_field_type_enumeration_mapping_iterator_next() is
1732 \em not called on \p iter.
1734 @param[in] iter Enumeration field type mapping iterator
1735 of which to get the range of the current
1737 @param[out] name Returned name of the current mapping of
1738 \p iter (can be \c NULL to ignore).
1739 @param[out] range_begin Returned beginning of the range
1740 (included) of the current mapping of
1741 \p iter (can be \c NULL to ignore).
1742 @param[out] range_end Returned end of the range
1743 (included) of the current mapping of
1744 \p iter (can be \c NULL to ignore).
1745 @returns 0 on success, or a negative value on error.
1748 @postrefcountsame{iter}
1751 bt_ctf_field_type_enumeration_mapping_iterator_get_signed():
1752 Returns the name and the signed range of the current mapping of
1753 a given enumeration field type mapping iterator.
1755 extern int bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(
1756 struct bt_ctf_field_type_enumeration_mapping_iterator
*iter
,
1757 const char **name
, uint64_t *range_begin
, uint64_t *range_end
);
1760 @brief Advances the @enumftiter \p iter to the next mapping.
1762 @param[in] iter Enumeration field type mapping iterator to
1764 @returns 0 on success, or a negative value on error or
1765 when you reach the end of the set.
1768 @postrefcountsame{iter}
1770 extern int bt_ctf_field_type_enumeration_mapping_iterator_next(
1771 struct bt_ctf_field_type_enumeration_mapping_iterator
*iter
);
1776 @defgroup ctfirstringfieldtype CTF IR string field type
1777 @ingroup ctfirfieldtypes
1778 @brief CTF IR string field type.
1781 #include <babeltrace/ctf-ir/field-types.h>
1784 A CTF IR <strong><em>string field type</em></strong> is a field type that
1785 you can use to create concrete @stringfields.
1787 You can create a string field type
1788 with bt_ctf_field_type_string_create().
1790 A string field type has only one property: the \b encoding of its
1791 described @stringfields. By default, the encoding of the string fields
1792 described by a string field type is #BT_CTF_STRING_ENCODING_UTF8. You
1793 can set the encoding of the string fields described by a string field
1794 type with bt_ctf_field_type_string_set_encoding().
1796 @sa ctfirstringfield
1799 @addtogroup ctfirstringfieldtype
1804 @brief Creates a default @stringft.
1806 @returns Created string field type, or \c NULL on error.
1808 @postsuccessrefcountret1
1810 extern struct bt_ctf_field_type
*bt_ctf_field_type_string_create(void);
1813 @brief Returns the encoding of the @stringfields described by
1814 the @stringft \p string_field_type.
1816 @param[in] string_field_type String field type which describes the
1817 string fields of which to get the
1819 @returns Encoding of the string
1820 fields described by \p string_field_type,
1821 or #BT_CTF_STRING_ENCODING_UNKNOWN on
1824 @prenotnull{string_field_type}
1825 @preisstringft{string_field_type}
1826 @postrefcountsame{string_field_type}
1828 @sa bt_ctf_field_type_string_set_encoding(): Sets the encoding
1829 of the string fields described by a given string field type.
1831 extern enum bt_ctf_string_encoding
bt_ctf_field_type_string_get_encoding(
1832 struct bt_ctf_field_type
*string_field_type
);
1835 @brief Sets the encoding of the @stringfields described by the
1836 @stringft \p string_field_type to \p encoding.
1838 @param[in] string_field_type String field type which describes the
1839 string fields of which to set the
1841 @param[in] encoding Encoding of the string fields described
1842 by \p string_field_type.
1843 @returns 0 on success, or a negative value on error.
1845 @prenotnull{string_field_type}
1846 @preisstringft{string_field_type}
1847 @prehot{string_field_type}
1848 @pre \p encoding is #BT_CTF_STRING_ENCODING_ASCII or
1849 #BT_CTF_STRING_ENCODING_UTF8.
1850 @postrefcountsame{string_field_type}
1852 @sa bt_ctf_field_type_string_get_encoding(): Returns the encoding of
1853 the string fields described by a given string field type.
1855 extern int bt_ctf_field_type_string_set_encoding(
1856 struct bt_ctf_field_type
*string_field_type
,
1857 enum bt_ctf_string_encoding encoding
);
1862 @defgroup ctfirstructfieldtype CTF IR structure field type
1863 @ingroup ctfirfieldtypes
1864 @brief CTF IR structure field type.
1867 #include <babeltrace/ctf-ir/field-types.h>
1870 A CTF IR <strong><em>structure field type</em></strong> is
1871 a field type that you can use to create concrete @structfields.
1873 You can create a structure field type
1874 with bt_ctf_field_type_structure_create(). This function creates
1875 an empty structure field type, with no fields.
1877 You can add a field to a structure field type with
1878 bt_ctf_field_type_structure_add_field(). Two fields in a structure
1879 field type cannot have the same name.
1881 You can set the \em minimum alignment of the structure fields described
1882 by a structure field type with the common
1883 bt_ctf_field_type_set_alignment() function. The \em effective alignment
1884 of the structure fields described by a structure field type, as per
1885 <a href="http://diamon.org/ctf/">CTF</a>, is the \em maximum value amongst
1886 the effective alignments of all its fields. Note that the effective
1887 alignment of @varfields is always 1.
1889 You can set the byte order of <em>all the contained fields</em>,
1890 recursively, of a structure field type with the common
1891 bt_ctf_field_type_set_byte_order() function.
1893 @sa ctfirstructfield
1896 @addtogroup ctfirstructfieldtype
1901 @brief Creates a default, empty @structft.
1903 @returns Created structure field type,
1904 or \c NULL on error.
1906 @postsuccessrefcountret1
1908 extern struct bt_ctf_field_type
*bt_ctf_field_type_structure_create(void);
1911 @brief Returns the number of fields contained in the
1912 @structft \p struct_field_type.
1914 @param[in] struct_field_type Structure field type of which to get
1915 the number of contained fields.
1916 @returns Number of fields contained in
1917 \p struct_field_type, or a negative
1920 @prenotnull{struct_field_type}
1921 @preisstructft{struct_field_type}
1922 @postrefcountsame{struct_field_type}
1924 extern int64_t bt_ctf_field_type_structure_get_field_count(
1925 struct bt_ctf_field_type
*struct_field_type
);
1928 @brief Returns the field of the @structft \p struct_field_type
1931 On success, the field's type is placed in \p *field_type if
1932 \p field_type is not \c NULL. The field's name is placed in
1933 \p *field_name if \p field_name is not \c NULL.
1934 \p struct_field_type remains the sole owner of \p *field_name.
1936 @param[in] struct_field_type Structure field type of which to get
1937 the field at index \p index.
1938 @param[out] field_name Returned name of the field at index
1939 \p index (can be \c NULL).
1940 @param[out] field_type Returned field type of the field
1941 at index \p index (can be \c NULL).
1942 @param[in] index Index of the field to get from
1943 \p struct_field_type.
1944 @returns 0 on success, or a negative value on error.
1946 @prenotnull{struct_field_type}
1947 @preisstructft{struct_field_type}
1948 @pre \p index is lesser than the number of fields contained in the
1949 structure field type \p struct_field_type (see
1950 bt_ctf_field_type_structure_get_field_count()).
1951 @postrefcountsame{struct_field_type}
1952 @post <strong>On success</strong>, the returned field's type is placed
1953 in \p *field_type and its reference count is incremented.
1955 @sa bt_ctf_field_type_structure_get_field_type_by_name(): Finds a
1956 structure field type's field by name.
1958 extern int bt_ctf_field_type_structure_get_field(
1959 struct bt_ctf_field_type
*struct_field_type
,
1960 const char **field_name
, struct bt_ctf_field_type
**field_type
,
1964 @brief Returns the type of the field named \p field_name found in
1965 the @structft \p struct_field_type.
1967 @param[in] struct_field_type Structure field type of which to get
1969 @param[in] field_name Name of the field to find.
1970 @returns Type of the field named \p field_name in
1971 \p struct_field_type, or
1974 @prenotnull{struct_field_type}
1975 @prenotnull{field_name}
1976 @preisstructft{struct_field_type}
1977 @postrefcountsame{struct_field_type}
1978 @postsuccessrefcountretinc
1980 @sa bt_ctf_field_type_structure_get_field(): Finds a
1981 structure field type's field by index.
1984 struct bt_ctf_field_type
*bt_ctf_field_type_structure_get_field_type_by_name(
1985 struct bt_ctf_field_type
*struct_field_type
,
1986 const char *field_name
);
1989 @brief Adds a field named \p field_name with the @ft
1990 \p field_type to the @structft \p struct_field_type.
1992 On success, \p field_type becomes the child of \p struct_field_type.
1994 This function adds the new field after the current last field of
1995 \p struct_field_type (append mode).
1997 You \em cannot add a field named \p field_name if there's already a
1998 field named \p field_name in \p struct_field_type.
2000 @param[in] struct_field_type Structure field type to which to add
2002 @param[in] field_type Field type of the field to add to
2003 \p struct_field_type.
2004 @param[in] field_name Name of the field to add to
2005 \p struct_field_type
2006 (copied on success).
2007 @returns 0 on success, or a negative value on error.
2009 @prenotnull{struct_field_type}
2010 @prenotnull{field_type}
2011 @prenotnull{field_name}
2012 @preisstructft{struct_field_type}
2013 @pre \p field_type is not and does not contain \p struct_field_type,
2014 recursively, as a field's type.
2015 @prehot{struct_field_type}
2016 @postrefcountsame{struct_field_type}
2017 @postsuccessrefcountinc{field_type}
2019 extern int bt_ctf_field_type_structure_add_field(
2020 struct bt_ctf_field_type
*struct_field_type
,
2021 struct bt_ctf_field_type
*field_type
,
2022 const char *field_name
);
2027 @defgroup ctfirarrayfieldtype CTF IR array field type
2028 @ingroup ctfirfieldtypes
2029 @brief CTF IR array field type.
2032 #include <babeltrace/ctf-ir/field-types.h>
2035 A CTF IR <strong><em>array field type</em></strong> is a field type that
2036 you can use to create concrete @arrayfields.
2038 You can create an array field type
2039 with bt_ctf_field_type_array_create(). This function needs
2040 the @ft of the fields contained by the array fields described by the
2041 array field type to create.
2046 @addtogroup ctfirarrayfieldtype
2051 @brief Creates a default @arrayft with
2052 \p element_field_type as the field type of the fields contained
2053 in its described @arrayfields of length \p length.
2055 @param[in] element_field_type Field type of the fields contained in
2056 the array fields described by the
2057 created array field type.
2058 @param[in] length Length of the array fields described by
2059 the created array field type.
2060 @returns Created array field type, or
2063 @prenotnull{element_field_type}
2064 @postsuccessrefcountinc{element_field_type}
2065 @postsuccessrefcountret1
2067 extern struct bt_ctf_field_type
*bt_ctf_field_type_array_create(
2068 struct bt_ctf_field_type
*element_field_type
,
2069 unsigned int length
);
2072 @brief Returns the @ft of the @fields contained in
2073 the @arrayfields described by the @arrayft \p array_field_type.
2075 @param[in] array_field_type Array field type of which to get
2076 the type of the fields contained in its
2077 described array fields.
2078 @returns Type of the fields contained in the
2079 array fields described by
2080 \p array_field_type, or \c NULL
2083 @prenotnull{array_field_type}
2084 @preisarrayft{array_field_type}
2085 @postrefcountsame{array_field_type}
2086 @postsuccessrefcountretinc
2088 extern struct bt_ctf_field_type
*bt_ctf_field_type_array_get_element_type(
2089 struct bt_ctf_field_type
*array_field_type
);
2092 @brief Returns the number of @fields contained in the
2093 @arrayfields described by the @arrayft \p array_field_type.
2095 @param[in] array_field_type Array field type of which to get
2096 the number of fields contained in its
2097 described array fields.
2098 @returns Number of fields contained in the
2099 array fields described by
2100 \p array_field_type, or a negative value
2103 @prenotnull{array_field_type}
2104 @preisarrayft{array_field_type}
2105 @postrefcountsame{array_field_type}
2107 extern int64_t bt_ctf_field_type_array_get_length(
2108 struct bt_ctf_field_type
*array_field_type
);
2113 @defgroup ctfirseqfieldtype CTF IR sequence field type
2114 @ingroup ctfirfieldtypes
2115 @brief CTF IR sequence field type.
2118 #include <babeltrace/ctf-ir/field-types.h>
2121 A CTF IR <strong><em>sequence field type</em></strong> is
2122 a field type that you can use to create concrete @seqfields.
2124 You can create a sequence field type with
2125 bt_ctf_field_type_sequence_create(). This function needs the @ft
2126 of the fields contained by the sequence fields described by the created
2127 sequence field type. This function also needs the length name of the
2128 sequence field type to create. The length name is used to automatically
2129 resolve the length's field type. See \ref ctfirfieldtypes to learn more
2130 about the automatic resolving.
2135 @addtogroup ctfirseqfieldtype
2140 @brief Creates a default @seqft with \p element_field_type as the
2141 @ft of the @fields contained in its described @seqfields
2142 with the length name \p length_name.
2144 \p length_name can be an absolute or relative reference. See
2145 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2147 @param[in] element_field_type Field type of the fields contained in
2148 the sequence fields described by the
2149 created sequence field type.
2150 @param[in] length_name Length name (copied on success).
2151 @returns Created array field type, or
2154 @prenotnull{element_field_type}
2155 @prenotnull{length_name}
2156 @postsuccessrefcountinc{element_field_type}
2157 @postsuccessrefcountret1
2159 extern struct bt_ctf_field_type
*bt_ctf_field_type_sequence_create(
2160 struct bt_ctf_field_type
*element_field_type
,
2161 const char *length_name
);
2164 @brief Returns the @ft of the @fields contained in the @seqft
2165 described by the @seqft \p sequence_field_type.
2167 @param[in] sequence_field_type Sequence field type of which to get
2168 the type of the fields contained in its
2169 described sequence fields.
2170 @returns Type of the fields contained in the
2171 sequence fields described by
2172 \p sequence_field_type, or \c NULL
2175 @prenotnull{sequence_field_type}
2176 @preisseqft{sequence_field_type}
2177 @postrefcountsame{sequence_field_type}
2178 @postsuccessrefcountretinc
2180 extern struct bt_ctf_field_type
*bt_ctf_field_type_sequence_get_element_type(
2181 struct bt_ctf_field_type
*sequence_field_type
);
2184 @brief Returns the length name of the @seqft \p sequence_field_type.
2186 On success, \p sequence_field_type remains the sole owner of
2187 the returned string.
2189 @param[in] sequence_field_type Sequence field type of which to get the
2191 @returns Length name of \p sequence_field_type,
2192 or \c NULL on error.
2194 @prenotnull{sequence_field_type}
2195 @preisseqft{sequence_field_type}
2197 @sa bt_ctf_field_type_sequence_get_length_field_path(): Returns the
2198 length's CTF IR field path of a given sequence field type.
2200 extern const char *bt_ctf_field_type_sequence_get_length_field_name(
2201 struct bt_ctf_field_type
*sequence_field_type
);
2204 @brief Returns the length's CTF IR field path of the @seqft
2205 \p sequence_field_type.
2207 The length's field path of a sequence field type is set when automatic
2208 resolving is performed (see \ref ctfirfieldtypes).
2210 @param[in] sequence_field_type Sequence field type of which to get the
2211 length's field path.
2212 @returns Length's field path of
2213 \p sequence_field_type, or
2214 \c NULL if the length's field path is
2215 not set yet is not set or on error.
2217 @prenotnull{sequence_field_type}
2218 @preisseqft{sequence_field_type}
2219 @postsuccessrefcountretinc
2221 @sa bt_ctf_field_type_sequence_get_length_field_name(): Returns the
2222 length's name of a given sequence field type.
2224 extern struct bt_ctf_field_path
*bt_ctf_field_type_sequence_get_length_field_path(
2225 struct bt_ctf_field_type
*sequence_field_type
);
2230 @defgroup ctfirvarfieldtype CTF IR variant field type
2231 @ingroup ctfirfieldtypes
2232 @brief CTF IR variant field type.
2235 #include <babeltrace/ctf-ir/field-types.h>
2238 A CTF IR <strong><em>variant field type</em></strong> is
2239 a field type that you can use to create concrete @varfields.
2241 You can create a variant field type with
2242 bt_ctf_field_type_variant_create(). This function expects you to pass
2243 both the tag's @enumft and the tag name of the variant field type to
2244 create. The tag's field type is optional, as the Babeltrace system can
2245 automatically resolve it using the tag name. You can leave the tag name
2246 to \c NULL initially, and set it later with
2247 bt_ctf_field_type_variant_set_tag_name(). The tag name must be set when
2248 the variant field type is frozen. See \ref ctfirfieldtypes to learn more
2249 about the automatic resolving and the conditions under which a field
2252 You can add a field to a variant field type with
2253 bt_ctf_field_type_variant_add_field(). All the field names of a
2254 variant field type \em must exist as mapping names in its tag's @enumft.
2256 The effective alignment of the @varfields described by a
2257 variant field type is always 1, but the individual fields of a
2258 @varfield can have custom alignments.
2260 You can set the byte order of <em>all the contained fields</em>,
2261 recursively, of a variant field type with the common
2262 bt_ctf_field_type_set_byte_order() function.
2267 @addtogroup ctfirvarfieldtype
2272 @brief Creates a default, empty @varft with the tag's @enumft
2273 \p tag_field_type and the tag name \p tag_name.
2275 \p tag_field_type can be \c NULL; the tag's field type can be
2276 automatically resolved from the variant field type's tag name (see
2277 \ref ctfirfieldtypes). If \p tag_name is \c NULL, it \em must be set
2278 with bt_ctf_field_type_variant_set_tag_name() \em before the variant
2279 field type is frozen.
2281 \p tag_name can be an absolute or relative reference. See
2282 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2284 @param[in] tag_field_type Tag's enumeration field type
2286 @param[in] tag_name Tag name (copied on success,
2288 @returns Created variant field type, or
2291 @pre \p tag_field_type is an enumeration field type or \c NULL.
2292 @post <strong>On success, if \p tag_field_type is not \c NULL</strong>,
2293 its reference count is incremented.
2294 @postsuccessrefcountret1
2296 extern struct bt_ctf_field_type
*bt_ctf_field_type_variant_create(
2297 struct bt_ctf_field_type
*tag_field_type
,
2298 const char *tag_name
);
2301 @brief Returns the tag's @enumft of the @varft \p variant_field_type.
2303 @param[in] variant_field_type Variant field type of which to get
2304 the tag's enumeration field type.
2305 @returns Tag's enumeration field type of
2306 \p variant_field_type, or \c NULL if the
2307 tag's field type is not set or on
2310 @prenotnull{variant_field_type}
2311 @preisvarft{variant_field_type}
2312 @postrefcountsame{variant_field_type}
2313 @postsuccessrefcountretinc
2315 extern struct bt_ctf_field_type
*bt_ctf_field_type_variant_get_tag_type(
2316 struct bt_ctf_field_type
*variant_field_type
);
2319 @brief Returns the tag name of the @varft \p variant_field_type.
2321 On success, \p variant_field_type remains the sole owner of
2322 the returned string.
2324 @param[in] variant_field_type Variant field type of which to get the
2326 @returns Tag name of \p variant_field_type, or
2327 \c NULL if the tag name is not set or
2330 @prenotnull{variant_field_type}
2331 @preisvarft{variant_field_type}
2333 @sa bt_ctf_field_type_variant_set_tag_name(): Sets the tag name of
2334 a given variant field type.
2335 @sa bt_ctf_field_type_variant_get_tag_field_path(): Returns the tag's
2336 CTF IR field path of a given variant field type.
2338 extern const char *bt_ctf_field_type_variant_get_tag_name(
2339 struct bt_ctf_field_type
*variant_field_type
);
2342 @brief Sets the tag name of the @varft \p variant_field_type.
2344 \p tag_name can be an absolute or relative reference. See
2345 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2347 @param[in] variant_field_type Variant field type of which to set
2349 @param[in] tag_name Tag name of \p variant_field_type
2350 (copied on success).
2351 @returns 0 on success, or a negative value on error.
2353 @prenotnull{variant_field_type}
2355 @prehot{variant_field_type}
2356 @postrefcountsame{variant_field_type}
2358 @sa bt_ctf_field_type_variant_get_tag_name(): Returns the tag name of
2359 a given variant field type.
2361 extern int bt_ctf_field_type_variant_set_tag_name(
2362 struct bt_ctf_field_type
*variant_field_type
,
2363 const char *tag_name
);
2366 @brief Returns the tag's CTF IR field path of the @varft
2367 \p variant_field_type.
2369 The tag's field path of a variant field type is set when automatic
2370 resolving is performed (see \ref ctfirfieldtypes).
2372 @param[in] variant_field_type Variant field type of which to get the
2374 @returns Tag's field path of
2375 \p variant_field_type, or
2376 \c NULL if the tag's field path is not
2377 set yet is not set or on error.
2379 @prenotnull{variant_field_type}
2380 @preisvarft{variant_field_type}
2381 @postsuccessrefcountretinc
2383 @sa bt_ctf_field_type_variant_get_tag_name(): Returns the tag's
2384 name of a given variant field type.
2386 extern struct bt_ctf_field_path
*bt_ctf_field_type_variant_get_tag_field_path(
2387 struct bt_ctf_field_type
*variant_field_type
);
2390 @brief Returns the number of fields (choices) contained in the @varft
2391 \p variant_field_type.
2393 @param[in] variant_field_type Variant field type of which to get
2394 the number of contained fields.
2395 @returns Number of fields contained in
2396 \p variant_field_type, or a negative
2399 @prenotnull{variant_field_type}
2400 @preisvarft{variant_field_type}
2401 @postrefcountsame{variant_field_type}
2403 extern int64_t bt_ctf_field_type_variant_get_field_count(
2404 struct bt_ctf_field_type
*variant_field_type
);
2407 @brief Returns the field (choice) of the @varft \p variant_field_type
2410 On success, the field's type is placed in \p *field_type if
2411 \p field_type is not \c NULL. The field's name is placed in
2412 \p *field_name if \p field_name is not \c NULL.
2413 \p variant_field_type remains the sole owner of \p *field_name.
2415 @param[in] variant_field_type Variant field type of which to get
2416 the field at index \p index.
2417 @param[out] field_name Returned name of the field at index
2418 \p index (can be \c NULL).
2419 @param[out] field_type Returned field type of the field
2420 at index \p index (can be \c NULL).
2421 @param[in] index Index of the field to get from
2422 \p variant_field_type.
2423 @returns 0 on success, or a negative value on error.
2425 @prenotnull{variant_field_type}
2426 @preisvarft{variant_field_type}
2427 @pre \p index is lesser than the number of fields contained in the
2428 variant field type \p variant_field_type (see
2429 bt_ctf_field_type_variant_get_field_count()).
2430 @postrefcountsame{variant_field_type}
2431 @post <strong>On success</strong>, the returned field's type is placed
2432 in \p *field_type and its reference count is incremented.
2434 @sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant
2435 field type's field by name.
2436 @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant
2437 field type's field by current tag value.
2439 extern int bt_ctf_field_type_variant_get_field(
2440 struct bt_ctf_field_type
*variant_field_type
,
2441 const char **field_name
,
2442 struct bt_ctf_field_type
**field_type
, int index
);
2445 @brief Returns the type of the field (choice) named \p field_name
2446 found in the @varft \p variant_field_type.
2448 @param[in] variant_field_type Variant field type of which to get
2450 @param[in] field_name Name of the field to find.
2451 @returns Type of the field named \p field_name in
2452 \p variant_field_type, or
2455 @prenotnull{variant_field_type}
2456 @prenotnull{field_name}
2457 @preisvarft{variant_field_type}
2458 @postrefcountsame{variant_field_type}
2459 @postsuccessrefcountretinc
2461 @sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's
2463 @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant
2464 field type's field by current tag value.
2467 struct bt_ctf_field_type
*bt_ctf_field_type_variant_get_field_type_by_name(
2468 struct bt_ctf_field_type
*variant_field_type
,
2469 const char *field_name
);
2472 @brief Returns the type of the field (choice) selected by the value of
2473 the @enumfield \p tag_field in the @varft \p variant_field_type.
2475 \p tag_field is the current tag value.
2477 The field type of \p tag_field, as returned by bt_ctf_field_get_type(),
2478 \em must be equivalent to the field type returned by
2479 bt_ctf_field_type_variant_get_tag_type() for \p variant_field_type.
2481 @param[in] variant_field_type Variant field type of which to get
2483 @param[in] tag_field Current tag value (variant field type's
2485 @returns Type of the field selected by
2486 \p tag_field in \p variant_field_type,
2487 or \c NULL on error.
2489 @prenotnull{variant_field_type}
2490 @prenotnull{tag_field}
2491 @preisvarft{variant_field_type}
2492 @preisenumfield{tag_field}
2493 @postrefcountsame{variant_field_type}
2494 @postrefcountsame{tag_field}
2495 @postsuccessrefcountretinc
2497 @sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's
2499 @sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant
2500 field type's field by name.
2503 struct bt_ctf_field_type
*bt_ctf_field_type_variant_get_field_type_from_tag(
2504 struct bt_ctf_field_type
*variant_field_type
,
2505 struct bt_ctf_field
*tag_field
);
2508 @brief Adds a field (a choice) named \p field_name with the @ft
2509 \p field_type to the @varft \p variant_field_type.
2511 On success, \p field_type becomes the child of \p variant_field_type.
2513 You \em cannot add a field named \p field_name if there's already a
2514 field named \p field_name in \p variant_field_type.
2516 \p field_name \em must name an existing mapping in the tag's
2517 enumeration field type of \p variant_field_type.
2519 @param[in] variant_field_type Variant field type to which to add
2521 @param[in] field_type Field type of the field to add to
2522 \p variant_field_type.
2523 @param[in] field_name Name of the field to add to
2524 \p variant_field_type
2525 (copied on success).
2526 @returns 0 on success, or a negative value on error.
2528 @prenotnull{variant_field_type}
2529 @prenotnull{field_type}
2530 @prenotnull{field_name}
2531 @preisvarft{variant_field_type}
2532 @pre \p field_type is not and does not contain \p variant_field_type,
2533 recursively, as a field's type.
2534 @prehot{variant_field_type}
2535 @postrefcountsame{variant_field_type}
2536 @postsuccessrefcountinc{field_type}
2538 extern int bt_ctf_field_type_variant_add_field(
2539 struct bt_ctf_field_type
*variant_field_type
,
2540 struct bt_ctf_field_type
*field_type
,
2541 const char *field_name
);
2549 #endif /* BABELTRACE_CTF_IR_FIELD_TYPES_H */