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
40 @defgroup ctfirfieldtypes CTF IR field types
42 @brief CTF IR field types.
45 #include <babeltrace/ctf-ir/field-types.h>
48 A CTF IR <strong><em>field type</em></strong> is a field type that you
49 can use to create concrete @fields.
51 You can create a @field object from a CTF IR field type object
52 with bt_ctf_field_create().
54 In the CTF IR hierarchy, you can set the root field types of three
57 - \ref ctfirtraceclass
58 - Trace packet header field type: bt_ctf_trace_set_packet_header_type().
59 - \ref ctfirstreamclass
60 - Stream packet context field type:
61 bt_ctf_stream_class_set_packet_context_type().
62 - Stream event header field type:
63 bt_ctf_stream_class_set_event_header_type().
64 - Stream event context field type:
65 bt_ctf_stream_class_set_event_context_type().
66 - \ref ctfireventclass
67 - Event context field type: bt_ctf_event_class_set_context_type().
68 - Event payload field type: bt_ctf_event_class_set_payload_type().
70 As of Babeltrace \btversion, those six previous "root" field types
71 \em must be @structft objects.
73 If, at any level within a given root field type, you add a @seqft or a
74 @varft, you do not need to specify its associated length
75 or tag field type: the length or tag string is enough for the Babeltrace
76 system to resolve the needed field type depending on where this
77 dynamic field type is located within the whole hierarchy. It is
78 guaranteed that this automatic resolving is performed for all the field
79 types contained in a given
80 \link ctfirstreamclass CTF IR stream class\endlink (and in its
81 children \link ctfireventclass CTF IR event classes\endlink) once you
82 add it to a \link ctfirtraceclass CTF IR trace class\endlink with
83 bt_ctf_trace_add_stream_class(). Once a stream class is the child of
84 a trace class, this automatic resolving is performed for the field
85 types of an event class when you add it with
86 bt_ctf_stream_class_add_event_class(). If the system cannot find a path
87 to a field in the hierarchy for a dynamic field type, the adding
90 The standard CTF field types are:
96 <th>CTF IR field which you can create from this field type
99 <td>#BT_CTF_TYPE_ID_INTEGER
100 <td>\ref ctfirintfieldtype
101 <td>\ref ctfirintfield
104 <td>#BT_CTF_TYPE_ID_FLOAT
105 <td>\ref ctfirfloatfieldtype
106 <td>\ref ctfirfloatfield
109 <td>#BT_CTF_TYPE_ID_ENUM
110 <td>\ref ctfirenumfieldtype
111 <td>\ref ctfirenumfield
114 <td>#BT_CTF_TYPE_ID_STRING
115 <td>\ref ctfirstringfieldtype
116 <td>\ref ctfirstringfield
119 <td>#BT_CTF_TYPE_ID_STRUCT
120 <td>\ref ctfirstructfieldtype
121 <td>\ref ctfirstructfield
124 <td>#BT_CTF_TYPE_ID_ARRAY
125 <td>\ref ctfirarrayfieldtype
126 <td>\ref ctfirarrayfield
129 <td>#BT_CTF_TYPE_ID_SEQUENCE
130 <td>\ref ctfirseqfieldtype
131 <td>\ref ctfirseqfield
134 <td>#BT_CTF_TYPE_ID_VARIANT
135 <td>\ref ctfirvarfieldtype
136 <td>\ref ctfirvarfield
140 Each field type has its own <strong>type ID</strong> (see
141 #bt_ctf_type_id). You get the type ID of a field type object
142 with bt_ctf_field_type_get_type_id().
144 You can get a deep copy of a field type with bt_ctf_field_type_copy().
145 This function resets, in the field type copy, the resolved field type
146 of the dynamic field types. The automatic resolving can be done again
147 when you eventually call bt_ctf_event_create(),
148 bt_ctf_stream_class_add_event_class(), or
149 bt_ctf_trace_add_stream_class().
151 You \em must always use bt_ctf_field_type_compare() to compare two
152 field types. Since some parts of the Babeltrace system can copy field
153 types behind the scenes, you \em cannot rely on a simple field type
156 As with any Babeltrace object, CTF IR field type objects have
157 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
158 counts</a>. See \ref refs to learn more about the reference counting
159 management of Babeltrace objects.
161 The following functions can \em freeze field type objects:
163 - bt_ctf_field_create() freezes its field type parameter.
164 - bt_ctf_stream_class_add_event_class(), if its
165 \link ctfirstreamclass CTF IR stream class\endlink parameter has a
166 \link ctfirtraceclass CTF IR trace class\endlink parent, freezes
167 the root field types of its
168 \link ctfireventclass CTF IR event class\endlink parameter.
169 - bt_ctf_trace_add_stream_class() freezes the root field types of the
170 whole trace class hierarchy (trace class, children stream classes,
171 and their children event classes).
172 - bt_ctf_writer_create_stream() freezes the root field types of the
173 whole CTF writer's trace class hierarchy.
174 - bt_ctf_event_create() freezes the root field types of its event class
175 parameter and of ther parent stream class of this event class.
177 You cannot modify a frozen field type object: it is considered
178 immutable, except for \link refs reference counting\endlink.
181 @sa \ref ctfirfieldtypesexamples "Examples"
184 @brief CTF IR field types type and functions.
187 @addtogroup ctfirfieldtypes
192 @struct bt_ctf_field_type
193 @brief A CTF IR field type.
196 struct bt_ctf_field_type
;
197 struct bt_ctf_event_class
;
200 struct bt_ctf_field_path
;
202 /** @cond DOCUMENT */
205 * Babeltrace 1.x enumerations that were also used in CTF writer's API.
206 * They are left here for backward compatibility reasons, but
207 * enum bt_ctf_type_id and enum bt_ctf_string_encoding should be used
208 * in new code. Both new enumerations are compatible with their legacy
212 CTF_TYPE_UNKNOWN
= 0,
218 CTF_TYPE_UNTAGGED_VARIANT
,
228 enum ctf_string_encoding
{
241 /// Unknown, used for errors.
242 BT_CTF_SCOPE_UNKNOWN
= -1,
244 /// Trace packet header.
245 BT_CTF_SCOPE_TRACE_PACKET_HEADER
= 1,
247 /// Stream packet context.
248 BT_CTF_SCOPE_STREAM_PACKET_CONTEXT
= 2,
250 /// Stream event header.
251 BT_CTF_SCOPE_STREAM_EVENT_HEADER
= 3,
253 /// Stream event context.
254 BT_CTF_SCOPE_STREAM_EVENT_CONTEXT
= 4,
257 BT_CTF_SCOPE_EVENT_CONTEXT
= 5,
260 BT_CTF_SCOPE_EVENT_PAYLOAD
= 6,
263 BT_CTF_SCOPE_ENV
= 0,
264 BT_CTF_SCOPE_EVENT_FIELDS
= 6,
269 @name Type information
274 @brief Type ID of a @ft.
276 enum bt_ctf_type_id
{
277 /// Unknown, used for errors.
278 BT_CTF_TYPE_ID_UNKNOWN
= CTF_TYPE_UNKNOWN
,
280 /// \ref ctfirintfieldtype
281 BT_CTF_TYPE_ID_INTEGER
= CTF_TYPE_INTEGER
,
283 /// \ref ctfirfloatfieldtype
284 BT_CTF_TYPE_ID_FLOAT
= CTF_TYPE_FLOAT
,
286 /// \ref ctfirenumfieldtype
287 BT_CTF_TYPE_ID_ENUM
= CTF_TYPE_ENUM
,
289 /// \ref ctfirstringfieldtype
290 BT_CTF_TYPE_ID_STRING
= CTF_TYPE_STRING
,
292 /// \ref ctfirstructfieldtype
293 BT_CTF_TYPE_ID_STRUCT
= CTF_TYPE_STRUCT
,
296 BT_CTF_TYPE_ID_UNTAGGED_VARIANT
= CTF_TYPE_UNTAGGED_VARIANT
,
299 /// \ref ctfirarrayfieldtype
300 BT_CTF_TYPE_ID_ARRAY
= CTF_TYPE_ARRAY
,
302 /// \ref ctfirseqfieldtype
303 BT_CTF_TYPE_ID_SEQUENCE
= CTF_TYPE_SEQUENCE
,
305 /// \ref ctfirvarfieldtype
306 BT_CTF_TYPE_ID_VARIANT
= CTF_TYPE_VARIANT
,
308 /// Number of enumeration entries.
309 BT_CTF_NR_TYPE_IDS
= NR_CTF_TYPES
,
313 @brief Returns the type ID of the @ft \p field_type.
315 @param[in] field_type Field type of which to get the type ID.
316 @returns Type ID of \p field_type,
317 or #BT_CTF_TYPE_ID_UNKNOWN on error.
319 @prenotnull{field_type}
320 @postrefcountsame{field_type}
322 @sa #bt_ctf_type_id: CTF IR field type ID.
323 @sa bt_ctf_field_type_is_integer(): Returns whether or not a given
324 field type is a @intft.
325 @sa bt_ctf_field_type_is_floating_point(): Returns whether or not a
326 given field type is a @floatft.
327 @sa bt_ctf_field_type_is_enumeration(): Returns whether or not a given
328 field type is a @enumft.
329 @sa bt_ctf_field_type_is_string(): Returns whether or not a given
330 field type is a @stringft.
331 @sa bt_ctf_field_type_is_structure(): Returns whether or not a given
332 field type is a @structft.
333 @sa bt_ctf_field_type_is_array(): Returns whether or not a given
334 field type is a @arrayft.
335 @sa bt_ctf_field_type_is_sequence(): Returns whether or not a given
336 field type is a @seqft.
337 @sa bt_ctf_field_type_is_variant(): Returns whether or not a given
338 field type is a @varft.
340 extern enum bt_ctf_type_id
bt_ctf_field_type_get_type_id(
341 struct bt_ctf_field_type
*field_type
);
344 @brief Returns whether or not the @ft \p field_type is a @intft.
346 @param[in] field_type Field type to check (can be \c NULL).
347 @returns 1 if \p field_type is an integer field type,
348 or 0 otherwise (including if \p field_type is
351 @prenotnull{field_type}
352 @postrefcountsame{field_type}
354 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
357 extern int bt_ctf_field_type_is_integer(struct bt_ctf_field_type
*field_type
);
360 @brief Returns whether or not the @ft \p field_type is a @floatft.
362 @param[in] field_type Field type to check (can be \c NULL).
363 @returns 1 if \p field_type is a floating point
365 or 0 otherwise (including if \p field_type is
368 @postrefcountsame{field_type}
370 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
373 extern int bt_ctf_field_type_is_floating_point(struct bt_ctf_field_type
*field_type
);
376 @brief Returns whether or not the @ft \p field_type is a @enumft.
378 @param[in] field_type Field type to check (can be \c NULL).
379 @returns 1 if \p field_type is an enumeration field type,
380 or 0 otherwise (including if \p field_type is
383 @postrefcountsame{field_type}
385 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
388 extern int bt_ctf_field_type_is_enumeration(struct bt_ctf_field_type
*field_type
);
391 @brief Returns whether or not the @ft \p field_type is a @stringft.
393 @param[in] field_type Field type to check (can be \c NULL).
394 @returns 1 if \p field_type is a string field type,
395 or 0 otherwise (including if \p field_type is
398 @postrefcountsame{field_type}
400 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
403 extern int bt_ctf_field_type_is_string(struct bt_ctf_field_type
*field_type
);
406 @brief Returns whether or not the @ft \p field_type is a @structft.
408 @param[in] field_type Field type to check (can be \c NULL).
409 @returns 1 if \p field_type is a structure field type,
410 or 0 otherwise (including if \p field_type is
413 @postrefcountsame{field_type}
415 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
418 extern int bt_ctf_field_type_is_structure(struct bt_ctf_field_type
*field_type
);
421 @brief Returns whether or not the @ft \p field_type is a @arrayft.
423 @param[in] field_type Field type to check (can be \c NULL).
424 @returns 1 if \p field_type is an array field type,
425 or 0 otherwise (including if \p field_type is
428 @postrefcountsame{field_type}
430 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
433 extern int bt_ctf_field_type_is_array(struct bt_ctf_field_type
*field_type
);
436 @brief Returns whether or not the @ft \p field_type is a @seqft.
438 @param[in] field_type Field type to check (can be \c NULL).
439 @returns 1 if \p field_type is a sequence field type,
440 or 0 otherwise (including if \p field_type is
443 @postrefcountsame{field_type}
445 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
448 extern int bt_ctf_field_type_is_sequence(struct bt_ctf_field_type
*field_type
);
451 @brief Returns whether or not the @ft \p field_type is a @varft.
453 @param[in] field_type Field type to check (can be \c NULL).
454 @returns 1 if \p field_type is a variant field type,
455 or 0 otherwise (including if \p field_type is
458 @postrefcountsame{field_type}
460 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
463 extern int bt_ctf_field_type_is_variant(struct bt_ctf_field_type
*field_type
);
468 @name Common properties types and functions
473 @brief <a href="https://en.wikipedia.org/wiki/Endianness">Byte order</a>
476 enum bt_ctf_byte_order
{
477 /// Unknown, used for errors.
478 BT_CTF_BYTE_ORDER_UNKNOWN
= -1,
481 * Note that native, in the context of the CTF specification, is defined
482 * as "the byte order described in the trace" and does not mean that the
483 * host's endianness will be used.
485 /// Native (default) byte order.
486 BT_CTF_BYTE_ORDER_NATIVE
= 0,
489 BT_CTF_BYTE_ORDER_LITTLE_ENDIAN
,
492 BT_CTF_BYTE_ORDER_BIG_ENDIAN
,
494 /// Network byte order (big-endian).
495 BT_CTF_BYTE_ORDER_NETWORK
,
499 @brief String encoding of a @ft.
501 enum bt_ctf_string_encoding
{
502 /// Unknown, used for errors.
503 BT_CTF_STRING_ENCODING_UNKNOWN
= CTF_STRING_UNKNOWN
,
506 BT_CTF_STRING_ENCODING_NONE
= CTF_STRING_NONE
,
508 /// <a href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a>.
509 BT_CTF_STRING_ENCODING_UTF8
= CTF_STRING_UTF8
,
511 /// <a href="https://en.wikipedia.org/wiki/ASCII">ASCII</a>.
512 BT_CTF_STRING_ENCODING_ASCII
= CTF_STRING_ASCII
,
516 @brief Returns the alignment of the @fields described by
517 the @ft \p field_type.
519 @param[in] field_type Field type which describes the
520 fields of which to get the alignment.
521 @returns Alignment of the fields described by
522 \p field_type, or a negative value on error.
524 @prenotnull{field_type}
525 @postrefcountsame{field_type}
527 @sa bt_ctf_field_type_set_alignment(): Sets the alignment
528 of the fields described by a given field type.
530 extern int bt_ctf_field_type_get_alignment(
531 struct bt_ctf_field_type
*field_type
);
534 @brief Sets the alignment of the @fields described by the
535 @ft \p field_type to \p alignment.
537 \p alignment \em must be greater than 0 and a power of two.
539 @param[in] field_type Field type which describes the fields of
540 which to set the alignment.
541 @param[in] alignment Alignment of the fields described by
543 @returns 0 on success, or a negative value on error.
545 @prenotnull{field_type}
547 @pre \p alignment is greater than 0 and a power of two.
548 @postrefcountsame{field_type}
550 @sa bt_ctf_field_type_get_alignment(): Returns the alignment of the
551 fields described by a given field type.
553 extern int bt_ctf_field_type_set_alignment(struct bt_ctf_field_type
*field_type
,
554 unsigned int alignment
);
557 @brief Returns the byte order of the @fields described by
558 the @ft \p field_type.
560 You can only call this function if \p field_type is a @intft, a
561 @floatft, or a @enumft.
563 @param[in] field_type Field type which describes the
564 fields of which to get the byte order.
565 @returns Byte order of the fields described by
566 \p field_type, or #BT_CTF_BYTE_ORDER_UNKNOWN on
569 @prenotnull{field_type}
570 @pre \p field_type is a @intft, a @floatft, or a @enumft.
571 @postrefcountsame{field_type}
573 @sa bt_ctf_field_type_set_byte_order(): Sets the byte order
574 of the fields described by a given field type.
576 extern enum bt_ctf_byte_order
bt_ctf_field_type_get_byte_order(
577 struct bt_ctf_field_type
*field_type
);
580 @brief Sets the byte order of the @fields described by the
581 @ft \p field_type to \p byte_order.
583 If \p field_type is a compound field type, this function also
584 recursively sets the byte order of its children to \p byte_order.
586 @param[in] field_type Field type which describes the fields of
587 which to set the byte order.
588 @param[in] byte_order Alignment of the fields described by
590 @returns 0 on success, or a negative value on error.
592 @prenotnull{field_type}
594 @pre \p byte_order is #BT_CTF_BYTE_ORDER_NATIVE,
595 #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN, #BT_CTF_BYTE_ORDER_BIG_ENDIAN,
596 or #BT_CTF_BYTE_ORDER_NETWORK.
597 @postrefcountsame{field_type}
599 @sa bt_ctf_field_type_get_byte_order(): Returns the byte order of the
600 fields described by a given field type.
602 extern int bt_ctf_field_type_set_byte_order(
603 struct bt_ctf_field_type
*field_type
,
604 enum bt_ctf_byte_order byte_order
);
609 @name Utility functions
614 @brief Returns whether or not the @ft \p field_type_a
615 is equivalent to the field type \p field_type_b.
617 You \em must use this function to compare two field types: it is not
618 safe to compare two pointer values directly, because, for internal
619 reasons, some parts of the Babeltrace system can copy user field types
620 and discard the original ones.
622 @param[in] field_type_a Field type to compare to \p field_type_b.
623 @param[in] field_type_b Field type to compare to \p field_type_a.
624 @returns 0 if \p field_type_a is equivalent to
625 \p field_type_b, 1 if they are not equivalent,
626 or a negative value on error.
628 @prenotnull{field_type_a}
629 @prenotnull{field_type_b}
630 @postrefcountsame{field_type_a}
631 @postrefcountsame{field_type_b}
633 extern int bt_ctf_field_type_compare(struct bt_ctf_field_type
*field_type_a
,
634 struct bt_ctf_field_type
*field_type_b
);
637 @brief Creates a \em deep copy of the @ft \p field_type.
639 You can copy a frozen field type: the resulting copy is
642 This function resets the tag field type of a copied @varft. The
643 automatic field resolving which some functions of the API perform
644 can set it again when the returned field type is used (learn more
645 in the detailed description of this module).
647 @param[in] field_type Field type to copy.
648 @returns Deep copy of \p field_type on success,
651 @prenotnull{field_type}
652 @postrefcountsame{field_type}
653 @postsuccessrefcountret1
654 @post <strong>On success</strong>, the returned field type is not frozen.
656 extern struct bt_ctf_field_type
*bt_ctf_field_type_copy(
657 struct bt_ctf_field_type
*field_type
);
664 @defgroup ctfirintfieldtype CTF IR integer field type
665 @ingroup ctfirfieldtypes
666 @brief CTF IR integer field type.
669 #include <babeltrace/ctf-ir/field-types.h>
672 A CTF IR <strong><em>integer field type</em></strong> is a field type that
673 you can use to create concrete @intfield objects.
675 You can create an integer field type
676 with bt_ctf_field_type_integer_create().
678 An integer field type has the following properties:
683 <th>Value at creation
688 <td>\b Alignment (bits) of the described integer fields
690 <td>bt_ctf_field_type_get_alignment()
691 <td>bt_ctf_field_type_set_alignment()
694 <td><strong>Byte order</strong> of the described integer fields
695 <td>#BT_CTF_BYTE_ORDER_NATIVE
696 <td>bt_ctf_field_type_get_byte_order()
697 <td>bt_ctf_field_type_set_byte_order()
700 <td><strong>Storage size</strong> (bits) of the described
702 <td>Specified at creation
703 <td>bt_ctf_field_type_integer_get_size()
704 <td>None: specified at creation (bt_ctf_field_type_integer_create())
707 <td><strong>Signedness</strong> of the described integer fields
709 <td>bt_ctf_field_type_integer_get_signed()
710 <td>bt_ctf_field_type_integer_set_signed()
713 <td><strong>Preferred display base</strong> of the described
715 <td>#BT_CTF_INTEGER_BASE_DECIMAL
716 <td>bt_ctf_field_type_integer_get_base()
717 <td>bt_ctf_field_type_integer_set_base()
720 <td>\b Encoding of the described integer fields
721 <td>#BT_CTF_STRING_ENCODING_NONE
722 <td>bt_ctf_field_type_integer_get_encoding()
723 <td>bt_ctf_field_type_integer_set_encoding()
727 \link ctfirclockclass CTF IR clock class\endlink</strong>
729 <td>bt_ctf_field_type_integer_get_mapped_clock_class()
730 <td>bt_ctf_field_type_integer_set_mapped_clock_class()
736 @sa \ref ctfirfieldtypesexamples_intfieldtype "Examples"
738 @addtogroup ctfirintfieldtype
743 @brief Preferred display base (radix) of a @intft.
745 enum bt_ctf_integer_base
{
746 /// Unknown, used for errors.
747 BT_CTF_INTEGER_BASE_UNKNOWN
= -1,
750 BT_CTF_INTEGER_BASE_BINARY
= 2,
753 BT_CTF_INTEGER_BASE_OCTAL
= 8,
756 BT_CTF_INTEGER_BASE_DECIMAL
= 10,
759 BT_CTF_INTEGER_BASE_HEXADECIMAL
= 16,
763 @brief Creates a default @intft with \p size bits as the storage size
764 of the @intfields it describes.
766 @param[in] size Storage size (bits) of the described integer fields.
767 @returns Created integer field type, or \c NULL on error.
769 @pre \p size is greater than 0 and lesser than or equal to 64.
770 @postsuccessrefcountret1
772 extern struct bt_ctf_field_type
*bt_ctf_field_type_integer_create(
776 @brief Returns the storage size, in bits, of the @intfields
777 described by the @intft \p int_field_type.
779 @param[in] int_field_type Integer field type which describes the
780 integer fields of which to get the
782 @returns Storage size (bits) of the integer
783 fields described by \p int_field_type,
784 or a negative value on error.
786 @prenotnull{int_field_type}
787 @preisintft{int_field_type}
788 @postrefcountsame{int_field_type}
790 extern int bt_ctf_field_type_integer_get_size(
791 struct bt_ctf_field_type
*int_field_type
);
794 @brief Returns whether or not the @intfields described by the @intft
795 \p int_field_type are signed.
797 @param[in] int_field_type Integer field type which describes the
798 integer fields of which to get the
800 @returns 1 if the integer fields described by
801 \p int_field_type are signed, 0 if they
802 are unsigned, or a negative value on
805 @prenotnull{int_field_type}
806 @preisintft{int_field_type}
807 @postrefcountsame{int_field_type}
809 @sa bt_ctf_field_type_integer_set_signed(): Sets the signedness of the
810 integer fields described by a given integer field type.
812 extern int bt_ctf_field_type_integer_get_signed(
813 struct bt_ctf_field_type
*int_field_type
);
816 @brief Sets whether or not the @intfields described by
817 the @intft \p int_field_type are signed.
819 @param[in] int_field_type Integer field type which describes the
820 integer fields of which to set the
822 @param[in] is_signed Signedness of the integer fields
823 described by \p int_field_type; 0 means
824 \em unsigned, 1 means \em signed.
825 @returns 0 on success, or a negative value on error.
827 @prenotnull{int_field_type}
828 @preisintft{int_field_type}
829 @prehot{int_field_type}
830 @pre \p is_signed is 0 or 1.
831 @postrefcountsame{event_class}
833 @sa bt_ctf_field_type_integer_get_signed(): Returns the signedness of
834 the integer fields described by a given integer field type.
836 extern int bt_ctf_field_type_integer_set_signed(
837 struct bt_ctf_field_type
*int_field_type
, int is_signed
);
840 @brief Returns the preferred display base (radix) of the @intfields
841 described by the @intft \p int_field_type.
843 @param[in] int_field_type Integer field type which describes the
844 integer fields of which to get the
845 preferred display base.
846 @returns Preferred display base of the integer
847 fields described by \p int_field_type,
848 or #BT_CTF_INTEGER_BASE_UNKNOWN on
851 @prenotnull{int_field_type}
852 @preisintft{int_field_type}
853 @postrefcountsame{int_field_type}
855 @sa bt_ctf_field_type_integer_set_base(): Sets the preferred display
856 base of the integer fields described by a given integer field
859 extern enum bt_ctf_integer_base
bt_ctf_field_type_integer_get_base(
860 struct bt_ctf_field_type
*int_field_type
);
863 @brief Sets the preferred display base (radix) of the @intfields
864 described by the @intft \p int_field_type to \p base.
866 @param[in] int_field_type Integer field type which describes the
867 integer fields of which to set the
868 preferred display base.
869 @param[in] base Preferred display base of the integer
870 fields described by \p int_field_type.
871 @returns 0 on success, or a negative value on error.
873 @prenotnull{int_field_type}
874 @preisintft{int_field_type}
875 @prehot{int_field_type}
876 @pre \p base is #BT_CTF_INTEGER_BASE_BINARY, #BT_CTF_INTEGER_BASE_OCTAL,
877 #BT_CTF_INTEGER_BASE_DECIMAL, or
878 #BT_CTF_INTEGER_BASE_HEXADECIMAL.
879 @postrefcountsame{int_field_type}
881 @sa bt_ctf_field_type_integer_get_base(): Returns the preferred display
882 base of the integer fields described by a given
885 extern int bt_ctf_field_type_integer_set_base(
886 struct bt_ctf_field_type
*int_field_type
,
887 enum bt_ctf_integer_base base
);
890 @brief Returns the encoding of the @intfields described by
891 the @intft \p int_field_type.
893 @param[in] int_field_type Integer field type which describes the
894 integer fields of which to get the
896 @returns Encoding of the integer
897 fields described by \p int_field_type,
898 or #BT_CTF_STRING_ENCODING_UNKNOWN on
901 @prenotnull{int_field_type}
902 @preisintft{int_field_type}
903 @postrefcountsame{int_field_type}
905 @sa bt_ctf_field_type_integer_set_encoding(): Sets the encoding
906 of the integer fields described by a given integer field type.
908 extern enum bt_ctf_string_encoding
bt_ctf_field_type_integer_get_encoding(
909 struct bt_ctf_field_type
*int_field_type
);
912 @brief Sets the encoding of the @intfields described by the @intft
913 \p int_field_type to \p encoding.
915 You can use this property, in CTF IR, to create "text" @arrayfts or
916 @seqfts. A text array field type is array field type with an unsigned,
917 8-bit integer field type having an encoding as its element field type.
919 @param[in] int_field_type Integer field type which describes the
920 integer fields of which to set the
922 @param[in] encoding Encoding of the integer
923 fields described by \p int_field_type.
924 @returns 0 on success, or a negative value on error.
926 @prenotnull{int_field_type}
927 @preisintft{int_field_type}
928 @prehot{int_field_type}
929 @pre \p encoding is #BT_CTF_STRING_ENCODING_NONE,
930 #BT_CTF_STRING_ENCODING_ASCII, or
931 #BT_CTF_STRING_ENCODING_UTF8.
932 @postrefcountsame{int_field_type}
934 @sa bt_ctf_field_type_integer_get_encoding(): Returns the encoding of
935 the integer fields described by a given integer field type.
937 extern int bt_ctf_field_type_integer_set_encoding(
938 struct bt_ctf_field_type
*int_field_type
,
939 enum bt_ctf_string_encoding encoding
);
942 @brief Returns the \link ctfirclockclass CTF IR clock class\endlink
943 mapped to the @intft \p int_field_type.
945 The mapped clock class, if any, indicates the class of the clock which
946 an @intfield described by \p int_field_type should sample or update.
947 This mapped clock class is only indicative.
949 @param[in] int_field_type Integer field type of which to get the
951 @returns Mapped clock class of \p int_field_type,
952 or \c NULL if there's no mapped clock
955 @prenotnull{int_field_type}
956 @preisintft{int_field_type}
957 @postrefcountsame{int_field_type}
958 @postsuccessrefcountretinc
960 @sa bt_ctf_field_type_integer_set_mapped_clock_class(): Sets the mapped
961 clock class of a given integer field type.
963 extern struct bt_ctf_clock_class
*bt_ctf_field_type_integer_get_mapped_clock_class(
964 struct bt_ctf_field_type
*int_field_type
);
967 @brief Sets the \link ctfirclockclass CTF IR clock class\endlink mapped
968 to the @intft \p int_field_type to \p clock_class.
970 The mapped clock class, if any, indicates the class of the clock which
971 an integer field described by \p int_field_type should sample or update.
972 This mapped clock class is only indicative.
974 @param[in] int_field_type Integer field type of which to set the
976 @param[in] clock_class Mapped clock class of \p int_field_type.
977 @returns 0 on success, or a negative value on error.
979 @prenotnull{int_field_type}
980 @prenotnull{clock_class}
981 @preisintft{int_field_type}
982 @prehot{int_field_type}
983 @postrefcountsame{int_field_type}
984 @postsuccessrefcountinc{clock_class}
986 @sa bt_ctf_field_type_integer_get_mapped_clock_class(): Returns the mapped
987 clock class of a given integer field type.
989 extern int bt_ctf_field_type_integer_set_mapped_clock_class(
990 struct bt_ctf_field_type
*int_field_type
,
991 struct bt_ctf_clock_class
*clock_class
);
996 @defgroup ctfirfloatfieldtype CTF IR floating point number field type
997 @ingroup ctfirfieldtypes
998 @brief CTF IR floating point number field type.
1001 #include <babeltrace/ctf-ir/field-types.h>
1004 A CTF IR <strong><em>floating point number field type</em></strong> is
1005 a field type that you can use to create concrete @floatfields.
1007 You can create a floating point number field type
1008 with bt_ctf_field_type_floating_point_create().
1010 A floating point number field type has the following properties:
1015 <th>Value at creation
1020 <td>\b Alignment (bits) of the described floating point
1023 <td>bt_ctf_field_type_get_alignment()
1024 <td>bt_ctf_field_type_set_alignment()
1027 <td><strong>Byte order</strong> of the described floating point
1029 <td>#BT_CTF_BYTE_ORDER_NATIVE
1030 <td>bt_ctf_field_type_get_byte_order()
1031 <td>bt_ctf_field_type_set_byte_order()
1034 <td><strong>Exponent storage size</strong> (bits) of the described
1035 floating point number fields
1037 <td>bt_ctf_field_type_floating_point_get_exponent_digits()
1038 <td>bt_ctf_field_type_floating_point_set_exponent_digits()
1041 <td><strong>Mantissa and sign storage size</strong> (bits) of the
1042 described floating point number fields
1043 <td>24 (23-bit mantissa, 1-bit sign)
1044 <td>bt_ctf_field_type_floating_point_get_mantissa_digits()
1045 <td>bt_ctf_field_type_floating_point_set_mantissa_digits()
1051 @sa \ref ctfirfieldtypesexamples_floatfieldtype "Examples"
1053 @addtogroup ctfirfloatfieldtype
1058 @brief Creates a default @floatft.
1060 @returns Created floating point number field type,
1061 or \c NULL on error.
1063 @postsuccessrefcountret1
1065 extern struct bt_ctf_field_type
*bt_ctf_field_type_floating_point_create(void);
1068 @brief Returns the exponent storage size of the @floatfields
1069 described by the @floatft \p float_field_type.
1071 @param[in] float_field_type Floating point number field type which
1072 describes the floating point number
1073 fields of which to get the exponent
1075 @returns Exponent storage size of the
1076 floating point number fields
1077 described by \p float_field_type,
1078 or a negative value on error.
1080 @prenotnull{float_field_type}
1081 @preisfloatft{float_field_type}
1082 @postrefcountsame{float_field_type}
1084 @sa bt_ctf_field_type_floating_point_set_exponent_digits(): Sets the
1085 exponent storage size of the floating point number fields
1086 described by a given floating point number field type.
1088 extern int bt_ctf_field_type_floating_point_get_exponent_digits(
1089 struct bt_ctf_field_type
*float_field_type
);
1092 @brief Sets the exponent storage size of the @floatfields described by
1093 the @floatft \p float_field_type to \p exponent_size.
1095 As of Babeltrace \btversion, \p exponent_size can only be 8 or 11.
1097 @param[in] float_field_type Floating point number field type which
1098 describes the floating point number
1099 fields of which to set the exponent
1101 @param[in] exponent_size Exponent storage size of the floating
1102 point number fields described by \p
1104 @returns 0 on success, or a negative value on error.
1106 @prenotnull{float_field_type}
1107 @preisfloatft{float_field_type}
1108 @prehot{float_field_type}
1109 @pre \p exponent_size is 8 or 11.
1110 @postrefcountsame{float_field_type}
1112 @sa bt_ctf_field_type_floating_point_get_exponent_digits(): Returns the
1113 exponent storage size of the floating point number fields
1114 described by a given floating point number field type.
1116 extern int bt_ctf_field_type_floating_point_set_exponent_digits(
1117 struct bt_ctf_field_type
*float_field_type
,
1118 unsigned int exponent_size
);
1121 @brief Returns the mantissa and sign storage size of the @floatfields
1122 described by the @floatft \p float_field_type.
1124 On success, the returned value is the sum of the mantissa \em and
1127 @param[in] float_field_type Floating point number field type which
1128 describes the floating point number
1129 fields of which to get the mantissa and
1131 @returns Mantissa and sign storage size of the
1132 floating point number fields
1133 described by \p float_field_type,
1134 or a negative value on error.
1136 @prenotnull{float_field_type}
1137 @preisfloatft{float_field_type}
1138 @postrefcountsame{float_field_type}
1140 @sa bt_ctf_field_type_floating_point_set_mantissa_digits(): Sets the
1141 mantissa and size storage size of the floating point number
1142 fields described by a given floating point number field type.
1144 extern int bt_ctf_field_type_floating_point_get_mantissa_digits(
1145 struct bt_ctf_field_type
*float_field_type
);
1148 @brief Sets the mantissa and sign storage size of the @floatfields
1149 described by the @floatft \p float_field_type to \p
1152 As of Babeltrace \btversion, \p mantissa_sign_size can only be 24 or 53.
1154 @param[in] float_field_type Floating point number field type which
1155 describes the floating point number
1156 fields of which to set the mantissa and
1158 @param[in] mantissa_sign_size Mantissa and sign storage size of the
1159 floating point number fields described
1160 by \p float_field_type.
1161 @returns 0 on success, or a negative value on error.
1163 @prenotnull{float_field_type}
1164 @preisfloatft{float_field_type}
1165 @prehot{float_field_type}
1166 @pre \p mantissa_sign_size is 24 or 53.
1167 @postrefcountsame{float_field_type}
1169 @sa bt_ctf_field_type_floating_point_get_mantissa_digits(): Returns the
1170 mantissa and sign storage size of the floating point number
1171 fields described by a given floating point number field type.
1173 extern int bt_ctf_field_type_floating_point_set_mantissa_digits(
1174 struct bt_ctf_field_type
*float_field_type
,
1175 unsigned int mantissa_sign_size
);
1180 @defgroup ctfirenumfieldtype CTF IR enumeration field type
1181 @ingroup ctfirfieldtypes
1182 @brief CTF IR enumeration field type.
1185 #include <babeltrace/ctf-ir/field-types.h>
1188 A CTF IR <strong><em>enumeration field type</em></strong> is
1189 a field type that you can use to create concrete @enumfields.
1191 You can create an enumeration field type with
1192 bt_ctf_field_type_enumeration_create(). This function needs a @intft
1193 which represents the storage field type of the created enumeration field
1194 type. In other words, an enumeration field type wraps an integer field
1195 type and adds label-value mappings to it.
1197 An enumeration mapping has:
1199 - A <strong>name</strong>.
1200 - A <strong>range of values</strong> given by a beginning and an ending
1201 value, both included in the range.
1203 You can add a mapping to an enumeration field type with
1204 bt_ctf_field_type_enumeration_add_mapping() or
1205 bt_ctf_field_type_enumeration_add_mapping_unsigned(), depending on the
1206 signedness of the wrapped @intft.
1208 Many mappings can share the same name, but the ranges of a given
1209 enumeration field type <strong>must not overlap</strong>. For example,
1210 this is a valid set of mappings:
1219 The following set of mappings is \em not valid, however:
1228 Here, the range of the second \c APPLE mapping overlaps the range of
1229 the \c CHERRY mapping.
1234 @addtogroup ctfirenumfieldtype
1239 @brief Creates a default @enumft wrapping the @intft \p int_field_type.
1241 @param[in] int_field_type Integer field type wrapped by the
1242 created enumeration field type.
1243 @returns Created enumeration field type,
1244 or \c NULL on error.
1246 @prenotnull{int_field_type}
1247 @preisintft{int_field_type}
1248 @postsuccessrefcountinc{int_field_type}
1249 @postsuccessrefcountret1
1251 extern struct bt_ctf_field_type
*bt_ctf_field_type_enumeration_create(
1252 struct bt_ctf_field_type
*int_field_type
);
1255 @brief Returns the @intft wrapped by the @enumft \p enum_field_type.
1257 @param[in] enum_field_type Enumeration field type of which to get
1258 the wrapped integer field type.
1259 @returns Integer field type wrapped by
1260 \p enum_field_type, or \c NULL on
1263 @prenotnull{enum_field_type}
1264 @preisenumft{enum_field_type}
1265 @postrefcountsame{enum_field_type}
1266 @postsuccessrefcountretinc
1269 struct bt_ctf_field_type
*bt_ctf_field_type_enumeration_get_container_type(
1270 struct bt_ctf_field_type
*enum_field_type
);
1273 @brief Returns the number of mappings contained in the
1274 @enumft \p enum_field_type.
1276 @param[in] enum_field_type Enumeration field type of which to get
1277 the number of contained mappings.
1278 @returns Number of mappings contained in
1279 \p enum_field_type, or a negative
1282 @prenotnull{enum_field_type}
1283 @preisenumft{enum_field_type}
1284 @postrefcountsame{enum_field_type}
1286 extern int bt_ctf_field_type_enumeration_get_mapping_count(
1287 struct bt_ctf_field_type
*enum_field_type
);
1290 @brief Returns the signed mapping of the @enumft
1291 \p enum_field_type at index \p index.
1293 The @intft wrapped by \p enum_field_type, as returned by
1294 bt_ctf_field_type_enumeration_get_container_type(), must be \b signed
1295 to use this function.
1297 On success, \p enum_field_type remains the sole owner of \p *name.
1299 @param[in] enum_field_type Enumeration field type of which to get
1300 the mapping at index \p index.
1301 @param[in] index Index of the mapping to get from
1303 @param[out] name Returned name of the mapping at index
1305 @param[out] range_begin Returned beginning of the range
1306 (included) of the mapping at index \p
1308 @param[out] range_end Returned end of the range (included) of
1309 the mapping at index \p index.
1310 @returns 0 on success, or a negative value on error.
1312 @prenotnull{enum_field_type}
1314 @prenotnull{range_begin}
1315 @prenotnull{range_end}
1316 @preisenumft{enum_field_type}
1317 @pre The wrapped @intft of \p enum_field_type is signed.
1318 @pre \p index is lesser than the number of mappings contained in the
1319 enumeration field type \p enum_field_type (see
1320 bt_ctf_field_type_enumeration_get_mapping_count()).
1321 @postrefcountsame{enum_field_type}
1323 @sa bt_ctf_field_type_enumeration_get_mapping_unsigned(): Returns the
1324 unsigned mapping contained by a given enumeration field type
1327 extern int bt_ctf_field_type_enumeration_get_mapping(
1328 struct bt_ctf_field_type
*enum_field_type
, int index
,
1329 const char **name
, int64_t *range_begin
, int64_t *range_end
);
1332 @brief Returns the unsigned mapping of the @enumft
1333 \p enum_field_type at index \p index.
1335 The @intft wrapped by \p enum_field_type, as returned by
1336 bt_ctf_field_type_enumeration_get_container_type(), must be
1337 \b unsigned to use this function.
1339 On success, \p enum_field_type remains the sole owner of \p *name.
1341 @param[in] enum_field_type Enumeration field type of which to get
1342 the mapping at index \p index.
1343 @param[in] index Index of the mapping to get from
1345 @param[out] name Returned name of the mapping at index
1347 @param[out] range_begin Returned beginning of the range
1348 (included) of the mapping at index \p
1350 @param[out] range_end Returned end of the range (included) of
1351 the mapping at index \p index.
1352 @returns 0 on success, or a negative value on error.
1354 @prenotnull{enum_field_type}
1356 @prenotnull{range_begin}
1357 @prenotnull{range_end}
1358 @preisenumft{enum_field_type}
1359 @pre The wrapped @intft of \p enum_field_type is unsigned.
1360 @pre \p index is lesser than the number of mappings contained in the
1361 enumeration field type \p enum_field_type (see
1362 bt_ctf_field_type_enumeration_get_mapping_count()).
1363 @postrefcountsame{enum_field_type}
1365 @sa bt_ctf_field_type_enumeration_get_mapping(): Returns the
1366 signed mapping contained by a given enumeration field type
1369 extern int bt_ctf_field_type_enumeration_get_mapping_unsigned(
1370 struct bt_ctf_field_type
*enum_field_type
, int index
,
1371 const char **name
, uint64_t *range_begin
,
1372 uint64_t *range_end
);
1374 /** @cond DOCUMENT */
1376 * TODO: Document once we know what to do with this function (return
1377 * the first match?).
1379 extern int bt_ctf_field_type_enumeration_get_mapping_index_by_name(
1380 struct bt_ctf_field_type
*enum_field_type
, const char *name
);
1384 @brief Returns the index of the signed mapping of the @enumft
1385 \p field_type which contains the value \p value.
1387 The @intft wrapped by \p enum_field_type, as returned by
1388 bt_ctf_field_type_enumeration_get_container_type(), must be
1389 \b signed to use this function.
1391 @param[in] enum_field_type Enumeration field type of which to get
1392 the index of the mapping which contains
1394 @param[in] value Value of the mapping to find.
1395 @returns Index of the mapping of
1396 \p enum_field_type which contains
1397 \p value, or a negative value if the
1398 function cannot find such a mapping or
1401 @prenotnull{enum_field_type}
1402 @preisenumft{enum_field_type}
1403 @pre The wrapped @intft of \p enum_field_type is signed.
1404 @postrefcountsame{enum_field_type}
1406 @sa bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value():
1407 Finds the index of an unsigned mapping of a given enumeration
1408 field type by value.
1410 extern int bt_ctf_field_type_enumeration_get_mapping_index_by_value(
1411 struct bt_ctf_field_type
*enum_field_type
, int64_t value
);
1414 @brief Returns the index of the unsigned mapping of the @enumft
1415 \p field_type which contains the value \p value.
1417 The @intft wrapped by \p enum_field_type, as returned by
1418 bt_ctf_field_type_enumeration_get_container_type(), must be
1419 \b unsigned to use this function.
1421 @param[in] enum_field_type Enumeration field type of which to get
1422 the index of the mapping which contains
1424 @param[in] value Value of the mapping to find.
1425 @returns Index of the mapping of
1426 \p enum_field_type which contains
1427 \p value, or a negative value if the
1428 function cannot find such a mapping or
1431 @prenotnull{enum_field_type}
1432 @preisenumft{enum_field_type}
1433 @pre The wrapped @intft of \p enum_field_type is unsigned.
1434 @postrefcountsame{enum_field_type}
1436 @sa bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value():
1437 Finds the index of a signed mapping of a given enumeration
1438 field type by value.
1440 extern int bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value(
1441 struct bt_ctf_field_type
*enum_field_type
, uint64_t value
);
1444 @brief Adds a mapping to the @enumft \p enum_field_type which maps the
1445 name \p name to the signed range \p range_begin (included) to
1446 \p range_end (included).
1448 Make \p range_begin and \p range_end the same value to add a mapping
1451 The @intft wrapped by \p enum_field_type, as returned by
1452 bt_ctf_field_type_enumeration_get_container_type(), must be
1453 \b signed to use this function.
1455 A mapping in \p enum_field_type can exist with the name \p name, but
1456 there must be no overlap amongst all the ranges of
1459 @param[in] enum_field_type Enumeration field type to which to add
1461 @param[in] name Name of the mapping to add (copied
1463 @param[in] range_begin Beginning of the range of the mapping
1465 @param[in] range_end End of the range of the mapping
1467 @returns 0 on success, or a negative value on error.
1469 @prenotnull{enum_field_type}
1471 @preisenumft{enum_field_type}
1472 @pre The wrapped @intft of \p enum_field_type is signed.
1473 @pre \p range_end is greater than or equal to \p range_begin.
1474 @postrefcountsame{enum_field_type}
1476 @sa bt_ctf_field_type_enumeration_add_mapping_unsigned(): Adds an
1477 unsigned mapping to a given enumeration field type.
1479 extern int bt_ctf_field_type_enumeration_add_mapping(
1480 struct bt_ctf_field_type
*enum_field_type
, const char *name
,
1481 int64_t range_begin
, int64_t range_end
);
1484 @brief Adds a mapping to the @enumft \p enum_field_type which maps
1485 the name \p name to the unsigned
1486 range \p range_begin (included) to \p range_end (included).
1488 Make \p range_begin and \p range_end the same value to add a mapping
1491 The @intft wrapped by \p enum_field_type, as returned by
1492 bt_ctf_field_type_enumeration_get_container_type(), must be
1493 \b unsigned to use this function.
1495 A mapping in \p enum_field_type can exist with the name \p name, but
1496 there must be no overlap amongst all the ranges of
1499 @param[in] enum_field_type Enumeration field type to which to add
1501 @param[in] name Name of the mapping to add (copied
1503 @param[in] range_begin Beginning of the range of the mapping
1505 @param[in] range_end End of the range of the mapping
1507 @returns 0 on success, or a negative value on error.
1509 @prenotnull{enum_field_type}
1511 @preisenumft{enum_field_type}
1512 @pre The wrapped @intft of \p enum_field_type is unsigned.
1513 @pre \p range_end is greater than or equal to \p range_begin.
1514 @postrefcountsame{enum_field_type}
1516 @sa bt_ctf_field_type_enumeration_add_mapping(): Adds a signed
1517 mapping to a given enumeration field type.
1519 extern int bt_ctf_field_type_enumeration_add_mapping_unsigned(
1520 struct bt_ctf_field_type
*enum_field_type
, const char *name
,
1521 uint64_t range_begin
, uint64_t range_end
);
1526 @defgroup ctfirstringfieldtype CTF IR string field type
1527 @ingroup ctfirfieldtypes
1528 @brief CTF IR string field type.
1531 #include <babeltrace/ctf-ir/field-types.h>
1534 A CTF IR <strong><em>string field type</em></strong> is a field type that
1535 you can use to create concrete @stringfields.
1537 You can create a string field type
1538 with bt_ctf_field_type_string_create().
1540 A string field type has only one property: the \b encoding of its
1541 described @stringfields. By default, the encoding of the string fields
1542 described by a string field type is #BT_CTF_STRING_ENCODING_UTF8. You
1543 can set the encoding of the string fields described by a string field
1544 type with bt_ctf_field_type_string_set_encoding().
1546 @sa ctfirstringfield
1549 @addtogroup ctfirstringfieldtype
1554 @brief Creates a default @stringft.
1556 @returns Created string field type, or \c NULL on error.
1558 @postsuccessrefcountret1
1560 extern struct bt_ctf_field_type
*bt_ctf_field_type_string_create(void);
1563 @brief Returns the encoding of the @stringfields described by
1564 the @stringft \p string_field_type.
1566 @param[in] string_field_type String field type which describes the
1567 string fields of which to get the
1569 @returns Encoding of the string
1570 fields described by \p string_field_type,
1571 or #BT_CTF_STRING_ENCODING_UNKNOWN on
1574 @prenotnull{string_field_type}
1575 @preisstringft{string_field_type}
1576 @postrefcountsame{string_field_type}
1578 @sa bt_ctf_field_type_string_set_encoding(): Sets the encoding
1579 of the string fields described by a given string field type.
1581 extern enum bt_ctf_string_encoding
bt_ctf_field_type_string_get_encoding(
1582 struct bt_ctf_field_type
*string_field_type
);
1585 @brief Sets the encoding of the @stringfields described by the
1586 @stringft \p string_field_type to \p encoding.
1588 @param[in] string_field_type String field type which describes the
1589 string fields of which to set the
1591 @param[in] encoding Encoding of the string fields described
1592 by \p string_field_type.
1593 @returns 0 on success, or a negative value on error.
1595 @prenotnull{string_field_type}
1596 @preisstringft{string_field_type}
1597 @prehot{string_field_type}
1598 @pre \p encoding is #BT_CTF_STRING_ENCODING_ASCII or
1599 #BT_CTF_STRING_ENCODING_UTF8.
1600 @postrefcountsame{string_field_type}
1602 @sa bt_ctf_field_type_string_get_encoding(): Returns the encoding of
1603 the string fields described by a given string field type.
1605 extern int bt_ctf_field_type_string_set_encoding(
1606 struct bt_ctf_field_type
*string_field_type
,
1607 enum bt_ctf_string_encoding encoding
);
1612 @defgroup ctfirstructfieldtype CTF IR structure field type
1613 @ingroup ctfirfieldtypes
1614 @brief CTF IR structure field type.
1617 #include <babeltrace/ctf-ir/field-types.h>
1620 A CTF IR <strong><em>structure field type</em></strong> is
1621 a field type that you can use to create concrete @structfields.
1623 You can create a structure field type
1624 with bt_ctf_field_type_structure_create(). This function creates
1625 an empty structure field type, with no fields.
1627 You can add a field to a structure field type with
1628 bt_ctf_field_type_structure_add_field(). Two fields in a structure
1629 field type cannot have the same name.
1631 You can set the \em minimum alignment of the structure fields described
1632 by a structure field type with the common
1633 bt_ctf_field_type_set_alignment() function. The \em effective alignment
1634 of the structure fields described by a structure field type, as per
1635 <a href="http://diamon.org/ctf/">CTF</a>, is the \em maximum value amongst
1636 the effective alignments of all its fields. Note that the effective
1637 alignment of @varfields is always 1.
1639 You can set the byte order of <em>all the contained fields</em>,
1640 recursively, of a structure field type with the common
1641 bt_ctf_field_type_set_byte_order() function.
1643 @sa ctfirstructfield
1646 @addtogroup ctfirstructfieldtype
1651 @brief Creates a default, empty @structft.
1653 @returns Created structure field type,
1654 or \c NULL on error.
1656 @postsuccessrefcountret1
1658 extern struct bt_ctf_field_type
*bt_ctf_field_type_structure_create(void);
1661 @brief Returns the number of fields contained in the
1662 @structft \p struct_field_type.
1664 @param[in] struct_field_type Structure field type of which to get
1665 the number of contained fields.
1666 @returns Number of fields contained in
1667 \p struct_field_type, or a negative
1670 @prenotnull{struct_field_type}
1671 @preisstructft{struct_field_type}
1672 @postrefcountsame{struct_field_type}
1674 extern int bt_ctf_field_type_structure_get_field_count(
1675 struct bt_ctf_field_type
*struct_field_type
);
1678 @brief Returns the field of the @structft \p struct_field_type
1681 On success, the field's type is placed in \p *field_type if
1682 \p field_type is not \c NULL. The field's name is placed in
1683 \p *field_name if \p field_name is not \c NULL.
1684 \p struct_field_type remains the sole owner of \p *field_name.
1686 @param[in] struct_field_type Structure field type of which to get
1687 the field at index \p index.
1688 @param[out] field_name Returned name of the field at index
1689 \p index (can be \c NULL).
1690 @param[out] field_type Returned field type of the field
1691 at index \p index (can be \c NULL).
1692 @param[in] index Index of the field to get from
1693 \p struct_field_type.
1694 @returns 0 on success, or a negative value on error.
1696 @prenotnull{struct_field_type}
1697 @preisstructft{struct_field_type}
1698 @pre \p index is lesser than the number of fields contained in the
1699 structure field type \p struct_field_type (see
1700 bt_ctf_field_type_structure_get_field_count()).
1701 @postrefcountsame{struct_field_type}
1702 @post <strong>On success</strong>, the returned field's type is placed
1703 in \p *field_type and its reference count is incremented.
1705 @sa bt_ctf_field_type_structure_get_field_type_by_name(): Finds a
1706 structure field type's field by name.
1708 extern int bt_ctf_field_type_structure_get_field(
1709 struct bt_ctf_field_type
*struct_field_type
,
1710 const char **field_name
, struct bt_ctf_field_type
**field_type
,
1714 @brief Returns the type of the field named \p field_name found in
1715 the @structft \p struct_field_type.
1717 @param[in] struct_field_type Structure field type of which to get
1719 @param[in] field_name Name of the field to find.
1720 @returns Type of the field named \p field_name in
1721 \p struct_field_type, or
1724 @prenotnull{struct_field_type}
1725 @prenotnull{field_name}
1726 @preisstructft{struct_field_type}
1727 @postrefcountsame{struct_field_type}
1728 @postsuccessrefcountretinc
1730 @sa bt_ctf_field_type_structure_get_field(): Finds a
1731 structure field type's field by index.
1734 struct bt_ctf_field_type
*bt_ctf_field_type_structure_get_field_type_by_name(
1735 struct bt_ctf_field_type
*struct_field_type
,
1736 const char *field_name
);
1739 @brief Adds a field named \p field_name with the @ft
1740 \p field_type to the @structft \p struct_field_type.
1742 On success, \p field_type becomes the child of \p struct_field_type.
1744 This function adds the new field after the current last field of
1745 \p struct_field_type (append mode).
1747 You \em cannot add a field named \p field_name if there's already a
1748 field named \p field_name in \p struct_field_type.
1750 @param[in] struct_field_type Structure field type to which to add
1752 @param[in] field_type Field type of the field to add to
1753 \p struct_field_type.
1754 @param[in] field_name Name of the field to add to
1755 \p struct_field_type
1756 (copied on success).
1757 @returns 0 on success, or a negative value on error.
1759 @prenotnull{struct_field_type}
1760 @prenotnull{field_type}
1761 @prenotnull{field_name}
1762 @preisstructft{struct_field_type}
1763 @pre \p field_type is not and does not contain \p struct_field_type,
1764 recursively, as a field's type.
1765 @prehot{struct_field_type}
1766 @postrefcountsame{struct_field_type}
1767 @postsuccessrefcountinc{field_type}
1769 extern int bt_ctf_field_type_structure_add_field(
1770 struct bt_ctf_field_type
*struct_field_type
,
1771 struct bt_ctf_field_type
*field_type
,
1772 const char *field_name
);
1777 @defgroup ctfirarrayfieldtype CTF IR array field type
1778 @ingroup ctfirfieldtypes
1779 @brief CTF IR array field type.
1782 #include <babeltrace/ctf-ir/field-types.h>
1785 A CTF IR <strong><em>array field type</em></strong> is a field type that
1786 you can use to create concrete @arrayfields.
1788 You can create an array field type
1789 with bt_ctf_field_type_array_create(). This function needs
1790 the @ft of the fields contained by the array fields described by the
1791 array field type to create.
1796 @addtogroup ctfirarrayfieldtype
1801 @brief Creates a default @arrayft with
1802 \p element_field_type as the field type of the fields contained
1803 in its described @arrayfields of length \p length.
1805 @param[in] element_field_type Field type of the fields contained in
1806 the array fields described by the
1807 created array field type.
1808 @param[in] length Length of the array fields described by
1809 the created array field type.
1810 @returns Created array field type, or
1813 @prenotnull{element_field_type}
1814 @postsuccessrefcountinc{element_field_type}
1815 @postsuccessrefcountret1
1817 extern struct bt_ctf_field_type
*bt_ctf_field_type_array_create(
1818 struct bt_ctf_field_type
*element_field_type
,
1819 unsigned int length
);
1822 @brief Returns the @ft of the @fields contained in
1823 the @arrayfields described by the @arrayft \p array_field_type.
1825 @param[in] array_field_type Array field type of which to get
1826 the type of the fields contained in its
1827 described array fields.
1828 @returns Type of the fields contained in the
1829 array fields described by
1830 \p array_field_type, or \c NULL
1833 @prenotnull{array_field_type}
1834 @preisarrayft{array_field_type}
1835 @postrefcountsame{array_field_type}
1836 @postsuccessrefcountretinc
1838 extern struct bt_ctf_field_type
*bt_ctf_field_type_array_get_element_type(
1839 struct bt_ctf_field_type
*array_field_type
);
1842 @brief Returns the number of @fields contained in the
1843 @arrayfields described by the @arrayft \p array_field_type.
1845 @param[in] array_field_type Array field type of which to get
1846 the number of fields contained in its
1847 described array fields.
1848 @returns Number of fields contained in the
1849 array fields described by
1850 \p array_field_type, or a negative value
1853 @prenotnull{array_field_type}
1854 @preisarrayft{array_field_type}
1855 @postrefcountsame{array_field_type}
1857 extern int64_t bt_ctf_field_type_array_get_length(
1858 struct bt_ctf_field_type
*array_field_type
);
1863 @defgroup ctfirseqfieldtype CTF IR sequence field type
1864 @ingroup ctfirfieldtypes
1865 @brief CTF IR sequence field type.
1868 #include <babeltrace/ctf-ir/field-types.h>
1871 A CTF IR <strong><em>sequence field type</em></strong> is
1872 a field type that you can use to create concrete @seqfields.
1874 You can create a sequence field type with
1875 bt_ctf_field_type_sequence_create(). This function needs the @ft
1876 of the fields contained by the sequence fields described by the created
1877 sequence field type. This function also needs the length name of the
1878 sequence field type to create. The length name is used to automatically
1879 resolve the length's field type. See \ref ctfirfieldtypes to learn more
1880 about the automatic resolving.
1885 @addtogroup ctfirseqfieldtype
1890 @brief Creates a default @seqft with \p element_field_type as the
1891 @ft of the @fields contained in its described @seqfields
1892 with the length name \p length_name.
1894 \p length_name can be an absolute or relative reference. See
1895 <a href="http://diamon.org/ctf/">CTF</a> for more details.
1897 @param[in] element_field_type Field type of the fields contained in
1898 the sequence fields described by the
1899 created sequence field type.
1900 @param[in] length_name Length name (copied on success).
1901 @returns Created array field type, or
1904 @prenotnull{element_field_type}
1905 @prenotnull{length_name}
1906 @postsuccessrefcountinc{element_field_type}
1907 @postsuccessrefcountret1
1909 extern struct bt_ctf_field_type
*bt_ctf_field_type_sequence_create(
1910 struct bt_ctf_field_type
*element_field_type
,
1911 const char *length_name
);
1914 @brief Returns the @ft of the @fields contained in the @seqft
1915 described by the @seqft \p sequence_field_type.
1917 @param[in] sequence_field_type Sequence field type of which to get
1918 the type of the fields contained in its
1919 described sequence fields.
1920 @returns Type of the fields contained in the
1921 sequence fields described by
1922 \p sequence_field_type, or \c NULL
1925 @prenotnull{sequence_field_type}
1926 @preisseqft{sequence_field_type}
1927 @postrefcountsame{sequence_field_type}
1928 @postsuccessrefcountretinc
1930 extern struct bt_ctf_field_type
*bt_ctf_field_type_sequence_get_element_type(
1931 struct bt_ctf_field_type
*sequence_field_type
);
1934 @brief Returns the length name of the @seqft \p sequence_field_type.
1936 On success, \p sequence_field_type remains the sole owner of
1937 the returned string.
1939 @param[in] sequence_field_type Sequence field type of which to get the
1941 @returns Length name of \p sequence_field_type,
1942 or \c NULL on error.
1944 @prenotnull{sequence_field_type}
1945 @preisseqft{sequence_field_type}
1947 @sa bt_ctf_field_type_sequence_get_length_field_path(): Returns the
1948 length's CTF IR field path of a given sequence field type.
1950 extern const char *bt_ctf_field_type_sequence_get_length_field_name(
1951 struct bt_ctf_field_type
*sequence_field_type
);
1954 @brief Returns the length's CTF IR field path of the @seqft
1955 \p sequence_field_type.
1957 The length's field path of a sequence field type is set when automatic
1958 resolving is performed (see \ref ctfirfieldtypes).
1960 @param[in] sequence_field_type Sequence field type of which to get the
1961 length's field path.
1962 @returns Length's field path of
1963 \p sequence_field_type, or
1964 \c NULL if the length's field path is
1965 not set yet is not set or on error.
1967 @prenotnull{sequence_field_type}
1968 @preisseqft{sequence_field_type}
1969 @postsuccessrefcountretinc
1971 @sa bt_ctf_field_type_sequence_get_length_field_name(): Returns the
1972 length's name of a given sequence field type.
1974 extern struct bt_ctf_field_path
*bt_ctf_field_type_sequence_get_length_field_path(
1975 struct bt_ctf_field_type
*sequence_field_type
);
1980 @defgroup ctfirvarfieldtype CTF IR variant field type
1981 @ingroup ctfirfieldtypes
1982 @brief CTF IR variant field type.
1985 #include <babeltrace/ctf-ir/field-types.h>
1988 A CTF IR <strong><em>variant field type</em></strong> is
1989 a field type that you can use to create concrete @varfields.
1991 You can create a variant field type with
1992 bt_ctf_field_type_variant_create(). This function expects you to pass
1993 both the tag's @enumft and the tag name of the variant field type to
1994 create. The tag's field type is optional, as the Babeltrace system can
1995 automatically resolve it using the tag name. You can leave the tag name
1996 to \c NULL initially, and set it later with
1997 bt_ctf_field_type_variant_set_tag_name(). The tag name must be set when
1998 the variant field type is frozen. See \ref ctfirfieldtypes to learn more
1999 about the automatic resolving and the conditions under which a field
2002 You can add a field to a variant field type with
2003 bt_ctf_field_type_variant_add_field(). All the field names of a
2004 variant field type \em must exist as mapping names in its tag's @enumft.
2006 The effective alignment of the @varfields described by a
2007 variant field type is always 1, but the individual fields of a
2008 @varfield can have custom alignments.
2010 You can set the byte order of <em>all the contained fields</em>,
2011 recursively, of a variant field type with the common
2012 bt_ctf_field_type_set_byte_order() function.
2017 @addtogroup ctfirvarfieldtype
2022 @brief Creates a default, empty @varft with the tag's @enumft
2023 \p tag_field_type and the tag name \p tag_name.
2025 \p tag_field_type can be \c NULL; the tag's field type can be
2026 automatically resolved from the variant field type's tag name (see
2027 \ref ctfirfieldtypes). If \p tag_name is \c NULL, it \em must be set
2028 with bt_ctf_field_type_variant_set_tag_name() \em before the variant
2029 field type is frozen.
2031 \p tag_name can be an absolute or relative reference. See
2032 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2034 @param[in] tag_field_type Tag's enumeration field type
2036 @param[in] tag_name Tag name (copied on success,
2038 @returns Created variant field type, or
2041 @pre \p tag_field_type is an enumeration field type or \c NULL.
2042 @post <strong>On success, if \p tag_field_type is not \c NULL</strong>,
2043 its reference count is incremented.
2044 @postsuccessrefcountret1
2046 extern struct bt_ctf_field_type
*bt_ctf_field_type_variant_create(
2047 struct bt_ctf_field_type
*tag_field_type
,
2048 const char *tag_name
);
2051 @brief Returns the tag's @enumft of the @varft \p variant_field_type.
2053 @param[in] variant_field_type Variant field type of which to get
2054 the tag's enumeration field type.
2055 @returns Tag's enumeration field type of
2056 \p variant_field_type, or \c NULL if the
2057 tag's field type is not set or on
2060 @prenotnull{variant_field_type}
2061 @preisvarft{variant_field_type}
2062 @postrefcountsame{variant_field_type}
2063 @postsuccessrefcountretinc
2065 extern struct bt_ctf_field_type
*bt_ctf_field_type_variant_get_tag_type(
2066 struct bt_ctf_field_type
*variant_field_type
);
2069 @brief Returns the tag name of the @varft \p variant_field_type.
2071 On success, \p variant_field_type remains the sole owner of
2072 the returned string.
2074 @param[in] variant_field_type Variant field type of which to get the
2076 @returns Tag name of \p variant_field_type, or
2077 \c NULL if the tag name is not set or
2080 @prenotnull{variant_field_type}
2081 @preisvarft{variant_field_type}
2083 @sa bt_ctf_field_type_variant_set_tag_name(): Sets the tag name of
2084 a given variant field type.
2085 @sa bt_ctf_field_type_variant_get_tag_field_path(): Returns the tag's
2086 CTF IR field path of a given variant field type.
2088 extern const char *bt_ctf_field_type_variant_get_tag_name(
2089 struct bt_ctf_field_type
*variant_field_type
);
2092 @brief Sets the tag name of the @varft \p variant_field_type.
2094 \p tag_name can be an absolute or relative reference. See
2095 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2097 @param[in] variant_field_type Variant field type of which to set
2099 @param[in] tag_name Tag name of \p variant_field_type
2100 (copied on success).
2101 @returns 0 on success, or a negative value on error.
2103 @prenotnull{variant_field_type}
2105 @prehot{variant_field_type}
2106 @postrefcountsame{variant_field_type}
2108 @sa bt_ctf_field_type_variant_get_tag_name(): Returns the tag name of
2109 a given variant field type.
2111 extern int bt_ctf_field_type_variant_set_tag_name(
2112 struct bt_ctf_field_type
*variant_field_type
,
2113 const char *tag_name
);
2116 @brief Returns the tag's CTF IR field path of the @varft
2117 \p variant_field_type.
2119 The tag's field path of a variant field type is set when automatic
2120 resolving is performed (see \ref ctfirfieldtypes).
2122 @param[in] variant_field_type Variant field type of which to get the
2124 @returns Tag's field path of
2125 \p variant_field_type, or
2126 \c NULL if the tag's field path is not
2127 set yet is not set or on error.
2129 @prenotnull{variant_field_type}
2130 @preisvarft{variant_field_type}
2131 @postsuccessrefcountretinc
2133 @sa bt_ctf_field_type_variant_get_tag_name(): Returns the tag's
2134 name of a given variant field type.
2136 extern struct bt_ctf_field_path
*bt_ctf_field_type_variant_get_tag_field_path(
2137 struct bt_ctf_field_type
*variant_field_type
);
2140 @brief Returns the number of fields (choices) contained in the @varft
2141 \p variant_field_type.
2143 @param[in] variant_field_type Variant field type of which to get
2144 the number of contained fields.
2145 @returns Number of fields contained in
2146 \p variant_field_type, or a negative
2149 @prenotnull{variant_field_type}
2150 @preisvarft{variant_field_type}
2151 @postrefcountsame{variant_field_type}
2153 extern int bt_ctf_field_type_variant_get_field_count(
2154 struct bt_ctf_field_type
*variant_field_type
);
2157 @brief Returns the field (choice) of the @varft \p variant_field_type
2160 On success, the field's type is placed in \p *field_type if
2161 \p field_type is not \c NULL. The field's name is placed in
2162 \p *field_name if \p field_name is not \c NULL.
2163 \p variant_field_type remains the sole owner of \p *field_name.
2165 @param[in] variant_field_type Variant field type of which to get
2166 the field at index \p index.
2167 @param[out] field_name Returned name of the field at index
2168 \p index (can be \c NULL).
2169 @param[out] field_type Returned field type of the field
2170 at index \p index (can be \c NULL).
2171 @param[in] index Index of the field to get from
2172 \p variant_field_type.
2173 @returns 0 on success, or a negative value on error.
2175 @prenotnull{variant_field_type}
2176 @preisvarft{variant_field_type}
2177 @pre \p index is lesser than the number of fields contained in the
2178 variant field type \p variant_field_type (see
2179 bt_ctf_field_type_variant_get_field_count()).
2180 @postrefcountsame{variant_field_type}
2181 @post <strong>On success</strong>, the returned field's type is placed
2182 in \p *field_type and its reference count is incremented.
2184 @sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant
2185 field type's field by name.
2186 @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant
2187 field type's field by current tag value.
2189 extern int bt_ctf_field_type_variant_get_field(
2190 struct bt_ctf_field_type
*variant_field_type
,
2191 const char **field_name
,
2192 struct bt_ctf_field_type
**field_type
, int index
);
2195 @brief Returns the type of the field (choice) named \p field_name
2196 found in the @varft \p variant_field_type.
2198 @param[in] variant_field_type Variant field type of which to get
2200 @param[in] field_name Name of the field to find.
2201 @returns Type of the field named \p field_name in
2202 \p variant_field_type, or
2205 @prenotnull{variant_field_type}
2206 @prenotnull{field_name}
2207 @preisvarft{variant_field_type}
2208 @postrefcountsame{variant_field_type}
2209 @postsuccessrefcountretinc
2211 @sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's
2213 @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant
2214 field type's field by current tag value.
2217 struct bt_ctf_field_type
*bt_ctf_field_type_variant_get_field_type_by_name(
2218 struct bt_ctf_field_type
*variant_field_type
,
2219 const char *field_name
);
2222 @brief Returns the type of the field (choice) selected by the value of
2223 the @enumfield \p tag_field in the @varft \p variant_field_type.
2225 \p tag_field is the current tag value.
2227 The field type of \p tag_field, as returned by bt_ctf_field_get_type(),
2228 \em must be equivalent to the field type returned by
2229 bt_ctf_field_type_variant_get_tag_type() for \p variant_field_type.
2231 @param[in] variant_field_type Variant field type of which to get
2233 @param[in] tag_field Current tag value (variant field type's
2235 @returns Type of the field selected by
2236 \p tag_field in \p variant_field_type,
2237 or \c NULL on error.
2239 @prenotnull{variant_field_type}
2240 @prenotnull{tag_field}
2241 @preisvarft{variant_field_type}
2242 @preisenumfield{tag_field}
2243 @postrefcountsame{variant_field_type}
2244 @postrefcountsame{tag_field}
2245 @postsuccessrefcountretinc
2247 @sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's
2249 @sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant
2250 field type's field by name.
2253 struct bt_ctf_field_type
*bt_ctf_field_type_variant_get_field_type_from_tag(
2254 struct bt_ctf_field_type
*variant_field_type
,
2255 struct bt_ctf_field
*tag_field
);
2258 @brief Adds a field (a choice) named \p field_name with the @ft
2259 \p field_type to the @varft \p variant_field_type.
2261 On success, \p field_type becomes the child of \p variant_field_type.
2263 You \em cannot add a field named \p field_name if there's already a
2264 field named \p field_name in \p variant_field_type.
2266 \p field_name \em must name an existing mapping in the tag's
2267 enumeration field type of \p variant_field_type.
2269 @param[in] variant_field_type Variant field type to which to add
2271 @param[in] field_type Field type of the field to add to
2272 \p variant_field_type.
2273 @param[in] field_name Name of the field to add to
2274 \p variant_field_type
2275 (copied on success).
2276 @returns 0 on success, or a negative value on error.
2278 @prenotnull{variant_field_type}
2279 @prenotnull{field_type}
2280 @prenotnull{field_name}
2281 @preisvarft{variant_field_type}
2282 @pre \p field_type is not and does not contain \p variant_field_type,
2283 recursively, as a field's type.
2284 @prehot{variant_field_type}
2285 @postrefcountsame{variant_field_type}
2286 @postsuccessrefcountinc{field_type}
2288 extern int bt_ctf_field_type_variant_add_field(
2289 struct bt_ctf_field_type
*variant_field_type
,
2290 struct bt_ctf_field_type
*field_type
,
2291 const char *field_name
);
2299 #endif /* BABELTRACE_CTF_IR_FIELD_TYPES_H */