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
34 #include <babeltrace/ref.h>
37 #include <babeltrace/types.h>
47 @defgroup ctfirfieldtypes CTF IR field types
49 @brief CTF IR field types.
52 #include <babeltrace/ctf-ir/field-types.h>
55 A CTF IR <strong><em>field type</em></strong> is a field type that you
56 can use to create concrete @fields.
58 You can create a @field object from a CTF IR field type object
59 with bt_field_create().
61 In the CTF IR hierarchy, you can set the root field types of three
64 - \ref ctfirtraceclass
65 - Trace packet header field type: bt_trace_set_packet_header_field_type().
66 - \ref ctfirstreamclass
67 - Stream packet context field type:
68 bt_stream_class_set_packet_context_field_type().
69 - Stream event header field type:
70 bt_stream_class_set_event_header_field_type().
71 - Stream event context field type:
72 bt_stream_class_set_event_context_field_type().
73 - \ref ctfireventclass
74 - Event context field type: bt_event_class_set_context_field_type().
75 - Event payload field type: bt_event_class_set_payload_field_type().
77 As of Babeltrace \btversion, those six previous "root" field types
78 \em must be @structft objects.
80 If, at any level within a given root field type, you add a @seqft or a
81 @varft, you do not need to specify its associated length
82 or tag field type: the length or tag string is enough for the Babeltrace
83 system to resolve the needed field type depending on where this
84 dynamic field type is located within the whole hierarchy. It is
85 guaranteed that this automatic resolving is performed for all the field
86 types contained in a given
87 \link ctfirstreamclass CTF IR stream class\endlink (and in its
88 children \link ctfireventclass CTF IR event classes\endlink) once you
89 add it to a \link ctfirtraceclass CTF IR trace class\endlink with
90 bt_trace_add_stream_class(). Once a stream class is the child of
91 a trace class, this automatic resolving is performed for the field
92 types of an event class when you add it with
93 bt_stream_class_add_event_class(). If the system cannot find a path
94 to a field in the hierarchy for a dynamic field type, the adding
97 The standard CTF field types are:
102 <th>CTF IR field type
103 <th>CTF IR field which you can create from this field type
106 <td>#BT_FIELD_TYPE_ID_INTEGER
107 <td>\ref ctfirintfieldtype
108 <td>\ref ctfirintfield
111 <td>#BT_FIELD_TYPE_ID_FLOAT
112 <td>\ref ctfirfloatfieldtype
113 <td>\ref ctfirfloatfield
116 <td>#BT_FIELD_TYPE_ID_ENUM
117 <td>\ref ctfirenumfieldtype
118 <td>\ref ctfirenumfield
121 <td>#BT_FIELD_TYPE_ID_STRING
122 <td>\ref ctfirstringfieldtype
123 <td>\ref ctfirstringfield
126 <td>#BT_FIELD_TYPE_ID_STRUCT
127 <td>\ref ctfirstructfieldtype
128 <td>\ref ctfirstructfield
131 <td>#BT_FIELD_TYPE_ID_ARRAY
132 <td>\ref ctfirarrayfieldtype
133 <td>\ref ctfirarrayfield
136 <td>#BT_FIELD_TYPE_ID_SEQUENCE
137 <td>\ref ctfirseqfieldtype
138 <td>\ref ctfirseqfield
141 <td>#BT_FIELD_TYPE_ID_VARIANT
142 <td>\ref ctfirvarfieldtype
143 <td>\ref ctfirvarfield
147 Each field type has its own <strong>type ID</strong> (see
148 #bt_field_type_id). You get the type ID of a field type object
149 with bt_field_type_get_type_id().
151 You can get a deep copy of a field type with bt_field_type_copy().
152 This function resets, in the field type copy, the resolved field type
153 of the dynamic field types. The automatic resolving can be done again
154 when you eventually call bt_event_create(),
155 bt_stream_class_add_event_class(), or
156 bt_trace_add_stream_class().
158 You \em must always use bt_field_type_compare() to compare two
159 field types. Since some parts of the Babeltrace system can copy field
160 types behind the scenes, you \em cannot rely on a simple field type
163 As with any Babeltrace object, CTF IR field type objects have
164 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
165 counts</a>. See \ref refs to learn more about the reference counting
166 management of Babeltrace objects.
168 The following functions can \em freeze field type objects:
170 - bt_field_create() freezes its field type parameter.
171 - bt_stream_class_add_event_class(), if its
172 \link ctfirstreamclass CTF IR stream class\endlink parameter has a
173 \link ctfirtraceclass CTF IR trace class\endlink parent, freezes
174 the root field types of its
175 \link ctfireventclass CTF IR event class\endlink parameter.
176 - bt_trace_add_stream_class() freezes the root field types of the
177 whole trace class hierarchy (trace class, children stream classes,
178 and their children event classes).
179 - bt_writer_create_stream() freezes the root field types of the
180 whole CTF writer's trace class hierarchy.
181 - bt_event_create() freezes the root field types of its event class
182 parameter and of ther parent stream class of this event class.
184 You cannot modify a frozen field type object: it is considered
185 immutable, except for \link refs reference counting\endlink.
188 @sa \ref ctfirfieldtypesexamples "Examples"
191 @brief CTF IR field types type and functions.
194 @addtogroup ctfirfieldtypes
199 @struct bt_field_type
200 @brief A CTF IR field type.
203 struct bt_field_type
;
204 struct bt_event_class
;
207 struct bt_field_path
;
208 struct bt_field_type_enumeration_mapping_iterator
;
214 /// Unknown, used for errors.
215 BT_SCOPE_UNKNOWN
= -1,
217 /// Trace packet header.
218 BT_SCOPE_TRACE_PACKET_HEADER
= 1,
220 /// Stream packet context.
221 BT_SCOPE_STREAM_PACKET_CONTEXT
= 2,
223 /// Stream event header.
224 BT_SCOPE_STREAM_EVENT_HEADER
= 3,
226 /// Stream event context.
227 BT_SCOPE_STREAM_EVENT_CONTEXT
= 4,
230 BT_SCOPE_EVENT_CONTEXT
= 5,
233 BT_SCOPE_EVENT_PAYLOAD
= 6,
237 BT_SCOPE_EVENT_FIELDS
= 6,
242 @name Type information
247 @brief Type ID of a @ft.
249 enum bt_field_type_id
{
250 /// Unknown, used for errors.
251 BT_FIELD_TYPE_ID_UNKNOWN
= -1,
253 /// \ref ctfirintfieldtype
254 BT_FIELD_TYPE_ID_INTEGER
= 0,
256 /// \ref ctfirfloatfieldtype
257 BT_FIELD_TYPE_ID_FLOAT
= 1,
259 /// \ref ctfirenumfieldtype
260 BT_FIELD_TYPE_ID_ENUM
= 2,
262 /// \ref ctfirstringfieldtype
263 BT_FIELD_TYPE_ID_STRING
= 3,
265 /// \ref ctfirstructfieldtype
266 BT_FIELD_TYPE_ID_STRUCT
= 4,
268 /// \ref ctfirarrayfieldtype
269 BT_FIELD_TYPE_ID_ARRAY
= 6,
271 /// \ref ctfirseqfieldtype
272 BT_FIELD_TYPE_ID_SEQUENCE
= 7,
274 /// \ref ctfirvarfieldtype
275 BT_FIELD_TYPE_ID_VARIANT
= 5,
277 /// Number of enumeration entries.
278 BT_FIELD_TYPE_ID_NR
= 8,
282 @brief Returns the type ID of the @ft \p field_type.
284 @param[in] field_type Field type of which to get the type ID.
285 @returns Type ID of \p field_type,
286 or #BT_FIELD_TYPE_ID_UNKNOWN on error.
288 @prenotnull{field_type}
289 @postrefcountsame{field_type}
291 @sa #bt_field_type_id: CTF IR field type ID.
292 @sa bt_field_type_is_integer(): Returns whether or not a given
293 field type is a @intft.
294 @sa bt_field_type_is_floating_point(): Returns whether or not a
295 given field type is a @floatft.
296 @sa bt_field_type_is_enumeration(): Returns whether or not a given
297 field type is a @enumft.
298 @sa bt_field_type_is_string(): Returns whether or not a given
299 field type is a @stringft.
300 @sa bt_field_type_is_structure(): Returns whether or not a given
301 field type is a @structft.
302 @sa bt_field_type_is_array(): Returns whether or not a given
303 field type is a @arrayft.
304 @sa bt_field_type_is_sequence(): Returns whether or not a given
305 field type is a @seqft.
306 @sa bt_field_type_is_variant(): Returns whether or not a given
307 field type is a @varft.
309 extern enum bt_field_type_id
bt_field_type_get_type_id(
310 struct bt_field_type
*field_type
);
313 @brief Returns whether or not the @ft \p field_type is a @intft.
315 @param[in] field_type Field type to check (can be \c NULL).
316 @returns #BT_TRUE if \p field_type is an integer field type,
317 or #BT_FALSE otherwise (including if \p field_type is
320 @prenotnull{field_type}
321 @postrefcountsame{field_type}
323 @sa bt_field_type_get_type_id(): Returns the type ID of a given
327 bt_bool
bt_field_type_is_integer(struct bt_field_type
*field_type
)
329 return bt_field_type_get_type_id(field_type
) ==
330 BT_FIELD_TYPE_ID_INTEGER
;
334 @brief Returns whether or not the @ft \p field_type is a @floatft.
336 @param[in] field_type Field type to check (can be \c NULL).
337 @returns #BT_TRUE if \p field_type is a floating point
338 #BT_FALSE field type,
339 or 0 otherwise (including if \p field_type is
342 @postrefcountsame{field_type}
344 @sa bt_field_type_get_type_id(): Returns the type ID of a given
348 bt_bool
bt_field_type_is_floating_point(struct bt_field_type
*field_type
)
350 return bt_field_type_get_type_id(field_type
) == BT_FIELD_TYPE_ID_FLOAT
;
354 @brief Returns whether or not the @ft \p field_type is a @enumft.
356 @param[in] field_type Field type to check (can be \c NULL).
357 @returns #BT_TRUE if \p field_type is an enumeration field type,
358 or #BT_FALSE otherwise (including if \p field_type is
361 @postrefcountsame{field_type}
363 @sa bt_field_type_get_type_id(): Returns the type ID of a given
367 bt_bool
bt_field_type_is_enumeration(struct bt_field_type
*field_type
)
369 return bt_field_type_get_type_id(field_type
) == BT_FIELD_TYPE_ID_ENUM
;
373 @brief Returns whether or not the @ft \p field_type is a @stringft.
375 @param[in] field_type Field type to check (can be \c NULL).
376 @returns #BT_TRUE if \p field_type is a string field type,
377 or #BT_FALSE otherwise (including if \p field_type is
380 @postrefcountsame{field_type}
382 @sa bt_field_type_get_type_id(): Returns the type ID of a given
386 bt_bool
bt_field_type_is_string(struct bt_field_type
*field_type
)
388 return bt_field_type_get_type_id(field_type
) == BT_FIELD_TYPE_ID_STRING
;
392 @brief Returns whether or not the @ft \p field_type is a @structft.
394 @param[in] field_type Field type to check (can be \c NULL).
395 @returns #BT_TRUE if \p field_type is a structure field type,
396 or #BT_FALSE otherwise (including if \p field_type is
399 @postrefcountsame{field_type}
401 @sa bt_field_type_get_type_id(): Returns the type ID of a given
405 bt_bool
bt_field_type_is_structure(struct bt_field_type
*field_type
)
407 return bt_field_type_get_type_id(field_type
) == BT_FIELD_TYPE_ID_STRUCT
;
411 @brief Returns whether or not the @ft \p field_type is a @arrayft.
413 @param[in] field_type Field type to check (can be \c NULL).
414 @returns #BT_TRUE if \p field_type is an array field type,
415 or #BT_FALSE otherwise (including if \p field_type is
418 @postrefcountsame{field_type}
420 @sa bt_field_type_get_type_id(): Returns the type ID of a given
424 bt_bool
bt_field_type_is_array(struct bt_field_type
*field_type
)
426 return bt_field_type_get_type_id(field_type
) == BT_FIELD_TYPE_ID_ARRAY
;
430 @brief Returns whether or not the @ft \p field_type is a @seqft.
432 @param[in] field_type Field type to check (can be \c NULL).
433 @returns #BT_TRUE if \p field_type is a sequence field type,
434 or #BT_FALSE otherwise (including if \p field_type is
437 @postrefcountsame{field_type}
439 @sa bt_field_type_get_type_id(): Returns the type ID of a given
443 bt_bool
bt_field_type_is_sequence(struct bt_field_type
*field_type
)
445 return bt_field_type_get_type_id(field_type
) ==
446 BT_FIELD_TYPE_ID_SEQUENCE
;
450 @brief Returns whether or not the @ft \p field_type is a @varft.
452 @param[in] field_type Field type to check (can be \c NULL).
453 @returns #BT_TRUE if \p field_type is a variant field type,
454 or #BT_FALSE otherwise (including if \p field_type is
457 @postrefcountsame{field_type}
459 @sa bt_field_type_get_type_id(): Returns the type ID of a given
463 bt_bool
bt_field_type_is_variant(struct bt_field_type
*field_type
)
465 return bt_field_type_get_type_id(field_type
) ==
466 BT_FIELD_TYPE_ID_VARIANT
;
472 @name Common properties types and functions
477 @brief <a href="https://en.wikipedia.org/wiki/Endianness">Byte order</a>
481 /// Unknown, used for errors.
482 BT_BYTE_ORDER_UNKNOWN
= -1,
485 * Note that native, in the context of the CTF specification, is defined
486 * as "the byte order described in the trace" and does not mean that the
487 * host's endianness will be used.
489 /// Native (default) byte order.
490 BT_BYTE_ORDER_NATIVE
= 0,
493 Unspecified byte order; the initial native byte order of a
494 \link ctfirtraceclass CTF IR trace class\endlink.
496 BT_BYTE_ORDER_UNSPECIFIED
,
499 BT_BYTE_ORDER_LITTLE_ENDIAN
,
502 BT_BYTE_ORDER_BIG_ENDIAN
,
504 /// Network byte order (big-endian).
505 BT_BYTE_ORDER_NETWORK
,
509 @brief String encoding of a @ft.
511 enum bt_string_encoding
{
512 /// Unknown, used for errors.
513 BT_STRING_ENCODING_UNKNOWN
= -1,
516 BT_STRING_ENCODING_NONE
,
518 /// <a href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a>.
519 BT_STRING_ENCODING_UTF8
,
521 /// <a href="https://en.wikipedia.org/wiki/ASCII">ASCII</a>.
522 BT_STRING_ENCODING_ASCII
,
526 @brief Returns the alignment of the @fields described by
527 the @ft \p field_type.
529 @param[in] field_type Field type which describes the
530 fields of which to get the alignment.
531 @returns Alignment of the fields described by
532 \p field_type, or a negative value on error.
534 @prenotnull{field_type}
535 @postrefcountsame{field_type}
537 @sa bt_field_type_set_alignment(): Sets the alignment
538 of the fields described by a given field type.
540 extern int bt_field_type_get_alignment(
541 struct bt_field_type
*field_type
);
544 @brief Sets the alignment of the @fields described by the
545 @ft \p field_type to \p alignment.
547 \p alignment \em must be greater than 0 and a power of two.
549 @param[in] field_type Field type which describes the fields of
550 which to set the alignment.
551 @param[in] alignment Alignment of the fields described by
553 @returns 0 on success, or a negative value on error.
555 @prenotnull{field_type}
557 @pre \p alignment is greater than 0 and a power of two.
558 @postrefcountsame{field_type}
560 @sa bt_field_type_get_alignment(): Returns the alignment of the
561 fields described by a given field type.
563 extern int bt_field_type_set_alignment(struct bt_field_type
*field_type
,
564 unsigned int alignment
);
567 @brief Returns the byte order of the @fields described by
568 the @ft \p field_type.
570 You can only call this function if \p field_type is a @intft, a
571 @floatft, or a @enumft.
573 @param[in] field_type Field type which describes the
574 fields of which to get the byte order.
575 @returns Byte order of the fields described by
576 \p field_type, or #BT_BYTE_ORDER_UNKNOWN on
579 @prenotnull{field_type}
580 @pre \p field_type is a @intft, a @floatft, or a @enumft.
581 @postrefcountsame{field_type}
583 @sa bt_field_type_set_byte_order(): Sets the byte order
584 of the fields described by a given field type.
586 extern enum bt_byte_order
bt_field_type_get_byte_order(
587 struct bt_field_type
*field_type
);
590 @brief Sets the byte order of the @fields described by the
591 @ft \p field_type to \p byte_order.
593 If \p field_type is a compound field type, this function also
594 recursively sets the byte order of its children to \p byte_order.
596 @param[in] field_type Field type which describes the fields of
597 which to set the byte order.
598 @param[in] byte_order Alignment of the fields described by
600 @returns 0 on success, or a negative value on error.
602 @prenotnull{field_type}
604 @pre \p byte_order is #BT_BYTE_ORDER_NATIVE,
605 #BT_BYTE_ORDER_LITTLE_ENDIAN, #BT_BYTE_ORDER_BIG_ENDIAN,
606 or #BT_BYTE_ORDER_NETWORK.
607 @postrefcountsame{field_type}
609 @sa bt_field_type_get_byte_order(): Returns the byte order of the
610 fields described by a given field type.
612 extern int bt_field_type_set_byte_order(
613 struct bt_field_type
*field_type
,
614 enum bt_byte_order byte_order
);
619 @name Utility functions
624 @brief Returns whether or not the @ft \p field_type_a
625 is equivalent to the field type \p field_type_b.
627 You \em must use this function to compare two field types: it is not
628 safe to compare two pointer values directly, because, for internal
629 reasons, some parts of the Babeltrace system can copy user field types
630 and discard the original ones.
632 @param[in] field_type_a Field type to compare to \p field_type_b.
633 @param[in] field_type_b Field type to compare to \p field_type_a.
634 @returns 0 if \p field_type_a is equivalent to
635 \p field_type_b, 1 if they are not equivalent,
636 or a negative value on error.
638 @prenotnull{field_type_a}
639 @prenotnull{field_type_b}
640 @postrefcountsame{field_type_a}
641 @postrefcountsame{field_type_b}
643 extern int bt_field_type_compare(struct bt_field_type
*field_type_a
,
644 struct bt_field_type
*field_type_b
);
647 @brief Creates a \em deep copy of the @ft \p field_type.
649 You can copy a frozen field type: the resulting copy is
652 This function resets the tag field type of a copied @varft. The
653 automatic field resolving which some functions of the API perform
654 can set it again when the returned field type is used (learn more
655 in the detailed description of this module).
657 @param[in] field_type Field type to copy.
658 @returns Deep copy of \p field_type on success,
661 @prenotnull{field_type}
662 @postrefcountsame{field_type}
663 @postsuccessrefcountret1
664 @post <strong>On success</strong>, the returned field type is not frozen.
666 extern struct bt_field_type
*bt_field_type_copy(
667 struct bt_field_type
*field_type
);
674 @defgroup ctfirintfieldtype CTF IR integer field type
675 @ingroup ctfirfieldtypes
676 @brief CTF IR integer field type.
679 #include <babeltrace/ctf-ir/field-types.h>
682 A CTF IR <strong><em>integer field type</em></strong> is a field type that
683 you can use to create concrete @intfield objects.
685 You can create an integer field type
686 with bt_field_type_integer_create().
688 An integer field type has the following properties:
693 <th>Value at creation
698 <td>\b Alignment (bits) of the described integer fields
700 <td>bt_field_type_get_alignment()
701 <td>bt_field_type_set_alignment()
704 <td><strong>Byte order</strong> of the described integer fields
705 <td>#BT_BYTE_ORDER_NATIVE
706 <td>bt_field_type_get_byte_order()
707 <td>bt_field_type_set_byte_order()
710 <td><strong>Storage size</strong> (bits) of the described
712 <td>Specified at creation
713 <td>bt_field_type_integer_get_size()
714 <td>bt_field_type_integer_set_size()
717 <td><strong>Signedness</strong> of the described integer fields
719 <td>bt_field_type_integer_is_signed()
720 <td>bt_field_type_integer_set_is_signed()
723 <td><strong>Preferred display base</strong> of the described
725 <td>#BT_INTEGER_BASE_DECIMAL
726 <td>bt_field_type_integer_get_base()
727 <td>bt_field_type_integer_set_base()
730 <td>\b Encoding of the described integer fields
731 <td>#BT_STRING_ENCODING_NONE
732 <td>bt_field_type_integer_get_encoding()
733 <td>bt_field_type_integer_set_encoding()
737 \link ctfirclockclass CTF IR clock class\endlink</strong>
739 <td>bt_field_type_integer_get_mapped_clock_class()
740 <td>bt_field_type_integer_set_mapped_clock_class()
746 @sa \ref ctfirfieldtypesexamples_intfieldtype "Examples"
748 @addtogroup ctfirintfieldtype
753 @brief Preferred display base (radix) of a @intft.
755 enum bt_integer_base
{
756 /// Unknown, used for errors.
757 BT_INTEGER_BASE_UNKNOWN
= -1,
759 /// Unspecified by the tracer.
760 BT_INTEGER_BASE_UNSPECIFIED
= 0,
763 BT_INTEGER_BASE_BINARY
= 2,
766 BT_INTEGER_BASE_OCTAL
= 8,
769 BT_INTEGER_BASE_DECIMAL
= 10,
772 BT_INTEGER_BASE_HEXADECIMAL
= 16,
776 @brief Creates a default @intft with \p size bits as the storage size
777 of the @intfields it describes.
779 You can change the storage size of the integer fields described by
780 the created integer field type later with
781 bt_field_type_integer_set_size().
783 @param[in] size Storage size (bits) of the described integer fields.
784 @returns Created integer field type, or \c NULL on error.
786 @pre \p size is greater than 0 and lesser than or equal to 64.
787 @postsuccessrefcountret1
789 extern struct bt_field_type
*bt_field_type_integer_create(
793 @brief Returns the storage size, in bits, of the @intfields
794 described by the @intft \p int_field_type.
796 @param[in] int_field_type Integer field type which describes the
797 integer fields of which to get the
799 @returns Storage size (bits) of the integer
800 fields described by \p int_field_type,
801 or a negative value on error.
803 @prenotnull{int_field_type}
804 @preisintft{int_field_type}
805 @postrefcountsame{int_field_type}
807 @sa bt_field_type_integer_set_size(): Sets the storage size of the
808 integer fields described by a given integer field type.
810 extern int bt_field_type_integer_get_size(
811 struct bt_field_type
*int_field_type
);
814 @brief Sets the storage size, in bits, of the @intfields described by
815 the @intft \p int_field_type.
817 @param[in] int_field_type Integer field type which describes the
818 integer fields of which to set the
820 @param[in] size Storage size (bits) of the integer fields
821 described by \p int_field_type.
822 @returns 0 on success, or a negative value on error.
824 @prenotnull{int_field_type}
825 @preisintft{int_field_type}
826 @prehot{int_field_type}
827 @pre \p size is greater than 0 and lesser than or equal to 64.
828 @postrefcountsame{int_field_type}
830 @sa bt_field_type_integer_get_size(): Returns the storage size of
831 the integer fields described by a given integer field type.
833 extern int bt_field_type_integer_set_size(
834 struct bt_field_type
*int_field_type
, unsigned int size
);
837 @brief Returns whether or not the @intfields described by the @intft
838 \p int_field_type are signed.
840 @param[in] int_field_type Integer field type which describes the
841 integer fields of which to get the
843 @returns #BT_TRUE if the integer fields described by
844 \p int_field_type are signed, #BT_FALSE if they
847 @prenotnull{int_field_type}
848 @preisintft{int_field_type}
849 @postrefcountsame{int_field_type}
851 @sa bt_field_type_integer_set_is_signed(): Sets the signedness of the
852 integer fields described by a given integer field type.
854 extern bt_bool
bt_field_type_integer_is_signed(
855 struct bt_field_type
*int_field_type
);
858 @brief Sets whether or not the @intfields described by
859 the @intft \p int_field_type are signed.
861 @param[in] int_field_type Integer field type which describes the
862 integer fields of which to set the
864 @param[in] is_signed Signedness of the integer fields
865 described by \p int_field_type; #BT_FALSE means
866 \em unsigned, #BT_TRUE means \em signed.
867 @returns 0 on success, or a negative value on error.
869 @prenotnull{int_field_type}
870 @preisintft{int_field_type}
871 @prehot{int_field_type}
872 @postrefcountsame{int_field_type}
874 @sa bt_field_type_integer_is_signed(): Returns the signedness of
875 the integer fields described by a given integer field type.
877 extern int bt_field_type_integer_set_is_signed(
878 struct bt_field_type
*int_field_type
, bt_bool is_signed
);
881 @brief Returns the preferred display base (radix) of the @intfields
882 described by the @intft \p int_field_type.
884 @param[in] int_field_type Integer field type which describes the
885 integer fields of which to get the
886 preferred display base.
887 @returns Preferred display base of the integer
888 fields described by \p int_field_type,
889 #BT_INTEGER_BASE_UNSPECIFIED if
891 #BT_INTEGER_BASE_UNKNOWN on error.
893 @prenotnull{int_field_type}
894 @preisintft{int_field_type}
895 @postrefcountsame{int_field_type}
897 @sa bt_field_type_integer_set_base(): Sets the preferred display
898 base of the integer fields described by a given integer field
901 extern enum bt_integer_base
bt_field_type_integer_get_base(
902 struct bt_field_type
*int_field_type
);
905 @brief Sets the preferred display base (radix) of the @intfields
906 described by the @intft \p int_field_type to \p base.
908 @param[in] int_field_type Integer field type which describes the
909 integer fields of which to set the
910 preferred display base.
911 @param[in] base Preferred display base of the integer
912 fields described by \p int_field_type.
913 @returns 0 on success, or a negative value on error.
915 @prenotnull{int_field_type}
916 @preisintft{int_field_type}
917 @prehot{int_field_type}
918 @pre \p base is #BT_INTEGER_BASE_UNSPECIFIED,
919 #BT_INTEGER_BASE_BINARY, #BT_INTEGER_BASE_OCTAL,
920 #BT_INTEGER_BASE_DECIMAL, or #BT_INTEGER_BASE_HEXADECIMAL.
921 @postrefcountsame{int_field_type}
923 @sa bt_field_type_integer_get_base(): Returns the preferred display
924 base of the integer fields described by a given
927 extern int bt_field_type_integer_set_base(
928 struct bt_field_type
*int_field_type
,
929 enum bt_integer_base base
);
932 @brief Returns the encoding of the @intfields described by
933 the @intft \p int_field_type.
935 @param[in] int_field_type Integer field type which describes the
936 integer fields of which to get the
938 @returns Encoding of the integer
939 fields described by \p int_field_type,
940 or #BT_STRING_ENCODING_UNKNOWN on
943 @prenotnull{int_field_type}
944 @preisintft{int_field_type}
945 @postrefcountsame{int_field_type}
947 @sa bt_field_type_integer_set_encoding(): Sets the encoding
948 of the integer fields described by a given integer field type.
950 extern enum bt_string_encoding
bt_field_type_integer_get_encoding(
951 struct bt_field_type
*int_field_type
);
954 @brief Sets the encoding of the @intfields described by the @intft
955 \p int_field_type to \p encoding.
957 You can use this property, in CTF IR, to create "text" @arrayfts or
958 @seqfts. A text array field type is array field type with an unsigned,
959 8-bit integer field type having an encoding as its element field type.
961 @param[in] int_field_type Integer field type which describes the
962 integer fields of which to set the
964 @param[in] encoding Encoding of the integer
965 fields described by \p int_field_type.
966 @returns 0 on success, or a negative value on error.
968 @prenotnull{int_field_type}
969 @preisintft{int_field_type}
970 @prehot{int_field_type}
971 @pre \p encoding is #BT_STRING_ENCODING_NONE,
972 #BT_STRING_ENCODING_ASCII, or
973 #BT_STRING_ENCODING_UTF8.
974 @postrefcountsame{int_field_type}
976 @sa bt_field_type_integer_get_encoding(): Returns the encoding of
977 the integer fields described by a given integer field type.
979 extern int bt_field_type_integer_set_encoding(
980 struct bt_field_type
*int_field_type
,
981 enum bt_string_encoding encoding
);
983 extern struct bt_clock_class
*bt_field_type_integer_borrow_mapped_clock_class(
984 struct bt_field_type
*int_field_type
);
987 @brief Returns the \link ctfirclockclass CTF IR clock class\endlink
988 mapped to the @intft \p int_field_type.
990 The mapped clock class, if any, indicates the class of the clock which
991 an @intfield described by \p int_field_type should sample or update.
992 This mapped clock class is only indicative.
994 @param[in] int_field_type Integer field type of which to get the
996 @returns Mapped clock class of \p int_field_type,
997 or \c NULL if there's no mapped clock
1000 @prenotnull{int_field_type}
1001 @preisintft{int_field_type}
1002 @postrefcountsame{int_field_type}
1003 @postsuccessrefcountretinc
1005 @sa bt_field_type_integer_set_mapped_clock_class(): Sets the mapped
1006 clock class of a given integer field type.
1009 struct bt_clock_class
*bt_field_type_integer_get_mapped_clock_class(
1010 struct bt_field_type
*int_field_type
)
1012 return bt_get(bt_field_type_integer_borrow_mapped_clock_class(
1017 @brief Sets the \link ctfirclockclass CTF IR clock class\endlink mapped
1018 to the @intft \p int_field_type to \p clock_class.
1020 The mapped clock class, if any, indicates the class of the clock which
1021 an integer field described by \p int_field_type should sample or update.
1022 This mapped clock class is only indicative.
1024 @param[in] int_field_type Integer field type of which to set the
1026 @param[in] clock_class Mapped clock class of \p int_field_type.
1027 @returns 0 on success, or a negative value on error.
1029 @prenotnull{int_field_type}
1030 @prenotnull{clock_class}
1031 @preisintft{int_field_type}
1032 @prehot{int_field_type}
1033 @postrefcountsame{int_field_type}
1034 @postsuccessrefcountinc{clock_class}
1036 @sa bt_field_type_integer_get_mapped_clock_class(): Returns the mapped
1037 clock class of a given integer field type.
1039 extern int bt_field_type_integer_set_mapped_clock_class(
1040 struct bt_field_type
*int_field_type
,
1041 struct bt_clock_class
*clock_class
);
1046 @defgroup ctfirfloatfieldtype CTF IR floating point number field type
1047 @ingroup ctfirfieldtypes
1048 @brief CTF IR floating point number field type.
1051 #include <babeltrace/ctf-ir/field-types.h>
1054 A CTF IR <strong><em>floating point number field type</em></strong> is
1055 a field type that you can use to create concrete @floatfields.
1057 You can create a floating point number field type
1058 with bt_field_type_floating_point_create().
1060 A floating point number field type has the following properties:
1065 <th>Value at creation
1070 <td>\b Alignment (bits) of the described floating point
1073 <td>bt_field_type_get_alignment()
1074 <td>bt_field_type_set_alignment()
1077 <td><strong>Byte order</strong> of the described floating point
1079 <td>#BT_BYTE_ORDER_NATIVE
1080 <td>bt_field_type_get_byte_order()
1081 <td>bt_field_type_set_byte_order()
1084 <td><strong>Exponent storage size</strong> (bits) of the described
1085 floating point number fields
1087 <td>bt_field_type_floating_point_get_exponent_digits()
1088 <td>bt_field_type_floating_point_set_exponent_digits()
1091 <td><strong>Mantissa and sign storage size</strong> (bits) of the
1092 described floating point number fields
1093 <td>24 (23-bit mantissa, 1-bit sign)
1094 <td>bt_field_type_floating_point_get_mantissa_digits()
1095 <td>bt_field_type_floating_point_set_mantissa_digits()
1101 @sa \ref ctfirfieldtypesexamples_floatfieldtype "Examples"
1103 @addtogroup ctfirfloatfieldtype
1108 @brief Creates a default @floatft.
1110 @returns Created floating point number field type,
1111 or \c NULL on error.
1113 @postsuccessrefcountret1
1115 extern struct bt_field_type
*bt_field_type_floating_point_create(void);
1118 @brief Returns the exponent storage size of the @floatfields
1119 described by the @floatft \p float_field_type.
1121 @param[in] float_field_type Floating point number field type which
1122 describes the floating point number
1123 fields of which to get the exponent
1125 @returns Exponent storage size of the
1126 floating point number fields
1127 described by \p float_field_type,
1128 or a negative value on error.
1130 @prenotnull{float_field_type}
1131 @preisfloatft{float_field_type}
1132 @postrefcountsame{float_field_type}
1134 @sa bt_field_type_floating_point_set_exponent_digits(): Sets the
1135 exponent storage size of the floating point number fields
1136 described by a given floating point number field type.
1138 extern int bt_field_type_floating_point_get_exponent_digits(
1139 struct bt_field_type
*float_field_type
);
1142 @brief Sets the exponent storage size of the @floatfields described by
1143 the @floatft \p float_field_type to \p exponent_size.
1145 As of Babeltrace \btversion, \p exponent_size can only be 8 or 11.
1147 @param[in] float_field_type Floating point number field type which
1148 describes the floating point number
1149 fields of which to set the exponent
1151 @param[in] exponent_size Exponent storage size of the floating
1152 point number fields described by \p
1154 @returns 0 on success, or a negative value on error.
1156 @prenotnull{float_field_type}
1157 @preisfloatft{float_field_type}
1158 @prehot{float_field_type}
1159 @pre \p exponent_size is 8 or 11.
1160 @postrefcountsame{float_field_type}
1162 @sa bt_field_type_floating_point_get_exponent_digits(): Returns the
1163 exponent storage size of the floating point number fields
1164 described by a given floating point number field type.
1166 extern int bt_field_type_floating_point_set_exponent_digits(
1167 struct bt_field_type
*float_field_type
,
1168 unsigned int exponent_size
);
1171 @brief Returns the mantissa and sign storage size of the @floatfields
1172 described by the @floatft \p float_field_type.
1174 On success, the returned value is the sum of the mantissa \em and
1177 @param[in] float_field_type Floating point number field type which
1178 describes the floating point number
1179 fields of which to get the mantissa and
1181 @returns Mantissa and sign storage size of the
1182 floating point number fields
1183 described by \p float_field_type,
1184 or a negative value on error.
1186 @prenotnull{float_field_type}
1187 @preisfloatft{float_field_type}
1188 @postrefcountsame{float_field_type}
1190 @sa bt_field_type_floating_point_set_mantissa_digits(): Sets the
1191 mantissa and size storage size of the floating point number
1192 fields described by a given floating point number field type.
1194 extern int bt_field_type_floating_point_get_mantissa_digits(
1195 struct bt_field_type
*float_field_type
);
1198 @brief Sets the mantissa and sign storage size of the @floatfields
1199 described by the @floatft \p float_field_type to \p
1202 As of Babeltrace \btversion, \p mantissa_sign_size can only be 24 or 53.
1204 @param[in] float_field_type Floating point number field type which
1205 describes the floating point number
1206 fields of which to set the mantissa and
1208 @param[in] mantissa_sign_size Mantissa and sign storage size of the
1209 floating point number fields described
1210 by \p float_field_type.
1211 @returns 0 on success, or a negative value on error.
1213 @prenotnull{float_field_type}
1214 @preisfloatft{float_field_type}
1215 @prehot{float_field_type}
1216 @pre \p mantissa_sign_size is 24 or 53.
1217 @postrefcountsame{float_field_type}
1219 @sa bt_field_type_floating_point_get_mantissa_digits(): Returns the
1220 mantissa and sign storage size of the floating point number
1221 fields described by a given floating point number field type.
1223 extern int bt_field_type_floating_point_set_mantissa_digits(
1224 struct bt_field_type
*float_field_type
,
1225 unsigned int mantissa_sign_size
);
1230 @defgroup ctfirenumfieldtype CTF IR enumeration field type
1231 @ingroup ctfirfieldtypes
1232 @brief CTF IR enumeration field type.
1235 #include <babeltrace/ctf-ir/field-types.h>
1238 A CTF IR <strong><em>enumeration field type</em></strong> is
1239 a field type that you can use to create concrete @enumfields.
1241 You can create an enumeration field type with
1242 bt_field_type_enumeration_create(). This function needs a @intft
1243 which represents the storage field type of the created enumeration field
1244 type. In other words, an enumeration field type wraps an integer field
1245 type and adds label-value mappings to it.
1247 An enumeration mapping has:
1249 - A <strong>name</strong>.
1250 - A <strong>range of values</strong> given by a beginning and an ending
1251 value, both included in the range.
1253 You can add a mapping to an enumeration field type with
1254 bt_field_type_enumeration_signed_add_mapping() or
1255 bt_field_type_enumeration_unsigned_add_mapping(), depending on the
1256 signedness of the wrapped @intft.
1258 You can find mappings by name or by value with the following find
1261 - bt_field_type_enumeration_find_mappings_by_name(): Finds the
1262 mappings with a given name.
1263 - bt_field_type_enumeration_unsigned_find_mappings_by_value():
1264 Finds the mappings which contain a given unsigned value in their
1266 - bt_field_type_enumeration_signed_find_mappings_by_value():
1267 Finds the mappings which contain a given signed value in their range.
1269 Those functions return a @enumftiter on the result set of the find
1272 Many mappings can share the same name, and the ranges of a given
1273 enumeration field type are allowed to overlap. For example,
1274 this is a valid set of mappings:
1283 The following set of mappings is also valid:
1292 Here, the range of the second \c APPLE mapping overlaps the range of
1293 the \c CHERRY mapping.
1295 @sa ctfirenumftmappingiter
1299 @addtogroup ctfirenumfieldtype
1304 @brief Creates a default @enumft wrapping the @intft \p int_field_type.
1306 @param[in] int_field_type Integer field type wrapped by the
1307 created enumeration field type.
1308 @returns Created enumeration field type,
1309 or \c NULL on error.
1311 @prenotnull{int_field_type}
1312 @preisintft{int_field_type}
1313 @postsuccessrefcountinc{int_field_type}
1314 @postsuccessrefcountret1
1316 extern struct bt_field_type
*bt_field_type_enumeration_create(
1317 struct bt_field_type
*int_field_type
);
1320 struct bt_field_type
*bt_field_type_enumeration_borrow_container_field_type(
1321 struct bt_field_type
*enum_field_type
);
1324 @brief Returns the @intft wrapped by the @enumft \p enum_field_type.
1326 @param[in] enum_field_type Enumeration field type of which to get
1327 the wrapped integer field type.
1328 @returns Integer field type wrapped by
1329 \p enum_field_type, or \c NULL on
1332 @prenotnull{enum_field_type}
1333 @preisenumft{enum_field_type}
1334 @postrefcountsame{enum_field_type}
1335 @postsuccessrefcountretinc
1338 struct bt_field_type
*bt_field_type_enumeration_get_container_field_type(
1339 struct bt_field_type
*enum_field_type
)
1341 return bt_get(bt_field_type_enumeration_borrow_container_field_type(
1346 @brief Returns the number of mappings contained in the
1347 @enumft \p enum_field_type.
1349 @param[in] enum_field_type Enumeration field type of which to get
1350 the number of contained mappings.
1351 @returns Number of mappings contained in
1352 \p enum_field_type, or a negative
1355 @prenotnull{enum_field_type}
1356 @preisenumft{enum_field_type}
1357 @postrefcountsame{enum_field_type}
1359 extern int64_t bt_field_type_enumeration_get_mapping_count(
1360 struct bt_field_type
*enum_field_type
);
1363 @brief Returns the signed mapping of the @enumft
1364 \p enum_field_type at index \p index.
1366 The @intft wrapped by \p enum_field_type, as returned by
1367 bt_field_type_enumeration_get_container_field_type(), must be \b signed
1368 to use this function.
1370 On success, \p enum_field_type remains the sole owner of \p *name.
1372 @param[in] enum_field_type Enumeration field type of which to get
1373 the mapping at index \p index.
1374 @param[in] index Index of the mapping to get from
1376 @param[out] name Returned name of the mapping at index
1378 @param[out] range_begin Returned beginning of the range
1379 (included) of the mapping at index \p
1381 @param[out] range_end Returned end of the range (included) of
1382 the mapping at index \p index.
1383 @returns 0 on success, or a negative value on error.
1385 @prenotnull{enum_field_type}
1387 @prenotnull{range_begin}
1388 @prenotnull{range_end}
1389 @preisenumft{enum_field_type}
1390 @pre The wrapped @intft of \p enum_field_type is signed.
1391 @pre \p index is lesser than the number of mappings contained in the
1392 enumeration field type \p enum_field_type (see
1393 bt_field_type_enumeration_get_mapping_count()).
1394 @postrefcountsame{enum_field_type}
1396 @sa bt_field_type_enumeration_unsigned_get_mapping_by_index(): Returns the
1397 unsigned mapping contained by a given enumeration field type
1400 extern int bt_field_type_enumeration_signed_get_mapping_by_index(
1401 struct bt_field_type
*enum_field_type
, uint64_t index
,
1402 const char **name
, int64_t *range_begin
, int64_t *range_end
);
1405 @brief Returns the unsigned mapping of the @enumft
1406 \p enum_field_type at index \p index.
1408 The @intft wrapped by \p enum_field_type, as returned by
1409 bt_field_type_enumeration_get_container_field_type(), must be
1410 \b unsigned to use this function.
1412 On success, \p enum_field_type remains the sole owner of \p *name.
1414 @param[in] enum_field_type Enumeration field type of which to get
1415 the mapping at index \p index.
1416 @param[in] index Index of the mapping to get from
1418 @param[out] name Returned name of the mapping at index
1420 @param[out] range_begin Returned beginning of the range
1421 (included) of the mapping at index \p
1423 @param[out] range_end Returned end of the range (included) of
1424 the mapping at index \p index.
1425 @returns 0 on success, or a negative value on error.
1427 @prenotnull{enum_field_type}
1429 @prenotnull{range_begin}
1430 @prenotnull{range_end}
1431 @preisenumft{enum_field_type}
1432 @pre The wrapped @intft of \p enum_field_type is unsigned.
1433 @pre \p index is lesser than the number of mappings contained in the
1434 enumeration field type \p enum_field_type (see
1435 bt_field_type_enumeration_get_mapping_count()).
1436 @postrefcountsame{enum_field_type}
1438 @sa bt_field_type_enumeration_signed_get_mapping_by_index(): Returns the
1439 signed mapping contained by a given enumeration field type
1442 extern int bt_field_type_enumeration_unsigned_get_mapping_by_index(
1443 struct bt_field_type
*enum_field_type
, uint64_t index
,
1444 const char **name
, uint64_t *range_begin
,
1445 uint64_t *range_end
);
1448 @brief Finds the mappings of the @enumft \p enum_field_type which
1451 This function returns an iterator on the result set of this find
1452 operation. See \ref ctfirenumftmappingiter for more details.
1454 @param[in] enum_field_type Enumeration field type of which to find
1455 the mappings named \p name.
1456 @param[in] name Name of the mappings to find in
1458 @returns @enumftiter on the set of mappings named
1459 \p name in \p enum_field_type, or
1460 \c NULL if no mappings were found or
1463 @prenotnull{enum_field_type}
1465 @preisenumft{enum_field_type}
1466 @postrefcountsame{enum_field_type}
1467 @postsuccessrefcountret1
1468 @post <strong>On success</strong>, the returned @enumftiter can iterate
1469 on at least one mapping.
1471 @sa bt_field_type_enumeration_signed_find_mappings_by_value(): Finds
1472 the mappings of a given enumeration field type which contain
1473 a given signed value in their range.
1474 @sa bt_field_type_enumeration_unsigned_find_mappings_by_value(): Finds
1475 the mappings of a given enumeration field type which contain
1476 a given unsigned value in their range.
1478 extern struct bt_field_type_enumeration_mapping_iterator
*
1479 bt_field_type_enumeration_find_mappings_by_name(
1480 struct bt_field_type
*enum_field_type
,
1484 @brief Finds the mappings of the @enumft \p enum_field_type which
1485 contain the signed value \p value in their range.
1487 This function returns an iterator on the result set of this find
1488 operation. See \ref ctfirenumftmappingiter for more details.
1490 @param[in] enum_field_type Enumeration field type of which to find
1491 the mappings which contain \p value.
1492 @param[in] value Value to find in the ranges of the
1493 mappings of \p enum_field_type.
1494 @returns @enumftiter on the set of mappings of
1495 \p enum_field_type which contain
1496 \p value in their range, or \c NULL if
1497 no mappings were found or on error.
1499 @prenotnull{enum_field_type}
1500 @preisenumft{enum_field_type}
1501 @postrefcountsame{enum_field_type}
1502 @postsuccessrefcountret1
1503 @post <strong>On success</strong>, the returned @enumftiter can iterate
1504 on at least one mapping.
1506 @sa bt_field_type_enumeration_find_mappings_by_name(): Finds the
1507 mappings of a given enumeration field type which have a given
1509 @sa bt_field_type_enumeration_unsigned_find_mappings_by_value(): Finds
1510 the mappings of a given enumeration field type which contain
1511 a given unsigned value in their range.
1513 extern struct bt_field_type_enumeration_mapping_iterator
*
1514 bt_field_type_enumeration_signed_find_mappings_by_value(
1515 struct bt_field_type
*enum_field_type
,
1519 @brief Finds the mappings of the @enumft \p enum_field_type which
1520 contain the unsigned value \p value in their range.
1522 This function returns an iterator on the result set of this find
1523 operation. See \ref ctfirenumftmappingiter for more details.
1525 @param[in] enum_field_type Enumeration field type of which to find
1526 the mappings which contain \p value.
1527 @param[in] value Value to find in the ranges of the
1528 mappings of \p enum_field_type.
1529 @returns @enumftiter on the set of mappings of
1530 \p enum_field_type which contain
1531 \p value in their range, or \c NULL
1532 if no mappings were found or
1535 @prenotnull{enum_field_type}
1536 @preisenumft{enum_field_type}
1537 @postrefcountsame{enum_field_type}
1538 @postsuccessrefcountret1
1539 @post <strong>On success</strong>, the returned @enumftiter can iterate
1540 on at least one mapping.
1542 @sa bt_field_type_enumeration_find_mappings_by_name(): Finds the
1543 mappings of a given enumeration field type which have a given
1545 @sa bt_field_type_enumeration_signed_find_mappings_by_value(): Finds
1546 the mappings of a given enumeration field type which contain
1547 a given unsigned value in their range.
1549 extern struct bt_field_type_enumeration_mapping_iterator
*
1550 bt_field_type_enumeration_unsigned_find_mappings_by_value(
1551 struct bt_field_type
*enum_field_type
,
1555 @brief Adds a mapping to the @enumft \p enum_field_type which maps the
1556 name \p name to the signed range \p range_begin (included) to
1557 \p range_end (included).
1559 Make \p range_begin and \p range_end the same value to add a mapping
1562 The @intft wrapped by \p enum_field_type, as returned by
1563 bt_field_type_enumeration_get_container_field_type(), must be
1564 \b signed to use this function.
1566 A mapping in \p enum_field_type can exist with the name \p name.
1568 @param[in] enum_field_type Enumeration field type to which to add
1570 @param[in] name Name of the mapping to add (copied
1572 @param[in] range_begin Beginning of the range of the mapping
1574 @param[in] range_end End of the range of the mapping
1576 @returns 0 on success, or a negative value on error.
1578 @prenotnull{enum_field_type}
1580 @prehot{enum_field_type}
1581 @preisenumft{enum_field_type}
1582 @pre The wrapped @intft of \p enum_field_type is signed.
1583 @pre \p range_end is greater than or equal to \p range_begin.
1584 @postrefcountsame{enum_field_type}
1586 @sa bt_field_type_enumeration_unsigned_add_mapping(): Adds an
1587 unsigned mapping to a given enumeration field type.
1589 extern int bt_field_type_enumeration_signed_add_mapping(
1590 struct bt_field_type
*enum_field_type
, const char *name
,
1591 int64_t range_begin
, int64_t range_end
);
1594 @brief Adds a mapping to the @enumft \p enum_field_type which maps
1595 the name \p name to the unsigned
1596 range \p range_begin (included) to \p range_end (included).
1598 Make \p range_begin and \p range_end the same value to add a mapping
1601 The @intft wrapped by \p enum_field_type, as returned by
1602 bt_field_type_enumeration_get_container_field_type(), must be
1603 \b unsigned to use this function.
1605 A mapping in \p enum_field_type can exist with the name \p name.
1607 @param[in] enum_field_type Enumeration field type to which to add
1609 @param[in] name Name of the mapping to add (copied
1611 @param[in] range_begin Beginning of the range of the mapping
1613 @param[in] range_end End of the range of the mapping
1615 @returns 0 on success, or a negative value on error.
1617 @prenotnull{enum_field_type}
1619 @prehot{enum_field_type}
1620 @preisenumft{enum_field_type}
1621 @pre The wrapped @intft of \p enum_field_type is unsigned.
1622 @pre \p range_end is greater than or equal to \p range_begin.
1623 @postrefcountsame{enum_field_type}
1625 @sa bt_field_type_enumeration_signed_add_mapping(): Adds a signed
1626 mapping to a given enumeration field type.
1628 extern int bt_field_type_enumeration_unsigned_add_mapping(
1629 struct bt_field_type
*enum_field_type
, const char *name
,
1630 uint64_t range_begin
, uint64_t range_end
);
1635 @defgroup ctfirenumftmappingiter CTF IR enumeration field type mapping iterator
1636 @ingroup ctfirenumfieldtype
1637 @brief CTF IR enumeration field type mapping iterator.
1640 #include <babeltrace/ctf-ir/field-types.h>
1643 A CTF IR <strong><em>enumeration field type mapping
1644 iterator</em></strong> is an iterator on @enumft mappings.
1646 You can get an enumeration mapping iterator from one of the following
1649 - Find operations of an @enumft object:
1650 - bt_field_type_enumeration_find_mappings_by_name(): Finds the
1651 mappings with a given name.
1652 - bt_field_type_enumeration_unsigned_find_mappings_by_value():
1653 Finds the mappings which contain a given unsigned value in their
1655 - bt_field_type_enumeration_signed_find_mappings_by_value():
1656 Finds the mappings which contain a given signed value in their range.
1657 - bt_field_enumeration_get_mappings(): Finds the mappings in the
1658 @enumft of an @enumfield containing its current integral value in
1661 Those functions guarantee that the returned iterator can iterate on
1662 at least one mapping. Otherwise, they return \c NULL.
1664 You can get the name and the range of a mapping iterator's current
1666 bt_field_type_enumeration_mapping_iterator_signed_get()
1668 bt_field_type_enumeration_mapping_iterator_unsigned_get(),
1669 depending on the signedness of the @intft wrapped by the
1670 @enumft. If you only need the name of the current mapping, you can
1671 use any of the two functions and set the \p range_begin and \p range_end
1672 parameters to \c NULL.
1674 You can advance an enumeration field type mapping iterator to the next
1676 bt_field_type_enumeration_mapping_iterator_next(). This
1677 function returns a negative value when you reach the end of the
1680 As with any Babeltrace object, CTF IR enumeration field type mapping
1681 iterator objects have <a
1682 href="https://en.wikipedia.org/wiki/Reference_counting">reference
1683 counts</a>. See \ref refs to learn more about the reference counting
1684 management of Babeltrace objects.
1686 @sa ctfirenumfieldtype
1688 @addtogroup ctfirenumftmappingiter
1693 @struct bt_field_type_enumeration_mapping_iterator
1694 @brief A CTF IR enumeration field type mapping iterator.
1695 @sa ctfirenumftmappingiter
1699 @brief Returns the name and the range of the current (signed) mapping
1700 of the @enumftiter \p iter.
1702 If one of \p range_begin or \p range_end is not \c NULL, the @intft
1703 wrapped by the @enumft from which \p iter was obtained, as returned by
1704 bt_field_type_enumeration_get_container_field_type(), must be
1705 \b signed to use this function. Otherwise, if you only need to get the
1706 name of the current mapping, set \p range_begin and \p range_end to
1709 On success, if \p name is not \c NULL, \p *name remains valid as long
1710 as \p iter exists and
1711 bt_field_type_enumeration_mapping_iterator_next() is
1712 \em not called on \p iter.
1714 @param[in] iter Enumeration field type mapping iterator
1715 of which to get the range of the current
1717 @param[out] name Returned name of the current mapping of
1718 \p iter (can be \c NULL to ignore).
1719 @param[out] range_begin Returned beginning of the range
1720 (included) of the current mapping of
1721 \p iter (can be \c NULL to ignore).
1722 @param[out] range_end Returned end of the range
1723 (included) of the current mapping of
1724 \p iter (can be \c NULL to ignore).
1725 @returns 0 on success, or a negative value on error.
1728 @postrefcountsame{iter}
1730 @sa bt_field_type_enumeration_mapping_iterator_unsigned_get():
1731 Returns the name and the unsigned range of the current mapping
1732 of a given enumeration field type mapping iterator.
1734 extern int bt_field_type_enumeration_mapping_iterator_signed_get(
1735 struct bt_field_type_enumeration_mapping_iterator
*iter
,
1736 const char **name
, int64_t *range_begin
, int64_t *range_end
);
1739 @brief Returns the name and the range of the current (unsigned) mapping
1740 of the @enumftiter \p iter.
1742 If one of \p range_begin or \p range_end is not \c NULL, the @intft
1743 wrapped by the @enumft from which \p iter was obtained, as returned by
1744 bt_field_type_enumeration_get_container_field_type(), must be
1745 \b unsigned to use this function. Otherwise, if you only need to get the
1746 name of the current mapping, set \p range_begin and \p range_end to
1749 On success, if \p name is not \c NULL, \p *name remains valid as long
1750 as \p iter exists and
1751 bt_field_type_enumeration_mapping_iterator_next() is
1752 \em not called on \p iter.
1754 @param[in] iter Enumeration field type mapping iterator
1755 of which to get the range of the current
1757 @param[out] name Returned name of the current mapping of
1758 \p iter (can be \c NULL to ignore).
1759 @param[out] range_begin Returned beginning of the range
1760 (included) of the current mapping of
1761 \p iter (can be \c NULL to ignore).
1762 @param[out] range_end Returned end of the range
1763 (included) of the current mapping of
1764 \p iter (can be \c NULL to ignore).
1765 @returns 0 on success, or a negative value on error.
1768 @postrefcountsame{iter}
1771 bt_field_type_enumeration_mapping_iterator_signed_get():
1772 Returns the name and the signed range of the current mapping of
1773 a given enumeration field type mapping iterator.
1775 extern int bt_field_type_enumeration_mapping_iterator_unsigned_get(
1776 struct bt_field_type_enumeration_mapping_iterator
*iter
,
1777 const char **name
, uint64_t *range_begin
, uint64_t *range_end
);
1780 @brief Advances the @enumftiter \p iter to the next mapping.
1782 @param[in] iter Enumeration field type mapping iterator to
1784 @returns 0 on success, or a negative value on error or
1785 when you reach the end of the set.
1788 @postrefcountsame{iter}
1790 extern int bt_field_type_enumeration_mapping_iterator_next(
1791 struct bt_field_type_enumeration_mapping_iterator
*iter
);
1796 @defgroup ctfirstringfieldtype CTF IR string field type
1797 @ingroup ctfirfieldtypes
1798 @brief CTF IR string field type.
1801 #include <babeltrace/ctf-ir/field-types.h>
1804 A CTF IR <strong><em>string field type</em></strong> is a field type that
1805 you can use to create concrete @stringfields.
1807 You can create a string field type
1808 with bt_field_type_string_create().
1810 A string field type has only one property: the \b encoding of its
1811 described @stringfields. By default, the encoding of the string fields
1812 described by a string field type is #BT_STRING_ENCODING_UTF8. You
1813 can set the encoding of the string fields described by a string field
1814 type with bt_field_type_string_set_encoding().
1816 @sa ctfirstringfield
1819 @addtogroup ctfirstringfieldtype
1824 @brief Creates a default @stringft.
1826 @returns Created string field type, or \c NULL on error.
1828 @postsuccessrefcountret1
1830 extern struct bt_field_type
*bt_field_type_string_create(void);
1833 @brief Returns the encoding of the @stringfields described by
1834 the @stringft \p string_field_type.
1836 @param[in] string_field_type String field type which describes the
1837 string fields of which to get the
1839 @returns Encoding of the string
1840 fields described by \p string_field_type,
1841 or #BT_STRING_ENCODING_UNKNOWN on
1844 @prenotnull{string_field_type}
1845 @preisstringft{string_field_type}
1846 @postrefcountsame{string_field_type}
1848 @sa bt_field_type_string_set_encoding(): Sets the encoding
1849 of the string fields described by a given string field type.
1851 extern enum bt_string_encoding
bt_field_type_string_get_encoding(
1852 struct bt_field_type
*string_field_type
);
1855 @brief Sets the encoding of the @stringfields described by the
1856 @stringft \p string_field_type to \p encoding.
1858 @param[in] string_field_type String field type which describes the
1859 string fields of which to set the
1861 @param[in] encoding Encoding of the string fields described
1862 by \p string_field_type.
1863 @returns 0 on success, or a negative value on error.
1865 @prenotnull{string_field_type}
1866 @preisstringft{string_field_type}
1867 @prehot{string_field_type}
1868 @pre \p encoding is #BT_STRING_ENCODING_ASCII or
1869 #BT_STRING_ENCODING_UTF8.
1870 @postrefcountsame{string_field_type}
1872 @sa bt_field_type_string_get_encoding(): Returns the encoding of
1873 the string fields described by a given string field type.
1875 extern int bt_field_type_string_set_encoding(
1876 struct bt_field_type
*string_field_type
,
1877 enum bt_string_encoding encoding
);
1882 @defgroup ctfirstructfieldtype CTF IR structure field type
1883 @ingroup ctfirfieldtypes
1884 @brief CTF IR structure field type.
1887 #include <babeltrace/ctf-ir/field-types.h>
1890 A CTF IR <strong><em>structure field type</em></strong> is
1891 a field type that you can use to create concrete @structfields.
1893 You can create a structure field type
1894 with bt_field_type_structure_create(). This function creates
1895 an empty structure field type, with no fields.
1897 You can add a field to a structure field type with
1898 bt_field_type_structure_add_field(). Two fields in a structure
1899 field type cannot have the same name.
1901 You can set the \em minimum alignment of the structure fields described
1902 by a structure field type with the common
1903 bt_field_type_set_alignment() function. The \em effective alignment
1904 of the structure fields described by a structure field type, as per
1905 <a href="http://diamon.org/ctf/">CTF</a>, is the \em maximum value amongst
1906 the effective alignments of all its fields. Note that the effective
1907 alignment of @varfields is always 1.
1909 You can set the byte order of <em>all the contained fields</em>,
1910 recursively, of a structure field type with the common
1911 bt_field_type_set_byte_order() function.
1913 @sa ctfirstructfield
1916 @addtogroup ctfirstructfieldtype
1921 @brief Creates a default, empty @structft.
1923 @returns Created structure field type,
1924 or \c NULL on error.
1926 @postsuccessrefcountret1
1928 extern struct bt_field_type
*bt_field_type_structure_create(void);
1931 @brief Returns the number of fields contained in the
1932 @structft \p struct_field_type.
1934 @param[in] struct_field_type Structure field type of which to get
1935 the number of contained fields.
1936 @returns Number of fields contained in
1937 \p struct_field_type, or a negative
1940 @prenotnull{struct_field_type}
1941 @preisstructft{struct_field_type}
1942 @postrefcountsame{struct_field_type}
1944 extern int64_t bt_field_type_structure_get_field_count(
1945 struct bt_field_type
*struct_field_type
);
1947 extern int bt_field_type_structure_borrow_field_by_index(
1948 struct bt_field_type
*struct_field_type
,
1949 const char **field_name
, struct bt_field_type
**field_type
,
1953 @brief Returns the field of the @structft \p struct_field_type
1956 On success, the field's type is placed in \p *field_type if
1957 \p field_type is not \c NULL. The field's name is placed in
1958 \p *field_name if \p field_name is not \c NULL.
1959 \p struct_field_type remains the sole owner of \p *field_name.
1961 @param[in] struct_field_type Structure field type of which to get
1962 the field at index \p index.
1963 @param[out] field_name Returned name of the field at index
1964 \p index (can be \c NULL).
1965 @param[out] field_type Returned field type of the field
1966 at index \p index (can be \c NULL).
1967 @param[in] index Index of the field to get from
1968 \p struct_field_type.
1969 @returns 0 on success, or a negative value on error.
1971 @prenotnull{struct_field_type}
1972 @preisstructft{struct_field_type}
1973 @pre \p index is lesser than the number of fields contained in the
1974 structure field type \p struct_field_type (see
1975 bt_field_type_structure_get_field_count()).
1976 @postrefcountsame{struct_field_type}
1977 @post <strong>On success</strong>, the returned field's type is placed
1978 in \p *field_type and its reference count is incremented.
1980 @sa bt_field_type_structure_get_field_type_by_name(): Finds a
1981 structure field type's field by name.
1984 int bt_field_type_structure_get_field_by_index(
1985 struct bt_field_type
*struct_field_type
,
1986 const char **field_name
, struct bt_field_type
**field_type
,
1989 int ret
= bt_field_type_structure_borrow_field_by_index(
1990 struct_field_type
, field_name
, field_type
, index
);
1992 if (ret
== 0 && field_type
) {
1993 bt_get(*field_type
);
2000 struct bt_field_type
*bt_field_type_structure_borrow_field_type_by_name(
2001 struct bt_field_type
*struct_field_type
,
2002 const char *field_name
);
2005 @brief Returns the type of the field named \p field_name found in
2006 the @structft \p struct_field_type.
2008 @param[in] struct_field_type Structure field type of which to get
2010 @param[in] field_name Name of the field to find.
2011 @returns Type of the field named \p field_name in
2012 \p struct_field_type, or
2015 @prenotnull{struct_field_type}
2016 @prenotnull{field_name}
2017 @preisstructft{struct_field_type}
2018 @postrefcountsame{struct_field_type}
2019 @postsuccessrefcountretinc
2021 @sa bt_field_type_structure_get_field_by_index(): Finds a
2022 structure field type's field by index.
2025 struct bt_field_type
*bt_field_type_structure_get_field_type_by_name(
2026 struct bt_field_type
*struct_field_type
,
2027 const char *field_name
)
2029 return bt_get(bt_field_type_structure_borrow_field_type_by_name(
2030 struct_field_type
, field_name
));
2034 @brief Adds a field named \p field_name with the @ft
2035 \p field_type to the @structft \p struct_field_type.
2037 On success, \p field_type becomes the child of \p struct_field_type.
2039 This function adds the new field after the current last field of
2040 \p struct_field_type (append mode).
2042 You \em cannot add a field named \p field_name if there's already a
2043 field named \p field_name in \p struct_field_type.
2045 @param[in] struct_field_type Structure field type to which to add
2047 @param[in] field_type Field type of the field to add to
2048 \p struct_field_type.
2049 @param[in] field_name Name of the field to add to
2050 \p struct_field_type
2051 (copied on success).
2052 @returns 0 on success, or a negative value on error.
2054 @prenotnull{struct_field_type}
2055 @prenotnull{field_type}
2056 @prenotnull{field_name}
2057 @preisstructft{struct_field_type}
2058 @pre \p field_type is not and does not contain \p struct_field_type,
2059 recursively, as a field's type.
2060 @prehot{struct_field_type}
2061 @postrefcountsame{struct_field_type}
2062 @postsuccessrefcountinc{field_type}
2064 extern int bt_field_type_structure_add_field(
2065 struct bt_field_type
*struct_field_type
,
2066 struct bt_field_type
*field_type
,
2067 const char *field_name
);
2072 @defgroup ctfirarrayfieldtype CTF IR array field type
2073 @ingroup ctfirfieldtypes
2074 @brief CTF IR array field type.
2077 #include <babeltrace/ctf-ir/field-types.h>
2080 A CTF IR <strong><em>array field type</em></strong> is a field type that
2081 you can use to create concrete @arrayfields.
2083 You can create an array field type
2084 with bt_field_type_array_create(). This function needs
2085 the @ft of the fields contained by the array fields described by the
2086 array field type to create.
2091 @addtogroup ctfirarrayfieldtype
2096 @brief Creates a default @arrayft with
2097 \p element_field_type as the field type of the fields contained
2098 in its described @arrayfields of length \p length.
2100 @param[in] element_field_type Field type of the fields contained in
2101 the array fields described by the
2102 created array field type.
2103 @param[in] length Length of the array fields described by
2104 the created array field type.
2105 @returns Created array field type, or
2108 @prenotnull{element_field_type}
2109 @postsuccessrefcountinc{element_field_type}
2110 @postsuccessrefcountret1
2112 extern struct bt_field_type
*bt_field_type_array_create(
2113 struct bt_field_type
*element_field_type
,
2114 unsigned int length
);
2116 extern struct bt_field_type
*bt_field_type_array_borrow_element_field_type(
2117 struct bt_field_type
*array_field_type
);
2120 @brief Returns the @ft of the @fields contained in
2121 the @arrayfields described by the @arrayft \p array_field_type.
2123 @param[in] array_field_type Array field type of which to get
2124 the type of the fields contained in its
2125 described array fields.
2126 @returns Type of the fields contained in the
2127 array fields described by
2128 \p array_field_type, or \c NULL
2131 @prenotnull{array_field_type}
2132 @preisarrayft{array_field_type}
2133 @postrefcountsame{array_field_type}
2134 @postsuccessrefcountretinc
2137 struct bt_field_type
*bt_field_type_array_get_element_field_type(
2138 struct bt_field_type
*array_field_type
)
2140 return bt_get(bt_field_type_array_borrow_element_field_type(
2145 @brief Returns the number of @fields contained in the
2146 @arrayfields described by the @arrayft \p array_field_type.
2148 @param[in] array_field_type Array field type of which to get
2149 the number of fields contained in its
2150 described array fields.
2151 @returns Number of fields contained in the
2152 array fields described by
2153 \p array_field_type, or a negative value
2156 @prenotnull{array_field_type}
2157 @preisarrayft{array_field_type}
2158 @postrefcountsame{array_field_type}
2160 extern int64_t bt_field_type_array_get_length(
2161 struct bt_field_type
*array_field_type
);
2166 @defgroup ctfirseqfieldtype CTF IR sequence field type
2167 @ingroup ctfirfieldtypes
2168 @brief CTF IR sequence field type.
2171 #include <babeltrace/ctf-ir/field-types.h>
2174 A CTF IR <strong><em>sequence field type</em></strong> is
2175 a field type that you can use to create concrete @seqfields.
2177 You can create a sequence field type with
2178 bt_field_type_sequence_create(). This function needs the @ft
2179 of the fields contained by the sequence fields described by the created
2180 sequence field type. This function also needs the length name of the
2181 sequence field type to create. The length name is used to automatically
2182 resolve the length's field type. See \ref ctfirfieldtypes to learn more
2183 about the automatic resolving.
2188 @addtogroup ctfirseqfieldtype
2193 @brief Creates a default @seqft with \p element_field_type as the
2194 @ft of the @fields contained in its described @seqfields
2195 with the length name \p length_name.
2197 \p length_name can be an absolute or relative reference. See
2198 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2200 @param[in] element_field_type Field type of the fields contained in
2201 the sequence fields described by the
2202 created sequence field type.
2203 @param[in] length_name Length name (copied on success).
2204 @returns Created array field type, or
2207 @prenotnull{element_field_type}
2208 @prenotnull{length_name}
2209 @postsuccessrefcountinc{element_field_type}
2210 @postsuccessrefcountret1
2212 extern struct bt_field_type
*bt_field_type_sequence_create(
2213 struct bt_field_type
*element_field_type
,
2214 const char *length_name
);
2216 extern struct bt_field_type
*bt_field_type_sequence_borrow_element_field_type(
2217 struct bt_field_type
*sequence_field_type
);
2220 @brief Returns the @ft of the @fields contained in the @seqft
2221 described by the @seqft \p sequence_field_type.
2223 @param[in] sequence_field_type Sequence field type of which to get
2224 the type of the fields contained in its
2225 described sequence fields.
2226 @returns Type of the fields contained in the
2227 sequence fields described by
2228 \p sequence_field_type, or \c NULL
2231 @prenotnull{sequence_field_type}
2232 @preisseqft{sequence_field_type}
2233 @postrefcountsame{sequence_field_type}
2234 @postsuccessrefcountretinc
2237 struct bt_field_type
*bt_field_type_sequence_get_element_field_type(
2238 struct bt_field_type
*sequence_field_type
)
2240 return bt_get(bt_field_type_sequence_borrow_element_field_type(
2241 sequence_field_type
));
2245 @brief Returns the length name of the @seqft \p sequence_field_type.
2247 On success, \p sequence_field_type remains the sole owner of
2248 the returned string.
2250 @param[in] sequence_field_type Sequence field type of which to get the
2252 @returns Length name of \p sequence_field_type,
2253 or \c NULL on error.
2255 @prenotnull{sequence_field_type}
2256 @preisseqft{sequence_field_type}
2258 @sa bt_field_type_sequence_get_length_field_path(): Returns the
2259 length's CTF IR field path of a given sequence field type.
2261 extern const char *bt_field_type_sequence_get_length_field_name(
2262 struct bt_field_type
*sequence_field_type
);
2264 extern struct bt_field_path
*bt_field_type_sequence_borrow_length_field_path(
2265 struct bt_field_type
*sequence_field_type
);
2268 @brief Returns the length's CTF IR field path of the @seqft
2269 \p sequence_field_type.
2271 The length's field path of a sequence field type is set when automatic
2272 resolving is performed (see \ref ctfirfieldtypes).
2274 @param[in] sequence_field_type Sequence field type of which to get the
2275 length's field path.
2276 @returns Length's field path of
2277 \p sequence_field_type, or
2278 \c NULL if the length's field path is
2279 not set yet is not set or on error.
2281 @prenotnull{sequence_field_type}
2282 @preisseqft{sequence_field_type}
2283 @postsuccessrefcountretinc
2285 @sa bt_field_type_sequence_get_length_field_name(): Returns the
2286 length's name of a given sequence field type.
2289 struct bt_field_path
*bt_field_type_sequence_get_length_field_path(
2290 struct bt_field_type
*sequence_field_type
)
2292 return bt_get(bt_field_type_sequence_borrow_length_field_path(
2293 sequence_field_type
));
2299 @defgroup ctfirvarfieldtype CTF IR variant field type
2300 @ingroup ctfirfieldtypes
2301 @brief CTF IR variant field type.
2304 #include <babeltrace/ctf-ir/field-types.h>
2307 A CTF IR <strong><em>variant field type</em></strong> is
2308 a field type that you can use to create concrete @varfields.
2310 You can create a variant field type with
2311 bt_field_type_variant_create(). This function expects you to pass
2312 both the tag's @enumft and the tag name of the variant field type to
2313 create. The tag's field type is optional, as the Babeltrace system can
2314 automatically resolve it using the tag name. You can leave the tag name
2315 to \c NULL initially, and set it later with
2316 bt_field_type_variant_set_tag_name(). The tag name must be set when
2317 the variant field type is frozen. See \ref ctfirfieldtypes to learn more
2318 about the automatic resolving and the conditions under which a field
2321 You can add a field to a variant field type with
2322 bt_field_type_variant_add_field(). All the field names of a
2323 variant field type \em must exist as mapping names in its tag's @enumft.
2325 The effective alignment of the @varfields described by a
2326 variant field type is always 1, but the individual fields of a
2327 @varfield can have custom alignments.
2329 You can set the byte order of <em>all the contained fields</em>,
2330 recursively, of a variant field type with the common
2331 bt_field_type_set_byte_order() function.
2336 @addtogroup ctfirvarfieldtype
2341 @brief Creates a default, empty @varft with the tag's @enumft
2342 \p tag_field_type and the tag name \p tag_name.
2344 \p tag_field_type can be \c NULL; the tag's field type can be
2345 automatically resolved from the variant field type's tag name (see
2346 \ref ctfirfieldtypes). If \p tag_name is \c NULL, it \em must be set
2347 with bt_field_type_variant_set_tag_name() \em before the variant
2348 field type is frozen.
2350 \p tag_name can be an absolute or relative reference. See
2351 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2353 @param[in] tag_field_type Tag's enumeration field type
2355 @param[in] tag_name Tag name (copied on success,
2357 @returns Created variant field type, or
2360 @pre \p tag_field_type is an enumeration field type or \c NULL.
2361 @post <strong>On success, if \p tag_field_type is not \c NULL</strong>,
2362 its reference count is incremented.
2363 @postsuccessrefcountret1
2365 extern struct bt_field_type
*bt_field_type_variant_create(
2366 struct bt_field_type
*tag_field_type
,
2367 const char *tag_name
);
2369 extern struct bt_field_type
*bt_field_type_variant_borrow_tag_field_type(
2370 struct bt_field_type
*variant_field_type
);
2373 @brief Returns the tag's @enumft of the @varft \p variant_field_type.
2375 @param[in] variant_field_type Variant field type of which to get
2376 the tag's enumeration field type.
2377 @returns Tag's enumeration field type of
2378 \p variant_field_type, or \c NULL if the
2379 tag's field type is not set or on
2382 @prenotnull{variant_field_type}
2383 @preisvarft{variant_field_type}
2384 @postrefcountsame{variant_field_type}
2385 @postsuccessrefcountretinc
2388 struct bt_field_type
*bt_field_type_variant_get_tag_field_type(
2389 struct bt_field_type
*variant_field_type
)
2391 return bt_get(bt_field_type_variant_borrow_tag_field_type(
2392 variant_field_type
));
2396 @brief Returns the tag name of the @varft \p variant_field_type.
2398 On success, \p variant_field_type remains the sole owner of
2399 the returned string.
2401 @param[in] variant_field_type Variant field type of which to get the
2403 @returns Tag name of \p variant_field_type, or
2404 \c NULL if the tag name is not set or
2407 @prenotnull{variant_field_type}
2408 @preisvarft{variant_field_type}
2410 @sa bt_field_type_variant_set_tag_name(): Sets the tag name of
2411 a given variant field type.
2412 @sa bt_field_type_variant_get_tag_field_path(): Returns the tag's
2413 CTF IR field path of a given variant field type.
2415 extern const char *bt_field_type_variant_get_tag_name(
2416 struct bt_field_type
*variant_field_type
);
2419 @brief Sets the tag name of the @varft \p variant_field_type.
2421 \p tag_name can be an absolute or relative reference. See
2422 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2424 @param[in] variant_field_type Variant field type of which to set
2426 @param[in] tag_name Tag name of \p variant_field_type
2427 (copied on success).
2428 @returns 0 on success, or a negative value on error.
2430 @prenotnull{variant_field_type}
2432 @prehot{variant_field_type}
2433 @postrefcountsame{variant_field_type}
2435 @sa bt_field_type_variant_get_tag_name(): Returns the tag name of
2436 a given variant field type.
2438 extern int bt_field_type_variant_set_tag_name(
2439 struct bt_field_type
*variant_field_type
,
2440 const char *tag_name
);
2442 extern struct bt_field_path
*bt_field_type_variant_borrow_tag_field_path(
2443 struct bt_field_type
*variant_field_type
);
2446 @brief Returns the tag's CTF IR field path of the @varft
2447 \p variant_field_type.
2449 The tag's field path of a variant field type is set when automatic
2450 resolving is performed (see \ref ctfirfieldtypes).
2452 @param[in] variant_field_type Variant field type of which to get the
2454 @returns Tag's field path of
2455 \p variant_field_type, or
2456 \c NULL if the tag's field path is not
2457 set yet is not set or on error.
2459 @prenotnull{variant_field_type}
2460 @preisvarft{variant_field_type}
2461 @postsuccessrefcountretinc
2463 @sa bt_field_type_variant_get_tag_name(): Returns the tag's
2464 name of a given variant field type.
2467 struct bt_field_path
*bt_field_type_variant_get_tag_field_path(
2468 struct bt_field_type
*variant_field_type
)
2470 return bt_get(bt_field_type_variant_borrow_tag_field_path(
2471 variant_field_type
));
2475 @brief Returns the number of fields (choices) contained in the @varft
2476 \p variant_field_type.
2478 @param[in] variant_field_type Variant field type of which to get
2479 the number of contained fields.
2480 @returns Number of fields contained in
2481 \p variant_field_type, or a negative
2484 @prenotnull{variant_field_type}
2485 @preisvarft{variant_field_type}
2486 @postrefcountsame{variant_field_type}
2488 extern int64_t bt_field_type_variant_get_field_count(
2489 struct bt_field_type
*variant_field_type
);
2491 extern int bt_field_type_variant_borrow_field_by_index(
2492 struct bt_field_type
*variant_field_type
,
2493 const char **field_name
,
2494 struct bt_field_type
**field_type
, uint64_t index
);
2497 @brief Returns the field (choice) of the @varft \p variant_field_type
2500 On success, the field's type is placed in \p *field_type if
2501 \p field_type is not \c NULL. The field's name is placed in
2502 \p *field_name if \p field_name is not \c NULL.
2503 \p variant_field_type remains the sole owner of \p *field_name.
2505 @param[in] variant_field_type Variant field type of which to get
2506 the field at index \p index.
2507 @param[out] field_name Returned name of the field at index
2508 \p index (can be \c NULL).
2509 @param[out] field_type Returned field type of the field
2510 at index \p index (can be \c NULL).
2511 @param[in] index Index of the field to get from
2512 \p variant_field_type.
2513 @returns 0 on success, or a negative value on error.
2515 @prenotnull{variant_field_type}
2516 @preisvarft{variant_field_type}
2517 @pre \p index is lesser than the number of fields contained in the
2518 variant field type \p variant_field_type (see
2519 bt_field_type_variant_get_field_count()).
2520 @postrefcountsame{variant_field_type}
2521 @post <strong>On success</strong>, the returned field's type is placed
2522 in \p *field_type and its reference count is incremented.
2524 @sa bt_field_type_variant_get_field_type_by_name(): Finds a variant
2525 field type's field by name.
2526 @sa bt_field_type_variant_get_field_type_from_tag(): Finds a variant
2527 field type's field by current tag value.
2530 int bt_field_type_variant_get_field_by_index(
2531 struct bt_field_type
*variant_field_type
,
2532 const char **field_name
,
2533 struct bt_field_type
**field_type
, uint64_t index
)
2535 int ret
= bt_field_type_variant_borrow_field_by_index(
2536 variant_field_type
, field_name
, field_type
, index
);
2538 if (ret
== 0 && field_type
) {
2539 bt_get(*field_type
);
2546 struct bt_field_type
*bt_field_type_variant_borrow_field_type_by_name(
2547 struct bt_field_type
*variant_field_type
,
2548 const char *field_name
);
2551 @brief Returns the type of the field (choice) named \p field_name
2552 found in the @varft \p variant_field_type.
2554 @param[in] variant_field_type Variant field type of which to get
2556 @param[in] field_name Name of the field to find.
2557 @returns Type of the field named \p field_name in
2558 \p variant_field_type, or
2561 @prenotnull{variant_field_type}
2562 @prenotnull{field_name}
2563 @preisvarft{variant_field_type}
2564 @postrefcountsame{variant_field_type}
2565 @postsuccessrefcountretinc
2567 @sa bt_field_type_variant_get_field_by_index(): Finds a variant field type's
2569 @sa bt_field_type_variant_get_field_type_from_tag(): Finds a variant
2570 field type's field by current tag value.
2573 struct bt_field_type
*bt_field_type_variant_get_field_type_by_name(
2574 struct bt_field_type
*variant_field_type
,
2575 const char *field_name
)
2577 return bt_get(bt_field_type_variant_borrow_field_type_by_name(
2578 variant_field_type
, field_name
));
2582 struct bt_field_type
*bt_field_type_variant_borrow_field_type_from_tag(
2583 struct bt_field_type
*variant_field_type
,
2584 struct bt_field
*tag_field
);
2587 @brief Returns the type of the field (choice) selected by the value of
2588 the @enumfield \p tag_field in the @varft \p variant_field_type.
2590 \p tag_field is the current tag value.
2592 The field type of \p tag_field, as returned by bt_field_get_type(),
2593 \em must be equivalent to the field type returned by
2594 bt_field_type_variant_get_tag_field_type() for \p variant_field_type.
2596 @param[in] variant_field_type Variant field type of which to get
2598 @param[in] tag_field Current tag value (variant field type's
2600 @returns Type of the field selected by
2601 \p tag_field in \p variant_field_type,
2602 or \c NULL on error.
2604 @prenotnull{variant_field_type}
2605 @prenotnull{tag_field}
2606 @preisvarft{variant_field_type}
2607 @preisenumfield{tag_field}
2608 @postrefcountsame{variant_field_type}
2609 @postrefcountsame{tag_field}
2610 @postsuccessrefcountretinc
2612 @sa bt_field_type_variant_get_field_by_index(): Finds a variant field type's
2614 @sa bt_field_type_variant_get_field_type_by_name(): Finds a variant
2615 field type's field by name.
2618 struct bt_field_type
*bt_field_type_variant_get_field_type_from_tag(
2619 struct bt_field_type
*variant_field_type
,
2620 struct bt_field
*tag_field
)
2622 return bt_get(bt_field_type_variant_borrow_field_type_from_tag(
2623 variant_field_type
, tag_field
));
2627 @brief Adds a field (a choice) named \p field_name with the @ft
2628 \p field_type to the @varft \p variant_field_type.
2630 On success, \p field_type becomes the child of \p variant_field_type.
2632 You \em cannot add a field named \p field_name if there's already a
2633 field named \p field_name in \p variant_field_type.
2635 \p field_name \em must name an existing mapping in the tag's
2636 enumeration field type of \p variant_field_type.
2638 @param[in] variant_field_type Variant field type to which to add
2640 @param[in] field_type Field type of the field to add to
2641 \p variant_field_type.
2642 @param[in] field_name Name of the field to add to
2643 \p variant_field_type
2644 (copied on success).
2645 @returns 0 on success, or a negative value on error.
2647 @prenotnull{variant_field_type}
2648 @prenotnull{field_type}
2649 @prenotnull{field_name}
2650 @preisvarft{variant_field_type}
2651 @pre \p field_type is not and does not contain \p variant_field_type,
2652 recursively, as a field's type.
2653 @prehot{variant_field_type}
2654 @postrefcountsame{variant_field_type}
2655 @postsuccessrefcountinc{field_type}
2657 extern int bt_field_type_variant_add_field(
2658 struct bt_field_type
*variant_field_type
,
2659 struct bt_field_type
*field_type
,
2660 const char *field_name
);
2668 #endif /* BABELTRACE_CTF_IR_FIELD_TYPES_H */