1 #ifndef BABELTRACE_CTF_IR_FIELD_TYPES_H
2 #define BABELTRACE_CTF_IR_FIELD_TYPES_H
5 * BabelTrace - CTF IR: Event field types
7 * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
9 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
11 * Permission is hereby granted, free of charge, to any person obtaining a copy
12 * of this software and associated documentation files (the "Software"), to deal
13 * in the Software without restriction, including without limitation the rights
14 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15 * copies of the Software, and to permit persons to whom the Software is
16 * furnished to do so, subject to the following conditions:
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
29 * The Common Trace Format (CTF) Specification is available at
30 * http://www.efficios.com/ctf
41 @defgroup ctfirfieldtypes CTF IR field types
43 @brief CTF IR field types.
46 #include <babeltrace/ctf-ir/field-types.h>
49 A CTF IR <strong><em>field type</em></strong> is a field type that you
50 can use to create concrete @fields.
52 You can create a @field object from a CTF IR field type object
53 with bt_ctf_field_create().
55 In the CTF IR hierarchy, you can set the root field types of three
58 - \ref ctfirtraceclass
59 - Trace packet header field type: bt_ctf_trace_set_packet_header_type().
60 - \ref ctfirstreamclass
61 - Stream packet context field type:
62 bt_ctf_stream_class_set_packet_context_type().
63 - Stream event header field type:
64 bt_ctf_stream_class_set_event_header_type().
65 - Stream event context field type:
66 bt_ctf_stream_class_set_event_context_type().
67 - \ref ctfireventclass
68 - Event context field type: bt_ctf_event_class_set_context_type().
69 - Event payload field type: bt_ctf_event_class_set_payload_type().
71 As of Babeltrace \btversion, those six previous "root" field types
72 \em must be @structft objects.
74 If, at any level within a given root field type, you add a @seqft or a
75 @varft, you do not need to specify its associated length
76 or tag field type: the length or tag string is enough for the Babeltrace
77 system to resolve the needed field type depending on where this
78 dynamic field type is located within the whole hierarchy. It is
79 guaranteed that this automatic resolving is performed for all the field
80 types contained in a given
81 \link ctfirstreamclass CTF IR stream class\endlink (and in its
82 children \link ctfireventclass CTF IR event classes\endlink) once you
83 add it to a \link ctfirtraceclass CTF IR trace class\endlink with
84 bt_ctf_trace_add_stream_class(). Once a stream class is the child of
85 a trace class, this automatic resolving is performed for the field
86 types of an event class when you add it with
87 bt_ctf_stream_class_add_event_class(). If the system cannot find a path
88 to a field in the hierarchy for a dynamic field type, the adding
91 The standard CTF field types are:
97 <th>CTF IR field which you can create from this field type
100 <td>#BT_CTF_FIELD_TYPE_ID_INTEGER
101 <td>\ref ctfirintfieldtype
102 <td>\ref ctfirintfield
105 <td>#BT_CTF_FIELD_TYPE_ID_FLOAT
106 <td>\ref ctfirfloatfieldtype
107 <td>\ref ctfirfloatfield
110 <td>#BT_CTF_FIELD_TYPE_ID_ENUM
111 <td>\ref ctfirenumfieldtype
112 <td>\ref ctfirenumfield
115 <td>#BT_CTF_FIELD_TYPE_ID_STRING
116 <td>\ref ctfirstringfieldtype
117 <td>\ref ctfirstringfield
120 <td>#BT_CTF_FIELD_TYPE_ID_STRUCT
121 <td>\ref ctfirstructfieldtype
122 <td>\ref ctfirstructfield
125 <td>#BT_CTF_FIELD_TYPE_ID_ARRAY
126 <td>\ref ctfirarrayfieldtype
127 <td>\ref ctfirarrayfield
130 <td>#BT_CTF_FIELD_TYPE_ID_SEQUENCE
131 <td>\ref ctfirseqfieldtype
132 <td>\ref ctfirseqfield
135 <td>#BT_CTF_FIELD_TYPE_ID_VARIANT
136 <td>\ref ctfirvarfieldtype
137 <td>\ref ctfirvarfield
141 Each field type has its own <strong>type ID</strong> (see
142 #bt_ctf_field_type_id). You get the type ID of a field type object
143 with bt_ctf_field_type_get_type_id().
145 You can get a deep copy of a field type with bt_ctf_field_type_copy().
146 This function resets, in the field type copy, the resolved field type
147 of the dynamic field types. The automatic resolving can be done again
148 when you eventually call bt_ctf_event_create(),
149 bt_ctf_stream_class_add_event_class(), or
150 bt_ctf_trace_add_stream_class().
152 You \em must always use bt_ctf_field_type_compare() to compare two
153 field types. Since some parts of the Babeltrace system can copy field
154 types behind the scenes, you \em cannot rely on a simple field type
157 As with any Babeltrace object, CTF IR field type objects have
158 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
159 counts</a>. See \ref refs to learn more about the reference counting
160 management of Babeltrace objects.
162 The following functions can \em freeze field type objects:
164 - bt_ctf_field_create() freezes its field type parameter.
165 - bt_ctf_stream_class_add_event_class(), if its
166 \link ctfirstreamclass CTF IR stream class\endlink parameter has a
167 \link ctfirtraceclass CTF IR trace class\endlink parent, freezes
168 the root field types of its
169 \link ctfireventclass CTF IR event class\endlink parameter.
170 - bt_ctf_trace_add_stream_class() freezes the root field types of the
171 whole trace class hierarchy (trace class, children stream classes,
172 and their children event classes).
173 - bt_ctf_writer_create_stream() freezes the root field types of the
174 whole CTF writer's trace class hierarchy.
175 - bt_ctf_event_create() freezes the root field types of its event class
176 parameter and of ther parent stream class of this event class.
178 You cannot modify a frozen field type object: it is considered
179 immutable, except for \link refs reference counting\endlink.
182 @sa \ref ctfirfieldtypesexamples "Examples"
185 @brief CTF IR field types type and functions.
188 @addtogroup ctfirfieldtypes
193 @struct bt_ctf_field_type
194 @brief A CTF IR field type.
197 struct bt_ctf_field_type
;
198 struct bt_ctf_event_class
;
201 struct bt_ctf_field_path
;
202 struct bt_ctf_field_type_enumeration_mapping_iterator
;
204 /** @cond DOCUMENT */
207 * Babeltrace 1.x enumerations that were also used in CTF writer's API.
208 * They are left here for backward compatibility reasons, but
209 * enum bt_ctf_field_type_id and enum bt_ctf_string_encoding should be used
210 * in new code. Both new enumerations are compatible with their legacy
214 CTF_TYPE_UNKNOWN
= 0,
220 CTF_TYPE_UNTAGGED_VARIANT
,
230 enum ctf_string_encoding
{
243 /// Unknown, used for errors.
244 BT_CTF_SCOPE_UNKNOWN
= -1,
246 /// Trace packet header.
247 BT_CTF_SCOPE_TRACE_PACKET_HEADER
= 1,
249 /// Stream packet context.
250 BT_CTF_SCOPE_STREAM_PACKET_CONTEXT
= 2,
252 /// Stream event header.
253 BT_CTF_SCOPE_STREAM_EVENT_HEADER
= 3,
255 /// Stream event context.
256 BT_CTF_SCOPE_STREAM_EVENT_CONTEXT
= 4,
259 BT_CTF_SCOPE_EVENT_CONTEXT
= 5,
262 BT_CTF_SCOPE_EVENT_PAYLOAD
= 6,
265 BT_CTF_SCOPE_ENV
= 0,
266 BT_CTF_SCOPE_EVENT_FIELDS
= 6,
271 @name Type information
276 @brief Type ID of a @ft.
278 enum bt_ctf_field_type_id
{
279 /// Unknown, used for errors.
280 BT_CTF_FIELD_TYPE_ID_UNKNOWN
= CTF_TYPE_UNKNOWN
,
282 /// \ref ctfirintfieldtype
283 BT_CTF_FIELD_TYPE_ID_INTEGER
= CTF_TYPE_INTEGER
,
285 /// \ref ctfirfloatfieldtype
286 BT_CTF_FIELD_TYPE_ID_FLOAT
= CTF_TYPE_FLOAT
,
288 /// \ref ctfirenumfieldtype
289 BT_CTF_FIELD_TYPE_ID_ENUM
= CTF_TYPE_ENUM
,
291 /// \ref ctfirstringfieldtype
292 BT_CTF_FIELD_TYPE_ID_STRING
= CTF_TYPE_STRING
,
294 /// \ref ctfirstructfieldtype
295 BT_CTF_FIELD_TYPE_ID_STRUCT
= CTF_TYPE_STRUCT
,
298 BT_CTF_TYPE_ID_UNTAGGED_VARIANT
= CTF_TYPE_UNTAGGED_VARIANT
,
301 /// \ref ctfirarrayfieldtype
302 BT_CTF_FIELD_TYPE_ID_ARRAY
= CTF_TYPE_ARRAY
,
304 /// \ref ctfirseqfieldtype
305 BT_CTF_FIELD_TYPE_ID_SEQUENCE
= CTF_TYPE_SEQUENCE
,
307 /// \ref ctfirvarfieldtype
308 BT_CTF_FIELD_TYPE_ID_VARIANT
= CTF_TYPE_VARIANT
,
310 /// Number of enumeration entries.
311 BT_CTF_NR_TYPE_IDS
= NR_CTF_TYPES
,
315 @brief Returns the type ID of the @ft \p field_type.
317 @param[in] field_type Field type of which to get the type ID.
318 @returns Type ID of \p field_type,
319 or #BT_CTF_FIELD_TYPE_ID_UNKNOWN on error.
321 @prenotnull{field_type}
322 @postrefcountsame{field_type}
324 @sa #bt_ctf_field_type_id: CTF IR field type ID.
325 @sa bt_ctf_field_type_is_integer(): Returns whether or not a given
326 field type is a @intft.
327 @sa bt_ctf_field_type_is_floating_point(): Returns whether or not a
328 given field type is a @floatft.
329 @sa bt_ctf_field_type_is_enumeration(): Returns whether or not a given
330 field type is a @enumft.
331 @sa bt_ctf_field_type_is_string(): Returns whether or not a given
332 field type is a @stringft.
333 @sa bt_ctf_field_type_is_structure(): Returns whether or not a given
334 field type is a @structft.
335 @sa bt_ctf_field_type_is_array(): Returns whether or not a given
336 field type is a @arrayft.
337 @sa bt_ctf_field_type_is_sequence(): Returns whether or not a given
338 field type is a @seqft.
339 @sa bt_ctf_field_type_is_variant(): Returns whether or not a given
340 field type is a @varft.
342 extern enum bt_ctf_field_type_id
bt_ctf_field_type_get_type_id(
343 struct bt_ctf_field_type
*field_type
);
346 @brief Returns whether or not the @ft \p field_type is a @intft.
348 @param[in] field_type Field type to check (can be \c NULL).
349 @returns 1 if \p field_type is an integer field type,
350 or 0 otherwise (including if \p field_type is
353 @prenotnull{field_type}
354 @postrefcountsame{field_type}
356 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
359 extern int bt_ctf_field_type_is_integer(struct bt_ctf_field_type
*field_type
);
362 @brief Returns whether or not the @ft \p field_type is a @floatft.
364 @param[in] field_type Field type to check (can be \c NULL).
365 @returns 1 if \p field_type is a floating point
367 or 0 otherwise (including if \p field_type is
370 @postrefcountsame{field_type}
372 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
375 extern int bt_ctf_field_type_is_floating_point(struct bt_ctf_field_type
*field_type
);
378 @brief Returns whether or not the @ft \p field_type is a @enumft.
380 @param[in] field_type Field type to check (can be \c NULL).
381 @returns 1 if \p field_type is an enumeration field type,
382 or 0 otherwise (including if \p field_type is
385 @postrefcountsame{field_type}
387 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
390 extern int bt_ctf_field_type_is_enumeration(struct bt_ctf_field_type
*field_type
);
393 @brief Returns whether or not the @ft \p field_type is a @stringft.
395 @param[in] field_type Field type to check (can be \c NULL).
396 @returns 1 if \p field_type is a string field type,
397 or 0 otherwise (including if \p field_type is
400 @postrefcountsame{field_type}
402 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
405 extern int bt_ctf_field_type_is_string(struct bt_ctf_field_type
*field_type
);
408 @brief Returns whether or not the @ft \p field_type is a @structft.
410 @param[in] field_type Field type to check (can be \c NULL).
411 @returns 1 if \p field_type is a structure field type,
412 or 0 otherwise (including if \p field_type is
415 @postrefcountsame{field_type}
417 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
420 extern int bt_ctf_field_type_is_structure(struct bt_ctf_field_type
*field_type
);
423 @brief Returns whether or not the @ft \p field_type is a @arrayft.
425 @param[in] field_type Field type to check (can be \c NULL).
426 @returns 1 if \p field_type is an array field type,
427 or 0 otherwise (including if \p field_type is
430 @postrefcountsame{field_type}
432 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
435 extern int bt_ctf_field_type_is_array(struct bt_ctf_field_type
*field_type
);
438 @brief Returns whether or not the @ft \p field_type is a @seqft.
440 @param[in] field_type Field type to check (can be \c NULL).
441 @returns 1 if \p field_type is a sequence field type,
442 or 0 otherwise (including if \p field_type is
445 @postrefcountsame{field_type}
447 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
450 extern int bt_ctf_field_type_is_sequence(struct bt_ctf_field_type
*field_type
);
453 @brief Returns whether or not the @ft \p field_type is a @varft.
455 @param[in] field_type Field type to check (can be \c NULL).
456 @returns 1 if \p field_type is a variant field type,
457 or 0 otherwise (including if \p field_type is
460 @postrefcountsame{field_type}
462 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
465 extern int bt_ctf_field_type_is_variant(struct bt_ctf_field_type
*field_type
);
470 @name Common properties types and functions
475 @brief <a href="https://en.wikipedia.org/wiki/Endianness">Byte order</a>
478 enum bt_ctf_byte_order
{
479 /// Unknown, used for errors.
480 BT_CTF_BYTE_ORDER_UNKNOWN
= -1,
483 * Note that native, in the context of the CTF specification, is defined
484 * as "the byte order described in the trace" and does not mean that the
485 * host's endianness will be used.
487 /// Native (default) byte order.
488 BT_CTF_BYTE_ORDER_NATIVE
= 0,
491 BT_CTF_BYTE_ORDER_LITTLE_ENDIAN
,
494 BT_CTF_BYTE_ORDER_BIG_ENDIAN
,
496 /// Network byte order (big-endian).
497 BT_CTF_BYTE_ORDER_NETWORK
,
501 @brief String encoding of a @ft.
503 enum bt_ctf_string_encoding
{
504 /// Unknown, used for errors.
505 BT_CTF_STRING_ENCODING_UNKNOWN
= CTF_STRING_UNKNOWN
,
508 BT_CTF_STRING_ENCODING_NONE
= CTF_STRING_NONE
,
510 /// <a href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a>.
511 BT_CTF_STRING_ENCODING_UTF8
= CTF_STRING_UTF8
,
513 /// <a href="https://en.wikipedia.org/wiki/ASCII">ASCII</a>.
514 BT_CTF_STRING_ENCODING_ASCII
= CTF_STRING_ASCII
,
518 @brief Returns the alignment of the @fields described by
519 the @ft \p field_type.
521 @param[in] field_type Field type which describes the
522 fields of which to get the alignment.
523 @returns Alignment of the fields described by
524 \p field_type, or a negative value on error.
526 @prenotnull{field_type}
527 @postrefcountsame{field_type}
529 @sa bt_ctf_field_type_set_alignment(): Sets the alignment
530 of the fields described by a given field type.
532 extern int bt_ctf_field_type_get_alignment(
533 struct bt_ctf_field_type
*field_type
);
536 @brief Sets the alignment of the @fields described by the
537 @ft \p field_type to \p alignment.
539 \p alignment \em must be greater than 0 and a power of two.
541 @param[in] field_type Field type which describes the fields of
542 which to set the alignment.
543 @param[in] alignment Alignment of the fields described by
545 @returns 0 on success, or a negative value on error.
547 @prenotnull{field_type}
549 @pre \p alignment is greater than 0 and a power of two.
550 @postrefcountsame{field_type}
552 @sa bt_ctf_field_type_get_alignment(): Returns the alignment of the
553 fields described by a given field type.
555 extern int bt_ctf_field_type_set_alignment(struct bt_ctf_field_type
*field_type
,
556 unsigned int alignment
);
559 @brief Returns the byte order of the @fields described by
560 the @ft \p field_type.
562 You can only call this function if \p field_type is a @intft, a
563 @floatft, or a @enumft.
565 @param[in] field_type Field type which describes the
566 fields of which to get the byte order.
567 @returns Byte order of the fields described by
568 \p field_type, or #BT_CTF_BYTE_ORDER_UNKNOWN on
571 @prenotnull{field_type}
572 @pre \p field_type is a @intft, a @floatft, or a @enumft.
573 @postrefcountsame{field_type}
575 @sa bt_ctf_field_type_set_byte_order(): Sets the byte order
576 of the fields described by a given field type.
578 extern enum bt_ctf_byte_order
bt_ctf_field_type_get_byte_order(
579 struct bt_ctf_field_type
*field_type
);
582 @brief Sets the byte order of the @fields described by the
583 @ft \p field_type to \p byte_order.
585 If \p field_type is a compound field type, this function also
586 recursively sets the byte order of its children to \p byte_order.
588 @param[in] field_type Field type which describes the fields of
589 which to set the byte order.
590 @param[in] byte_order Alignment of the fields described by
592 @returns 0 on success, or a negative value on error.
594 @prenotnull{field_type}
596 @pre \p byte_order is #BT_CTF_BYTE_ORDER_NATIVE,
597 #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN, #BT_CTF_BYTE_ORDER_BIG_ENDIAN,
598 or #BT_CTF_BYTE_ORDER_NETWORK.
599 @postrefcountsame{field_type}
601 @sa bt_ctf_field_type_get_byte_order(): Returns the byte order of the
602 fields described by a given field type.
604 extern int bt_ctf_field_type_set_byte_order(
605 struct bt_ctf_field_type
*field_type
,
606 enum bt_ctf_byte_order byte_order
);
611 @name Utility functions
616 @brief Returns whether or not the @ft \p field_type_a
617 is equivalent to the field type \p field_type_b.
619 You \em must use this function to compare two field types: it is not
620 safe to compare two pointer values directly, because, for internal
621 reasons, some parts of the Babeltrace system can copy user field types
622 and discard the original ones.
624 @param[in] field_type_a Field type to compare to \p field_type_b.
625 @param[in] field_type_b Field type to compare to \p field_type_a.
626 @returns 0 if \p field_type_a is equivalent to
627 \p field_type_b, 1 if they are not equivalent,
628 or a negative value on error.
630 @prenotnull{field_type_a}
631 @prenotnull{field_type_b}
632 @postrefcountsame{field_type_a}
633 @postrefcountsame{field_type_b}
635 extern int bt_ctf_field_type_compare(struct bt_ctf_field_type
*field_type_a
,
636 struct bt_ctf_field_type
*field_type_b
);
639 @brief Creates a \em deep copy of the @ft \p field_type.
641 You can copy a frozen field type: the resulting copy is
644 This function resets the tag field type of a copied @varft. The
645 automatic field resolving which some functions of the API perform
646 can set it again when the returned field type is used (learn more
647 in the detailed description of this module).
649 @param[in] field_type Field type to copy.
650 @returns Deep copy of \p field_type on success,
653 @prenotnull{field_type}
654 @postrefcountsame{field_type}
655 @postsuccessrefcountret1
656 @post <strong>On success</strong>, the returned field type is not frozen.
658 extern struct bt_ctf_field_type
*bt_ctf_field_type_copy(
659 struct bt_ctf_field_type
*field_type
);
666 @defgroup ctfirintfieldtype CTF IR integer field type
667 @ingroup ctfirfieldtypes
668 @brief CTF IR integer field type.
671 #include <babeltrace/ctf-ir/field-types.h>
674 A CTF IR <strong><em>integer field type</em></strong> is a field type that
675 you can use to create concrete @intfield objects.
677 You can create an integer field type
678 with bt_ctf_field_type_integer_create().
680 An integer field type has the following properties:
685 <th>Value at creation
690 <td>\b Alignment (bits) of the described integer fields
692 <td>bt_ctf_field_type_get_alignment()
693 <td>bt_ctf_field_type_set_alignment()
696 <td><strong>Byte order</strong> of the described integer fields
697 <td>#BT_CTF_BYTE_ORDER_NATIVE
698 <td>bt_ctf_field_type_get_byte_order()
699 <td>bt_ctf_field_type_set_byte_order()
702 <td><strong>Storage size</strong> (bits) of the described
704 <td>Specified at creation
705 <td>bt_ctf_field_type_integer_get_size()
706 <td>bt_ctf_field_type_integer_set_size()
709 <td><strong>Signedness</strong> of the described integer fields
711 <td>bt_ctf_field_type_integer_get_signed()
712 <td>bt_ctf_field_type_integer_set_signed()
715 <td><strong>Preferred display base</strong> of the described
717 <td>#BT_CTF_INTEGER_BASE_DECIMAL
718 <td>bt_ctf_field_type_integer_get_base()
719 <td>bt_ctf_field_type_integer_set_base()
722 <td>\b Encoding of the described integer fields
723 <td>#BT_CTF_STRING_ENCODING_NONE
724 <td>bt_ctf_field_type_integer_get_encoding()
725 <td>bt_ctf_field_type_integer_set_encoding()
729 \link ctfirclockclass CTF IR clock class\endlink</strong>
731 <td>bt_ctf_field_type_integer_get_mapped_clock_class()
732 <td>bt_ctf_field_type_integer_set_mapped_clock_class()
738 @sa \ref ctfirfieldtypesexamples_intfieldtype "Examples"
740 @addtogroup ctfirintfieldtype
745 @brief Preferred display base (radix) of a @intft.
747 enum bt_ctf_integer_base
{
748 /// Unknown, used for errors.
749 BT_CTF_INTEGER_BASE_UNKNOWN
= -1,
752 BT_CTF_INTEGER_BASE_BINARY
= 2,
755 BT_CTF_INTEGER_BASE_OCTAL
= 8,
758 BT_CTF_INTEGER_BASE_DECIMAL
= 10,
761 BT_CTF_INTEGER_BASE_HEXADECIMAL
= 16,
765 @brief Creates a default @intft with \p size bits as the storage size
766 of the @intfields it describes.
768 You can change the storage size of the integer fields described by
769 the created integer field type later with
770 bt_ctf_field_type_integer_set_size().
772 @param[in] size Storage size (bits) of the described integer fields.
773 @returns Created integer field type, or \c NULL on error.
775 @pre \p size is greater than 0 and lesser than or equal to 64.
776 @postsuccessrefcountret1
778 extern struct bt_ctf_field_type
*bt_ctf_field_type_integer_create(
782 @brief Returns the storage size, in bits, of the @intfields
783 described by the @intft \p int_field_type.
785 @param[in] int_field_type Integer field type which describes the
786 integer fields of which to get the
788 @returns Storage size (bits) of the integer
789 fields described by \p int_field_type,
790 or a negative value on error.
792 @prenotnull{int_field_type}
793 @preisintft{int_field_type}
794 @postrefcountsame{int_field_type}
796 @sa bt_ctf_field_type_integer_set_size(): Sets the storage size of the
797 integer fields described by a given integer field type.
799 extern int bt_ctf_field_type_integer_get_size(
800 struct bt_ctf_field_type
*int_field_type
);
803 @brief Sets the storage size, in bits, of the @intfields described by
804 the @intft \p int_field_type.
806 @param[in] int_field_type Integer field type which describes the
807 integer fields of which to set the
809 @param[in] size Storage size (bits) of the integer fields
810 described by \p int_field_type.
811 @returns 0 on success, or a negative value on error.
813 @prenotnull{int_field_type}
814 @preisintft{int_field_type}
815 @prehot{int_field_type}
816 @pre \p size is greater than 0 and lesser than or equal to 64.
817 @postrefcountsame{int_field_type}
819 @sa bt_ctf_field_type_integer_get_size(): Returns the storage size of
820 the integer fields described by a given integer field type.
822 extern int bt_ctf_field_type_integer_set_size(
823 struct bt_ctf_field_type
*int_field_type
, size_t size
);
826 @brief Returns whether or not the @intfields described by the @intft
827 \p int_field_type are signed.
829 @param[in] int_field_type Integer field type which describes the
830 integer fields of which to get the
832 @returns 1 if the integer fields described by
833 \p int_field_type are signed, 0 if they
834 are unsigned, or a negative value on
837 @prenotnull{int_field_type}
838 @preisintft{int_field_type}
839 @postrefcountsame{int_field_type}
841 @sa bt_ctf_field_type_integer_set_signed(): Sets the signedness of the
842 integer fields described by a given integer field type.
844 extern int bt_ctf_field_type_integer_get_signed(
845 struct bt_ctf_field_type
*int_field_type
);
848 @brief Sets whether or not the @intfields described by
849 the @intft \p int_field_type are signed.
851 @param[in] int_field_type Integer field type which describes the
852 integer fields of which to set the
854 @param[in] is_signed Signedness of the integer fields
855 described by \p int_field_type; 0 means
856 \em unsigned, 1 means \em signed.
857 @returns 0 on success, or a negative value on error.
859 @prenotnull{int_field_type}
860 @preisintft{int_field_type}
861 @prehot{int_field_type}
862 @pre \p is_signed is 0 or 1.
863 @postrefcountsame{int_field_type}
865 @sa bt_ctf_field_type_integer_get_signed(): Returns the signedness of
866 the integer fields described by a given integer field type.
868 extern int bt_ctf_field_type_integer_set_signed(
869 struct bt_ctf_field_type
*int_field_type
, int is_signed
);
872 @brief Returns the preferred display base (radix) of the @intfields
873 described by the @intft \p int_field_type.
875 @param[in] int_field_type Integer field type which describes the
876 integer fields of which to get the
877 preferred display base.
878 @returns Preferred display base of the integer
879 fields described by \p int_field_type,
880 or #BT_CTF_INTEGER_BASE_UNKNOWN on
883 @prenotnull{int_field_type}
884 @preisintft{int_field_type}
885 @postrefcountsame{int_field_type}
887 @sa bt_ctf_field_type_integer_set_base(): Sets the preferred display
888 base of the integer fields described by a given integer field
891 extern enum bt_ctf_integer_base
bt_ctf_field_type_integer_get_base(
892 struct bt_ctf_field_type
*int_field_type
);
895 @brief Sets the preferred display base (radix) of the @intfields
896 described by the @intft \p int_field_type to \p base.
898 @param[in] int_field_type Integer field type which describes the
899 integer fields of which to set the
900 preferred display base.
901 @param[in] base Preferred display base of the integer
902 fields described by \p int_field_type.
903 @returns 0 on success, or a negative value on error.
905 @prenotnull{int_field_type}
906 @preisintft{int_field_type}
907 @prehot{int_field_type}
908 @pre \p base is #BT_CTF_INTEGER_BASE_BINARY, #BT_CTF_INTEGER_BASE_OCTAL,
909 #BT_CTF_INTEGER_BASE_DECIMAL, or
910 #BT_CTF_INTEGER_BASE_HEXADECIMAL.
911 @postrefcountsame{int_field_type}
913 @sa bt_ctf_field_type_integer_get_base(): Returns the preferred display
914 base of the integer fields described by a given
917 extern int bt_ctf_field_type_integer_set_base(
918 struct bt_ctf_field_type
*int_field_type
,
919 enum bt_ctf_integer_base base
);
922 @brief Returns the encoding of the @intfields described by
923 the @intft \p int_field_type.
925 @param[in] int_field_type Integer field type which describes the
926 integer fields of which to get the
928 @returns Encoding of the integer
929 fields described by \p int_field_type,
930 or #BT_CTF_STRING_ENCODING_UNKNOWN on
933 @prenotnull{int_field_type}
934 @preisintft{int_field_type}
935 @postrefcountsame{int_field_type}
937 @sa bt_ctf_field_type_integer_set_encoding(): Sets the encoding
938 of the integer fields described by a given integer field type.
940 extern enum bt_ctf_string_encoding
bt_ctf_field_type_integer_get_encoding(
941 struct bt_ctf_field_type
*int_field_type
);
944 @brief Sets the encoding of the @intfields described by the @intft
945 \p int_field_type to \p encoding.
947 You can use this property, in CTF IR, to create "text" @arrayfts or
948 @seqfts. A text array field type is array field type with an unsigned,
949 8-bit integer field type having an encoding as its element field type.
951 @param[in] int_field_type Integer field type which describes the
952 integer fields of which to set the
954 @param[in] encoding Encoding of the integer
955 fields described by \p int_field_type.
956 @returns 0 on success, or a negative value on error.
958 @prenotnull{int_field_type}
959 @preisintft{int_field_type}
960 @prehot{int_field_type}
961 @pre \p encoding is #BT_CTF_STRING_ENCODING_NONE,
962 #BT_CTF_STRING_ENCODING_ASCII, or
963 #BT_CTF_STRING_ENCODING_UTF8.
964 @postrefcountsame{int_field_type}
966 @sa bt_ctf_field_type_integer_get_encoding(): Returns the encoding of
967 the integer fields described by a given integer field type.
969 extern int bt_ctf_field_type_integer_set_encoding(
970 struct bt_ctf_field_type
*int_field_type
,
971 enum bt_ctf_string_encoding encoding
);
974 @brief Returns the \link ctfirclockclass CTF IR clock class\endlink
975 mapped to the @intft \p int_field_type.
977 The mapped clock class, if any, indicates the class of the clock which
978 an @intfield described by \p int_field_type should sample or update.
979 This mapped clock class is only indicative.
981 @param[in] int_field_type Integer field type of which to get the
983 @returns Mapped clock class of \p int_field_type,
984 or \c NULL if there's no mapped clock
987 @prenotnull{int_field_type}
988 @preisintft{int_field_type}
989 @postrefcountsame{int_field_type}
990 @postsuccessrefcountretinc
992 @sa bt_ctf_field_type_integer_set_mapped_clock_class(): Sets the mapped
993 clock class of a given integer field type.
995 extern struct bt_ctf_clock_class
*bt_ctf_field_type_integer_get_mapped_clock_class(
996 struct bt_ctf_field_type
*int_field_type
);
999 @brief Sets the \link ctfirclockclass CTF IR clock class\endlink mapped
1000 to the @intft \p int_field_type to \p clock_class.
1002 The mapped clock class, if any, indicates the class of the clock which
1003 an integer field described by \p int_field_type should sample or update.
1004 This mapped clock class is only indicative.
1006 @param[in] int_field_type Integer field type of which to set the
1008 @param[in] clock_class Mapped clock class of \p int_field_type.
1009 @returns 0 on success, or a negative value on error.
1011 @prenotnull{int_field_type}
1012 @prenotnull{clock_class}
1013 @preisintft{int_field_type}
1014 @prehot{int_field_type}
1015 @postrefcountsame{int_field_type}
1016 @postsuccessrefcountinc{clock_class}
1018 @sa bt_ctf_field_type_integer_get_mapped_clock_class(): Returns the mapped
1019 clock class of a given integer field type.
1021 extern int bt_ctf_field_type_integer_set_mapped_clock_class(
1022 struct bt_ctf_field_type
*int_field_type
,
1023 struct bt_ctf_clock_class
*clock_class
);
1028 @defgroup ctfirfloatfieldtype CTF IR floating point number field type
1029 @ingroup ctfirfieldtypes
1030 @brief CTF IR floating point number field type.
1033 #include <babeltrace/ctf-ir/field-types.h>
1036 A CTF IR <strong><em>floating point number field type</em></strong> is
1037 a field type that you can use to create concrete @floatfields.
1039 You can create a floating point number field type
1040 with bt_ctf_field_type_floating_point_create().
1042 A floating point number field type has the following properties:
1047 <th>Value at creation
1052 <td>\b Alignment (bits) of the described floating point
1055 <td>bt_ctf_field_type_get_alignment()
1056 <td>bt_ctf_field_type_set_alignment()
1059 <td><strong>Byte order</strong> of the described floating point
1061 <td>#BT_CTF_BYTE_ORDER_NATIVE
1062 <td>bt_ctf_field_type_get_byte_order()
1063 <td>bt_ctf_field_type_set_byte_order()
1066 <td><strong>Exponent storage size</strong> (bits) of the described
1067 floating point number fields
1069 <td>bt_ctf_field_type_floating_point_get_exponent_digits()
1070 <td>bt_ctf_field_type_floating_point_set_exponent_digits()
1073 <td><strong>Mantissa and sign storage size</strong> (bits) of the
1074 described floating point number fields
1075 <td>24 (23-bit mantissa, 1-bit sign)
1076 <td>bt_ctf_field_type_floating_point_get_mantissa_digits()
1077 <td>bt_ctf_field_type_floating_point_set_mantissa_digits()
1083 @sa \ref ctfirfieldtypesexamples_floatfieldtype "Examples"
1085 @addtogroup ctfirfloatfieldtype
1090 @brief Creates a default @floatft.
1092 @returns Created floating point number field type,
1093 or \c NULL on error.
1095 @postsuccessrefcountret1
1097 extern struct bt_ctf_field_type
*bt_ctf_field_type_floating_point_create(void);
1100 @brief Returns the exponent storage size of the @floatfields
1101 described by the @floatft \p float_field_type.
1103 @param[in] float_field_type Floating point number field type which
1104 describes the floating point number
1105 fields of which to get the exponent
1107 @returns Exponent storage size of the
1108 floating point number fields
1109 described by \p float_field_type,
1110 or a negative value on error.
1112 @prenotnull{float_field_type}
1113 @preisfloatft{float_field_type}
1114 @postrefcountsame{float_field_type}
1116 @sa bt_ctf_field_type_floating_point_set_exponent_digits(): Sets the
1117 exponent storage size of the floating point number fields
1118 described by a given floating point number field type.
1120 extern int bt_ctf_field_type_floating_point_get_exponent_digits(
1121 struct bt_ctf_field_type
*float_field_type
);
1124 @brief Sets the exponent storage size of the @floatfields described by
1125 the @floatft \p float_field_type to \p exponent_size.
1127 As of Babeltrace \btversion, \p exponent_size can only be 8 or 11.
1129 @param[in] float_field_type Floating point number field type which
1130 describes the floating point number
1131 fields of which to set the exponent
1133 @param[in] exponent_size Exponent storage size of the floating
1134 point number fields described by \p
1136 @returns 0 on success, or a negative value on error.
1138 @prenotnull{float_field_type}
1139 @preisfloatft{float_field_type}
1140 @prehot{float_field_type}
1141 @pre \p exponent_size is 8 or 11.
1142 @postrefcountsame{float_field_type}
1144 @sa bt_ctf_field_type_floating_point_get_exponent_digits(): Returns the
1145 exponent storage size of the floating point number fields
1146 described by a given floating point number field type.
1148 extern int bt_ctf_field_type_floating_point_set_exponent_digits(
1149 struct bt_ctf_field_type
*float_field_type
,
1150 unsigned int exponent_size
);
1153 @brief Returns the mantissa and sign storage size of the @floatfields
1154 described by the @floatft \p float_field_type.
1156 On success, the returned value is the sum of the mantissa \em and
1159 @param[in] float_field_type Floating point number field type which
1160 describes the floating point number
1161 fields of which to get the mantissa and
1163 @returns Mantissa and sign storage size of the
1164 floating point number fields
1165 described by \p float_field_type,
1166 or a negative value on error.
1168 @prenotnull{float_field_type}
1169 @preisfloatft{float_field_type}
1170 @postrefcountsame{float_field_type}
1172 @sa bt_ctf_field_type_floating_point_set_mantissa_digits(): Sets the
1173 mantissa and size storage size of the floating point number
1174 fields described by a given floating point number field type.
1176 extern int bt_ctf_field_type_floating_point_get_mantissa_digits(
1177 struct bt_ctf_field_type
*float_field_type
);
1180 @brief Sets the mantissa and sign storage size of the @floatfields
1181 described by the @floatft \p float_field_type to \p
1184 As of Babeltrace \btversion, \p mantissa_sign_size can only be 24 or 53.
1186 @param[in] float_field_type Floating point number field type which
1187 describes the floating point number
1188 fields of which to set the mantissa and
1190 @param[in] mantissa_sign_size Mantissa and sign storage size of the
1191 floating point number fields described
1192 by \p float_field_type.
1193 @returns 0 on success, or a negative value on error.
1195 @prenotnull{float_field_type}
1196 @preisfloatft{float_field_type}
1197 @prehot{float_field_type}
1198 @pre \p mantissa_sign_size is 24 or 53.
1199 @postrefcountsame{float_field_type}
1201 @sa bt_ctf_field_type_floating_point_get_mantissa_digits(): Returns the
1202 mantissa and sign storage size of the floating point number
1203 fields described by a given floating point number field type.
1205 extern int bt_ctf_field_type_floating_point_set_mantissa_digits(
1206 struct bt_ctf_field_type
*float_field_type
,
1207 unsigned int mantissa_sign_size
);
1212 @defgroup ctfirenumfieldtype CTF IR enumeration field type
1213 @ingroup ctfirfieldtypes
1214 @brief CTF IR enumeration field type.
1217 #include <babeltrace/ctf-ir/field-types.h>
1220 A CTF IR <strong><em>enumeration field type</em></strong> is
1221 a field type that you can use to create concrete @enumfields.
1223 You can create an enumeration field type with
1224 bt_ctf_field_type_enumeration_create(). This function needs a @intft
1225 which represents the storage field type of the created enumeration field
1226 type. In other words, an enumeration field type wraps an integer field
1227 type and adds label-value mappings to it.
1229 An enumeration mapping has:
1231 - A <strong>name</strong>.
1232 - A <strong>range of values</strong> given by a beginning and an ending
1233 value, both included in the range.
1235 You can add a mapping to an enumeration field type with
1236 bt_ctf_field_type_enumeration_add_mapping() or
1237 bt_ctf_field_type_enumeration_add_mapping_unsigned(), depending on the
1238 signedness of the wrapped @intft.
1240 You can find mappings by name or by value with the following find
1243 - bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
1244 mappings with a given name.
1245 - bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value():
1246 Finds the mappings which contain a given unsigned value in their
1248 - bt_ctf_field_type_enumeration_find_mappings_by_signed_value():
1249 Finds the mappings which contain a given signed value in their range.
1251 Those functions return a @enumftiter on the result set of the find
1254 Many mappings can share the same name, and the ranges of a given
1255 enumeration field type are allowed to overlap. For example,
1256 this is a valid set of mappings:
1265 The following set of mappings is also valid:
1274 Here, the range of the second \c APPLE mapping overlaps the range of
1275 the \c CHERRY mapping.
1277 @sa ctfirenumftmappingiter
1281 @addtogroup ctfirenumfieldtype
1286 @brief Creates a default @enumft wrapping the @intft \p int_field_type.
1288 @param[in] int_field_type Integer field type wrapped by the
1289 created enumeration field type.
1290 @returns Created enumeration field type,
1291 or \c NULL on error.
1293 @prenotnull{int_field_type}
1294 @preisintft{int_field_type}
1295 @postsuccessrefcountinc{int_field_type}
1296 @postsuccessrefcountret1
1298 extern struct bt_ctf_field_type
*bt_ctf_field_type_enumeration_create(
1299 struct bt_ctf_field_type
*int_field_type
);
1302 @brief Returns the @intft wrapped by the @enumft \p enum_field_type.
1304 @param[in] enum_field_type Enumeration field type of which to get
1305 the wrapped integer field type.
1306 @returns Integer field type wrapped by
1307 \p enum_field_type, or \c NULL on
1310 @prenotnull{enum_field_type}
1311 @preisenumft{enum_field_type}
1312 @postrefcountsame{enum_field_type}
1313 @postsuccessrefcountretinc
1316 struct bt_ctf_field_type
*bt_ctf_field_type_enumeration_get_container_type(
1317 struct bt_ctf_field_type
*enum_field_type
);
1320 @brief Returns the number of mappings contained in the
1321 @enumft \p enum_field_type.
1323 @param[in] enum_field_type Enumeration field type of which to get
1324 the number of contained mappings.
1325 @returns Number of mappings contained in
1326 \p enum_field_type, or a negative
1329 @prenotnull{enum_field_type}
1330 @preisenumft{enum_field_type}
1331 @postrefcountsame{enum_field_type}
1333 extern int bt_ctf_field_type_enumeration_get_mapping_count(
1334 struct bt_ctf_field_type
*enum_field_type
);
1337 @brief Returns the signed mapping of the @enumft
1338 \p enum_field_type at index \p index.
1340 The @intft wrapped by \p enum_field_type, as returned by
1341 bt_ctf_field_type_enumeration_get_container_type(), must be \b signed
1342 to use this function.
1344 On success, \p enum_field_type remains the sole owner of \p *name.
1346 @param[in] enum_field_type Enumeration field type of which to get
1347 the mapping at index \p index.
1348 @param[in] index Index of the mapping to get from
1350 @param[out] name Returned name of the mapping at index
1352 @param[out] range_begin Returned beginning of the range
1353 (included) of the mapping at index \p
1355 @param[out] range_end Returned end of the range (included) of
1356 the mapping at index \p index.
1357 @returns 0 on success, or a negative value on error.
1359 @prenotnull{enum_field_type}
1361 @prenotnull{range_begin}
1362 @prenotnull{range_end}
1363 @preisenumft{enum_field_type}
1364 @pre The wrapped @intft of \p enum_field_type is signed.
1365 @pre \p index is lesser than the number of mappings contained in the
1366 enumeration field type \p enum_field_type (see
1367 bt_ctf_field_type_enumeration_get_mapping_count()).
1368 @postrefcountsame{enum_field_type}
1370 @sa bt_ctf_field_type_enumeration_get_mapping_unsigned(): Returns the
1371 unsigned mapping contained by a given enumeration field type
1374 extern int bt_ctf_field_type_enumeration_get_mapping_signed(
1375 struct bt_ctf_field_type
*enum_field_type
, int index
,
1376 const char **name
, int64_t *range_begin
, int64_t *range_end
);
1379 @brief Returns the unsigned mapping of the @enumft
1380 \p enum_field_type at index \p index.
1382 The @intft wrapped by \p enum_field_type, as returned by
1383 bt_ctf_field_type_enumeration_get_container_type(), must be
1384 \b unsigned to use this function.
1386 On success, \p enum_field_type remains the sole owner of \p *name.
1388 @param[in] enum_field_type Enumeration field type of which to get
1389 the mapping at index \p index.
1390 @param[in] index Index of the mapping to get from
1392 @param[out] name Returned name of the mapping at index
1394 @param[out] range_begin Returned beginning of the range
1395 (included) of the mapping at index \p
1397 @param[out] range_end Returned end of the range (included) of
1398 the mapping at index \p index.
1399 @returns 0 on success, or a negative value on error.
1401 @prenotnull{enum_field_type}
1403 @prenotnull{range_begin}
1404 @prenotnull{range_end}
1405 @preisenumft{enum_field_type}
1406 @pre The wrapped @intft of \p enum_field_type is unsigned.
1407 @pre \p index is lesser than the number of mappings contained in the
1408 enumeration field type \p enum_field_type (see
1409 bt_ctf_field_type_enumeration_get_mapping_count()).
1410 @postrefcountsame{enum_field_type}
1412 @sa bt_ctf_field_type_enumeration_get_mapping_signed(): Returns the
1413 signed mapping contained by a given enumeration field type
1416 extern int bt_ctf_field_type_enumeration_get_mapping_unsigned(
1417 struct bt_ctf_field_type
*enum_field_type
, int index
,
1418 const char **name
, uint64_t *range_begin
,
1419 uint64_t *range_end
);
1422 @brief Finds the mappings of the @enumft \p enum_field_type which
1425 This function returns an iterator on the result set of this find
1426 operation. See \ref ctfirenumftmappingiter for more details.
1428 @param[in] enum_field_type Enumeration field type of which to find
1429 the mappings named \p name.
1430 @param[in] name Name of the mappings to find in
1432 @returns @enumftiter on the set of mappings named
1433 \p name in \p enum_field_type, or
1434 \c NULL if no mappings were found or
1437 @prenotnull{enum_field_type}
1439 @preisenumft{enum_field_type}
1440 @postrefcountsame{enum_field_type}
1441 @postsuccessrefcountret1
1442 @post <strong>On success</strong>, the returned @enumftiter can iterate
1443 on at least one mapping.
1445 @sa bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): Finds
1446 the mappings of a given enumeration field type which contain
1447 a given signed value in their range.
1448 @sa bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): Finds
1449 the mappings of a given enumeration field type which contain
1450 a given unsigned value in their range.
1452 extern struct bt_ctf_field_type_enumeration_mapping_iterator
*
1453 bt_ctf_field_type_enumeration_find_mappings_by_name(
1454 struct bt_ctf_field_type
*enum_field_type
,
1458 @brief Finds the mappings of the @enumft \p enum_field_type which
1459 contain the signed value \p value in their range.
1461 This function returns an iterator on the result set of this find
1462 operation. See \ref ctfirenumftmappingiter for more details.
1464 @param[in] enum_field_type Enumeration field type of which to find
1465 the mappings which contain \p value.
1466 @param[in] value Value to find in the ranges of the
1467 mappings of \p enum_field_type.
1468 @returns @enumftiter on the set of mappings of
1469 \p enum_field_type which contain
1470 \p value in their range, or \c NULL if
1471 no mappings were found or on error.
1473 @prenotnull{enum_field_type}
1474 @preisenumft{enum_field_type}
1475 @postrefcountsame{enum_field_type}
1476 @postsuccessrefcountret1
1477 @post <strong>On success</strong>, the returned @enumftiter can iterate
1478 on at least one mapping.
1480 @sa bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
1481 mappings of a given enumeration field type which have a given
1483 @sa bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): Finds
1484 the mappings of a given enumeration field type which contain
1485 a given unsigned value in their range.
1487 extern struct bt_ctf_field_type_enumeration_mapping_iterator
*
1488 bt_ctf_field_type_enumeration_find_mappings_by_signed_value(
1489 struct bt_ctf_field_type
*enum_field_type
,
1493 @brief Finds the mappings of the @enumft \p enum_field_type which
1494 contain the unsigned value \p value in their range.
1496 This function returns an iterator on the result set of this find
1497 operation. See \ref ctfirenumftmappingiter for more details.
1499 @param[in] enum_field_type Enumeration field type of which to find
1500 the mappings which contain \p value.
1501 @param[in] value Value to find in the ranges of the
1502 mappings of \p enum_field_type.
1503 @returns @enumftiter on the set of mappings of
1504 \p enum_field_type which contain
1505 \p value in their range, or \c NULL
1506 if no mappings were found or
1509 @prenotnull{enum_field_type}
1510 @preisenumft{enum_field_type}
1511 @postrefcountsame{enum_field_type}
1512 @postsuccessrefcountret1
1513 @post <strong>On success</strong>, the returned @enumftiter can iterate
1514 on at least one mapping.
1516 @sa bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
1517 mappings of a given enumeration field type which have a given
1519 @sa bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): Finds
1520 the mappings of a given enumeration field type which contain
1521 a given unsigned value in their range.
1523 extern struct bt_ctf_field_type_enumeration_mapping_iterator
*
1524 bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(
1525 struct bt_ctf_field_type
*enum_field_type
,
1529 @brief Adds a mapping to the @enumft \p enum_field_type which maps the
1530 name \p name to the signed range \p range_begin (included) to
1531 \p range_end (included).
1533 Make \p range_begin and \p range_end the same value to add a mapping
1536 The @intft wrapped by \p enum_field_type, as returned by
1537 bt_ctf_field_type_enumeration_get_container_type(), must be
1538 \b signed to use this function.
1540 A mapping in \p enum_field_type can exist with the name \p name.
1542 @param[in] enum_field_type Enumeration field type to which to add
1544 @param[in] name Name of the mapping to add (copied
1546 @param[in] range_begin Beginning of the range of the mapping
1548 @param[in] range_end End of the range of the mapping
1550 @returns 0 on success, or a negative value on error.
1552 @prenotnull{enum_field_type}
1554 @prehot{enum_field_type}
1555 @preisenumft{enum_field_type}
1556 @pre The wrapped @intft of \p enum_field_type is signed.
1557 @pre \p range_end is greater than or equal to \p range_begin.
1558 @postrefcountsame{enum_field_type}
1560 @sa bt_ctf_field_type_enumeration_add_mapping_unsigned(): Adds an
1561 unsigned mapping to a given enumeration field type.
1563 extern int bt_ctf_field_type_enumeration_add_mapping(
1564 struct bt_ctf_field_type
*enum_field_type
, const char *name
,
1565 int64_t range_begin
, int64_t range_end
);
1568 @brief Adds a mapping to the @enumft \p enum_field_type which maps
1569 the name \p name to the unsigned
1570 range \p range_begin (included) to \p range_end (included).
1572 Make \p range_begin and \p range_end the same value to add a mapping
1575 The @intft wrapped by \p enum_field_type, as returned by
1576 bt_ctf_field_type_enumeration_get_container_type(), must be
1577 \b unsigned to use this function.
1579 A mapping in \p enum_field_type can exist with the name \p name.
1581 @param[in] enum_field_type Enumeration field type to which to add
1583 @param[in] name Name of the mapping to add (copied
1585 @param[in] range_begin Beginning of the range of the mapping
1587 @param[in] range_end End of the range of the mapping
1589 @returns 0 on success, or a negative value on error.
1591 @prenotnull{enum_field_type}
1593 @prehot{enum_field_type}
1594 @preisenumft{enum_field_type}
1595 @pre The wrapped @intft of \p enum_field_type is unsigned.
1596 @pre \p range_end is greater than or equal to \p range_begin.
1597 @postrefcountsame{enum_field_type}
1599 @sa bt_ctf_field_type_enumeration_add_mapping(): Adds a signed
1600 mapping to a given enumeration field type.
1602 extern int bt_ctf_field_type_enumeration_add_mapping_unsigned(
1603 struct bt_ctf_field_type
*enum_field_type
, const char *name
,
1604 uint64_t range_begin
, uint64_t range_end
);
1609 @defgroup ctfirenumftmappingiter CTF IR enumeration field type mapping iterator
1610 @ingroup ctfirenumfieldtype
1611 @brief CTF IR enumeration field type mapping iterator.
1614 #include <babeltrace/ctf-ir/field-types.h>
1617 A CTF IR <strong><em>enumeration field type mapping
1618 iterator</em></strong> is an iterator on @enumft mappings.
1620 You can get an enumeration mapping iterator from one of the following
1623 - Find operations of an @enumft object:
1624 - bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
1625 mappings with a given name.
1626 - bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value():
1627 Finds the mappings which contain a given unsigned value in their
1629 - bt_ctf_field_type_enumeration_find_mappings_by_signed_value():
1630 Finds the mappings which contain a given signed value in their range.
1631 - bt_ctf_field_enumeration_get_mappings(): Finds the mappings in the
1632 @enumft of an @enumfield containing its current integral value in
1635 Those functions guarantee that the returned iterator can iterate on
1636 at least one mapping. Otherwise, they return \c NULL.
1638 You can get the name and the range of a mapping iterator's current
1640 bt_ctf_field_type_enumeration_mapping_iterator_get_signed()
1642 bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(),
1643 depending on the signedness of the @intft wrapped by the
1644 @enumft. If you only need the name of the current mapping, you can
1645 use any of the two functions and set the \p range_begin and \p range_end
1646 parameters to \c NULL.
1648 You can advance an enumeration field type mapping iterator to the next
1650 bt_ctf_field_type_enumeration_mapping_iterator_next(). This
1651 function returns a negative value when you reach the end of the
1654 As with any Babeltrace object, CTF IR enumeration field type mapping
1655 iterator objects have <a
1656 href="https://en.wikipedia.org/wiki/Reference_counting">reference
1657 counts</a>. See \ref refs to learn more about the reference counting
1658 management of Babeltrace objects.
1660 @sa ctfirenumfieldtype
1662 @addtogroup ctfirenumftmappingiter
1667 @struct bt_ctf_field_type_enumeration_mapping_iterator
1668 @brief A CTF IR enumeration field type mapping iterator.
1669 @sa ctfirenumftmappingiter
1673 @brief Returns the name and the range of the current (signed) mapping
1674 of the @enumftiter \p iter.
1676 If one of \p range_begin or \p range_end is not \c NULL, the @intft
1677 wrapped by the @enumft from which \p iter was obtained, as returned by
1678 bt_ctf_field_type_enumeration_get_container_type(), must be
1679 \b signed to use this function. Otherwise, if you only need to get the
1680 name of the current mapping, set \p range_begin and \p range_end to
1683 On success, if \p name is not \c NULL, \p *name remains valid as long
1684 as \p iter exists and
1685 bt_ctf_field_type_enumeration_mapping_iterator_next() is
1686 \em not called on \p iter.
1688 @param[in] iter Enumeration field type mapping iterator
1689 of which to get the range of the current
1691 @param[out] name Returned name of the current mapping of
1692 \p iter (can be \c NULL to ignore).
1693 @param[out] range_begin Returned beginning of the range
1694 (included) of the current mapping of
1695 \p iter (can be \c NULL to ignore).
1696 @param[out] range_end Returned end of the range
1697 (included) of the current mapping of
1698 \p iter (can be \c NULL to ignore).
1699 @returns 0 on success, or a negative value on error.
1702 @postrefcountsame{iter}
1704 @sa bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned():
1705 Returns the name and the unsigned range of the current mapping
1706 of a given enumeration field type mapping iterator.
1708 extern int bt_ctf_field_type_enumeration_mapping_iterator_get_signed(
1709 struct bt_ctf_field_type_enumeration_mapping_iterator
*iter
,
1710 const char **name
, int64_t *range_begin
, int64_t *range_end
);
1713 @brief Returns the name and the range of the current (unsigned) mapping
1714 of the @enumftiter \p iter.
1716 If one of \p range_begin or \p range_end is not \c NULL, the @intft
1717 wrapped by the @enumft from which \p iter was obtained, as returned by
1718 bt_ctf_field_type_enumeration_get_container_type(), must be
1719 \b unsigned to use this function. Otherwise, if you only need to get the
1720 name of the current mapping, set \p range_begin and \p range_end to
1723 On success, if \p name is not \c NULL, \p *name remains valid as long
1724 as \p iter exists and
1725 bt_ctf_field_type_enumeration_mapping_iterator_next() is
1726 \em not called on \p iter.
1728 @param[in] iter Enumeration field type mapping iterator
1729 of which to get the range of the current
1731 @param[out] name Returned name of the current mapping of
1732 \p iter (can be \c NULL to ignore).
1733 @param[out] range_begin Returned beginning of the range
1734 (included) of the current mapping of
1735 \p iter (can be \c NULL to ignore).
1736 @param[out] range_end Returned end of the range
1737 (included) of the current mapping of
1738 \p iter (can be \c NULL to ignore).
1739 @returns 0 on success, or a negative value on error.
1742 @postrefcountsame{iter}
1745 bt_ctf_field_type_enumeration_mapping_iterator_get_signed():
1746 Returns the name and the signed range of the current mapping of
1747 a given enumeration field type mapping iterator.
1749 extern int bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(
1750 struct bt_ctf_field_type_enumeration_mapping_iterator
*iter
,
1751 const char **name
, uint64_t *range_begin
, uint64_t *range_end
);
1754 @brief Advances the @enumftiter \p iter to the next mapping.
1756 @param[in] iter Enumeration field type mapping iterator to
1758 @returns 0 on success, or a negative value on error or
1759 when you reach the end of the set.
1762 @postrefcountsame{iter}
1764 extern int bt_ctf_field_type_enumeration_mapping_iterator_next(
1765 struct bt_ctf_field_type_enumeration_mapping_iterator
*iter
);
1770 @defgroup ctfirstringfieldtype CTF IR string field type
1771 @ingroup ctfirfieldtypes
1772 @brief CTF IR string field type.
1775 #include <babeltrace/ctf-ir/field-types.h>
1778 A CTF IR <strong><em>string field type</em></strong> is a field type that
1779 you can use to create concrete @stringfields.
1781 You can create a string field type
1782 with bt_ctf_field_type_string_create().
1784 A string field type has only one property: the \b encoding of its
1785 described @stringfields. By default, the encoding of the string fields
1786 described by a string field type is #BT_CTF_STRING_ENCODING_UTF8. You
1787 can set the encoding of the string fields described by a string field
1788 type with bt_ctf_field_type_string_set_encoding().
1790 @sa ctfirstringfield
1793 @addtogroup ctfirstringfieldtype
1798 @brief Creates a default @stringft.
1800 @returns Created string field type, or \c NULL on error.
1802 @postsuccessrefcountret1
1804 extern struct bt_ctf_field_type
*bt_ctf_field_type_string_create(void);
1807 @brief Returns the encoding of the @stringfields described by
1808 the @stringft \p string_field_type.
1810 @param[in] string_field_type String field type which describes the
1811 string fields of which to get the
1813 @returns Encoding of the string
1814 fields described by \p string_field_type,
1815 or #BT_CTF_STRING_ENCODING_UNKNOWN on
1818 @prenotnull{string_field_type}
1819 @preisstringft{string_field_type}
1820 @postrefcountsame{string_field_type}
1822 @sa bt_ctf_field_type_string_set_encoding(): Sets the encoding
1823 of the string fields described by a given string field type.
1825 extern enum bt_ctf_string_encoding
bt_ctf_field_type_string_get_encoding(
1826 struct bt_ctf_field_type
*string_field_type
);
1829 @brief Sets the encoding of the @stringfields described by the
1830 @stringft \p string_field_type to \p encoding.
1832 @param[in] string_field_type String field type which describes the
1833 string fields of which to set the
1835 @param[in] encoding Encoding of the string fields described
1836 by \p string_field_type.
1837 @returns 0 on success, or a negative value on error.
1839 @prenotnull{string_field_type}
1840 @preisstringft{string_field_type}
1841 @prehot{string_field_type}
1842 @pre \p encoding is #BT_CTF_STRING_ENCODING_ASCII or
1843 #BT_CTF_STRING_ENCODING_UTF8.
1844 @postrefcountsame{string_field_type}
1846 @sa bt_ctf_field_type_string_get_encoding(): Returns the encoding of
1847 the string fields described by a given string field type.
1849 extern int bt_ctf_field_type_string_set_encoding(
1850 struct bt_ctf_field_type
*string_field_type
,
1851 enum bt_ctf_string_encoding encoding
);
1856 @defgroup ctfirstructfieldtype CTF IR structure field type
1857 @ingroup ctfirfieldtypes
1858 @brief CTF IR structure field type.
1861 #include <babeltrace/ctf-ir/field-types.h>
1864 A CTF IR <strong><em>structure field type</em></strong> is
1865 a field type that you can use to create concrete @structfields.
1867 You can create a structure field type
1868 with bt_ctf_field_type_structure_create(). This function creates
1869 an empty structure field type, with no fields.
1871 You can add a field to a structure field type with
1872 bt_ctf_field_type_structure_add_field(). Two fields in a structure
1873 field type cannot have the same name.
1875 You can set the \em minimum alignment of the structure fields described
1876 by a structure field type with the common
1877 bt_ctf_field_type_set_alignment() function. The \em effective alignment
1878 of the structure fields described by a structure field type, as per
1879 <a href="http://diamon.org/ctf/">CTF</a>, is the \em maximum value amongst
1880 the effective alignments of all its fields. Note that the effective
1881 alignment of @varfields is always 1.
1883 You can set the byte order of <em>all the contained fields</em>,
1884 recursively, of a structure field type with the common
1885 bt_ctf_field_type_set_byte_order() function.
1887 @sa ctfirstructfield
1890 @addtogroup ctfirstructfieldtype
1895 @brief Creates a default, empty @structft.
1897 @returns Created structure field type,
1898 or \c NULL on error.
1900 @postsuccessrefcountret1
1902 extern struct bt_ctf_field_type
*bt_ctf_field_type_structure_create(void);
1905 @brief Returns the number of fields contained in the
1906 @structft \p struct_field_type.
1908 @param[in] struct_field_type Structure field type of which to get
1909 the number of contained fields.
1910 @returns Number of fields contained in
1911 \p struct_field_type, or a negative
1914 @prenotnull{struct_field_type}
1915 @preisstructft{struct_field_type}
1916 @postrefcountsame{struct_field_type}
1918 extern int bt_ctf_field_type_structure_get_field_count(
1919 struct bt_ctf_field_type
*struct_field_type
);
1922 @brief Returns the field of the @structft \p struct_field_type
1925 On success, the field's type is placed in \p *field_type if
1926 \p field_type is not \c NULL. The field's name is placed in
1927 \p *field_name if \p field_name is not \c NULL.
1928 \p struct_field_type remains the sole owner of \p *field_name.
1930 @param[in] struct_field_type Structure field type of which to get
1931 the field at index \p index.
1932 @param[out] field_name Returned name of the field at index
1933 \p index (can be \c NULL).
1934 @param[out] field_type Returned field type of the field
1935 at index \p index (can be \c NULL).
1936 @param[in] index Index of the field to get from
1937 \p struct_field_type.
1938 @returns 0 on success, or a negative value on error.
1940 @prenotnull{struct_field_type}
1941 @preisstructft{struct_field_type}
1942 @pre \p index is lesser than the number of fields contained in the
1943 structure field type \p struct_field_type (see
1944 bt_ctf_field_type_structure_get_field_count()).
1945 @postrefcountsame{struct_field_type}
1946 @post <strong>On success</strong>, the returned field's type is placed
1947 in \p *field_type and its reference count is incremented.
1949 @sa bt_ctf_field_type_structure_get_field_type_by_name(): Finds a
1950 structure field type's field by name.
1952 extern int bt_ctf_field_type_structure_get_field(
1953 struct bt_ctf_field_type
*struct_field_type
,
1954 const char **field_name
, struct bt_ctf_field_type
**field_type
,
1958 @brief Returns the type of the field named \p field_name found in
1959 the @structft \p struct_field_type.
1961 @param[in] struct_field_type Structure field type of which to get
1963 @param[in] field_name Name of the field to find.
1964 @returns Type of the field named \p field_name in
1965 \p struct_field_type, or
1968 @prenotnull{struct_field_type}
1969 @prenotnull{field_name}
1970 @preisstructft{struct_field_type}
1971 @postrefcountsame{struct_field_type}
1972 @postsuccessrefcountretinc
1974 @sa bt_ctf_field_type_structure_get_field(): Finds a
1975 structure field type's field by index.
1978 struct bt_ctf_field_type
*bt_ctf_field_type_structure_get_field_type_by_name(
1979 struct bt_ctf_field_type
*struct_field_type
,
1980 const char *field_name
);
1983 @brief Adds a field named \p field_name with the @ft
1984 \p field_type to the @structft \p struct_field_type.
1986 On success, \p field_type becomes the child of \p struct_field_type.
1988 This function adds the new field after the current last field of
1989 \p struct_field_type (append mode).
1991 You \em cannot add a field named \p field_name if there's already a
1992 field named \p field_name in \p struct_field_type.
1994 @param[in] struct_field_type Structure field type to which to add
1996 @param[in] field_type Field type of the field to add to
1997 \p struct_field_type.
1998 @param[in] field_name Name of the field to add to
1999 \p struct_field_type
2000 (copied on success).
2001 @returns 0 on success, or a negative value on error.
2003 @prenotnull{struct_field_type}
2004 @prenotnull{field_type}
2005 @prenotnull{field_name}
2006 @preisstructft{struct_field_type}
2007 @pre \p field_type is not and does not contain \p struct_field_type,
2008 recursively, as a field's type.
2009 @prehot{struct_field_type}
2010 @postrefcountsame{struct_field_type}
2011 @postsuccessrefcountinc{field_type}
2013 extern int bt_ctf_field_type_structure_add_field(
2014 struct bt_ctf_field_type
*struct_field_type
,
2015 struct bt_ctf_field_type
*field_type
,
2016 const char *field_name
);
2021 @defgroup ctfirarrayfieldtype CTF IR array field type
2022 @ingroup ctfirfieldtypes
2023 @brief CTF IR array field type.
2026 #include <babeltrace/ctf-ir/field-types.h>
2029 A CTF IR <strong><em>array field type</em></strong> is a field type that
2030 you can use to create concrete @arrayfields.
2032 You can create an array field type
2033 with bt_ctf_field_type_array_create(). This function needs
2034 the @ft of the fields contained by the array fields described by the
2035 array field type to create.
2040 @addtogroup ctfirarrayfieldtype
2045 @brief Creates a default @arrayft with
2046 \p element_field_type as the field type of the fields contained
2047 in its described @arrayfields of length \p length.
2049 @param[in] element_field_type Field type of the fields contained in
2050 the array fields described by the
2051 created array field type.
2052 @param[in] length Length of the array fields described by
2053 the created array field type.
2054 @returns Created array field type, or
2057 @prenotnull{element_field_type}
2058 @postsuccessrefcountinc{element_field_type}
2059 @postsuccessrefcountret1
2061 extern struct bt_ctf_field_type
*bt_ctf_field_type_array_create(
2062 struct bt_ctf_field_type
*element_field_type
,
2063 unsigned int length
);
2066 @brief Returns the @ft of the @fields contained in
2067 the @arrayfields described by the @arrayft \p array_field_type.
2069 @param[in] array_field_type Array field type of which to get
2070 the type of the fields contained in its
2071 described array fields.
2072 @returns Type of the fields contained in the
2073 array fields described by
2074 \p array_field_type, or \c NULL
2077 @prenotnull{array_field_type}
2078 @preisarrayft{array_field_type}
2079 @postrefcountsame{array_field_type}
2080 @postsuccessrefcountretinc
2082 extern struct bt_ctf_field_type
*bt_ctf_field_type_array_get_element_type(
2083 struct bt_ctf_field_type
*array_field_type
);
2086 @brief Returns the number of @fields contained in the
2087 @arrayfields described by the @arrayft \p array_field_type.
2089 @param[in] array_field_type Array field type of which to get
2090 the number of fields contained in its
2091 described array fields.
2092 @returns Number of fields contained in the
2093 array fields described by
2094 \p array_field_type, or a negative value
2097 @prenotnull{array_field_type}
2098 @preisarrayft{array_field_type}
2099 @postrefcountsame{array_field_type}
2101 extern int64_t bt_ctf_field_type_array_get_length(
2102 struct bt_ctf_field_type
*array_field_type
);
2107 @defgroup ctfirseqfieldtype CTF IR sequence field type
2108 @ingroup ctfirfieldtypes
2109 @brief CTF IR sequence field type.
2112 #include <babeltrace/ctf-ir/field-types.h>
2115 A CTF IR <strong><em>sequence field type</em></strong> is
2116 a field type that you can use to create concrete @seqfields.
2118 You can create a sequence field type with
2119 bt_ctf_field_type_sequence_create(). This function needs the @ft
2120 of the fields contained by the sequence fields described by the created
2121 sequence field type. This function also needs the length name of the
2122 sequence field type to create. The length name is used to automatically
2123 resolve the length's field type. See \ref ctfirfieldtypes to learn more
2124 about the automatic resolving.
2129 @addtogroup ctfirseqfieldtype
2134 @brief Creates a default @seqft with \p element_field_type as the
2135 @ft of the @fields contained in its described @seqfields
2136 with the length name \p length_name.
2138 \p length_name can be an absolute or relative reference. See
2139 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2141 @param[in] element_field_type Field type of the fields contained in
2142 the sequence fields described by the
2143 created sequence field type.
2144 @param[in] length_name Length name (copied on success).
2145 @returns Created array field type, or
2148 @prenotnull{element_field_type}
2149 @prenotnull{length_name}
2150 @postsuccessrefcountinc{element_field_type}
2151 @postsuccessrefcountret1
2153 extern struct bt_ctf_field_type
*bt_ctf_field_type_sequence_create(
2154 struct bt_ctf_field_type
*element_field_type
,
2155 const char *length_name
);
2158 @brief Returns the @ft of the @fields contained in the @seqft
2159 described by the @seqft \p sequence_field_type.
2161 @param[in] sequence_field_type Sequence field type of which to get
2162 the type of the fields contained in its
2163 described sequence fields.
2164 @returns Type of the fields contained in the
2165 sequence fields described by
2166 \p sequence_field_type, or \c NULL
2169 @prenotnull{sequence_field_type}
2170 @preisseqft{sequence_field_type}
2171 @postrefcountsame{sequence_field_type}
2172 @postsuccessrefcountretinc
2174 extern struct bt_ctf_field_type
*bt_ctf_field_type_sequence_get_element_type(
2175 struct bt_ctf_field_type
*sequence_field_type
);
2178 @brief Returns the length name of the @seqft \p sequence_field_type.
2180 On success, \p sequence_field_type remains the sole owner of
2181 the returned string.
2183 @param[in] sequence_field_type Sequence field type of which to get the
2185 @returns Length name of \p sequence_field_type,
2186 or \c NULL on error.
2188 @prenotnull{sequence_field_type}
2189 @preisseqft{sequence_field_type}
2191 @sa bt_ctf_field_type_sequence_get_length_field_path(): Returns the
2192 length's CTF IR field path of a given sequence field type.
2194 extern const char *bt_ctf_field_type_sequence_get_length_field_name(
2195 struct bt_ctf_field_type
*sequence_field_type
);
2198 @brief Returns the length's CTF IR field path of the @seqft
2199 \p sequence_field_type.
2201 The length's field path of a sequence field type is set when automatic
2202 resolving is performed (see \ref ctfirfieldtypes).
2204 @param[in] sequence_field_type Sequence field type of which to get the
2205 length's field path.
2206 @returns Length's field path of
2207 \p sequence_field_type, or
2208 \c NULL if the length's field path is
2209 not set yet is not set or on error.
2211 @prenotnull{sequence_field_type}
2212 @preisseqft{sequence_field_type}
2213 @postsuccessrefcountretinc
2215 @sa bt_ctf_field_type_sequence_get_length_field_name(): Returns the
2216 length's name of a given sequence field type.
2218 extern struct bt_ctf_field_path
*bt_ctf_field_type_sequence_get_length_field_path(
2219 struct bt_ctf_field_type
*sequence_field_type
);
2224 @defgroup ctfirvarfieldtype CTF IR variant field type
2225 @ingroup ctfirfieldtypes
2226 @brief CTF IR variant field type.
2229 #include <babeltrace/ctf-ir/field-types.h>
2232 A CTF IR <strong><em>variant field type</em></strong> is
2233 a field type that you can use to create concrete @varfields.
2235 You can create a variant field type with
2236 bt_ctf_field_type_variant_create(). This function expects you to pass
2237 both the tag's @enumft and the tag name of the variant field type to
2238 create. The tag's field type is optional, as the Babeltrace system can
2239 automatically resolve it using the tag name. You can leave the tag name
2240 to \c NULL initially, and set it later with
2241 bt_ctf_field_type_variant_set_tag_name(). The tag name must be set when
2242 the variant field type is frozen. See \ref ctfirfieldtypes to learn more
2243 about the automatic resolving and the conditions under which a field
2246 You can add a field to a variant field type with
2247 bt_ctf_field_type_variant_add_field(). All the field names of a
2248 variant field type \em must exist as mapping names in its tag's @enumft.
2250 The effective alignment of the @varfields described by a
2251 variant field type is always 1, but the individual fields of a
2252 @varfield can have custom alignments.
2254 You can set the byte order of <em>all the contained fields</em>,
2255 recursively, of a variant field type with the common
2256 bt_ctf_field_type_set_byte_order() function.
2261 @addtogroup ctfirvarfieldtype
2266 @brief Creates a default, empty @varft with the tag's @enumft
2267 \p tag_field_type and the tag name \p tag_name.
2269 \p tag_field_type can be \c NULL; the tag's field type can be
2270 automatically resolved from the variant field type's tag name (see
2271 \ref ctfirfieldtypes). If \p tag_name is \c NULL, it \em must be set
2272 with bt_ctf_field_type_variant_set_tag_name() \em before the variant
2273 field type is frozen.
2275 \p tag_name can be an absolute or relative reference. See
2276 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2278 @param[in] tag_field_type Tag's enumeration field type
2280 @param[in] tag_name Tag name (copied on success,
2282 @returns Created variant field type, or
2285 @pre \p tag_field_type is an enumeration field type or \c NULL.
2286 @post <strong>On success, if \p tag_field_type is not \c NULL</strong>,
2287 its reference count is incremented.
2288 @postsuccessrefcountret1
2290 extern struct bt_ctf_field_type
*bt_ctf_field_type_variant_create(
2291 struct bt_ctf_field_type
*tag_field_type
,
2292 const char *tag_name
);
2295 @brief Returns the tag's @enumft of the @varft \p variant_field_type.
2297 @param[in] variant_field_type Variant field type of which to get
2298 the tag's enumeration field type.
2299 @returns Tag's enumeration field type of
2300 \p variant_field_type, or \c NULL if the
2301 tag's field type is not set or on
2304 @prenotnull{variant_field_type}
2305 @preisvarft{variant_field_type}
2306 @postrefcountsame{variant_field_type}
2307 @postsuccessrefcountretinc
2309 extern struct bt_ctf_field_type
*bt_ctf_field_type_variant_get_tag_type(
2310 struct bt_ctf_field_type
*variant_field_type
);
2313 @brief Returns the tag name of the @varft \p variant_field_type.
2315 On success, \p variant_field_type remains the sole owner of
2316 the returned string.
2318 @param[in] variant_field_type Variant field type of which to get the
2320 @returns Tag name of \p variant_field_type, or
2321 \c NULL if the tag name is not set or
2324 @prenotnull{variant_field_type}
2325 @preisvarft{variant_field_type}
2327 @sa bt_ctf_field_type_variant_set_tag_name(): Sets the tag name of
2328 a given variant field type.
2329 @sa bt_ctf_field_type_variant_get_tag_field_path(): Returns the tag's
2330 CTF IR field path of a given variant field type.
2332 extern const char *bt_ctf_field_type_variant_get_tag_name(
2333 struct bt_ctf_field_type
*variant_field_type
);
2336 @brief Sets the tag name of the @varft \p variant_field_type.
2338 \p tag_name can be an absolute or relative reference. See
2339 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2341 @param[in] variant_field_type Variant field type of which to set
2343 @param[in] tag_name Tag name of \p variant_field_type
2344 (copied on success).
2345 @returns 0 on success, or a negative value on error.
2347 @prenotnull{variant_field_type}
2349 @prehot{variant_field_type}
2350 @postrefcountsame{variant_field_type}
2352 @sa bt_ctf_field_type_variant_get_tag_name(): Returns the tag name of
2353 a given variant field type.
2355 extern int bt_ctf_field_type_variant_set_tag_name(
2356 struct bt_ctf_field_type
*variant_field_type
,
2357 const char *tag_name
);
2360 @brief Returns the tag's CTF IR field path of the @varft
2361 \p variant_field_type.
2363 The tag's field path of a variant field type is set when automatic
2364 resolving is performed (see \ref ctfirfieldtypes).
2366 @param[in] variant_field_type Variant field type of which to get the
2368 @returns Tag's field path of
2369 \p variant_field_type, or
2370 \c NULL if the tag's field path is not
2371 set yet is not set or on error.
2373 @prenotnull{variant_field_type}
2374 @preisvarft{variant_field_type}
2375 @postsuccessrefcountretinc
2377 @sa bt_ctf_field_type_variant_get_tag_name(): Returns the tag's
2378 name of a given variant field type.
2380 extern struct bt_ctf_field_path
*bt_ctf_field_type_variant_get_tag_field_path(
2381 struct bt_ctf_field_type
*variant_field_type
);
2384 @brief Returns the number of fields (choices) contained in the @varft
2385 \p variant_field_type.
2387 @param[in] variant_field_type Variant field type of which to get
2388 the number of contained fields.
2389 @returns Number of fields contained in
2390 \p variant_field_type, or a negative
2393 @prenotnull{variant_field_type}
2394 @preisvarft{variant_field_type}
2395 @postrefcountsame{variant_field_type}
2397 extern int bt_ctf_field_type_variant_get_field_count(
2398 struct bt_ctf_field_type
*variant_field_type
);
2401 @brief Returns the field (choice) of the @varft \p variant_field_type
2404 On success, the field's type is placed in \p *field_type if
2405 \p field_type is not \c NULL. The field's name is placed in
2406 \p *field_name if \p field_name is not \c NULL.
2407 \p variant_field_type remains the sole owner of \p *field_name.
2409 @param[in] variant_field_type Variant field type of which to get
2410 the field at index \p index.
2411 @param[out] field_name Returned name of the field at index
2412 \p index (can be \c NULL).
2413 @param[out] field_type Returned field type of the field
2414 at index \p index (can be \c NULL).
2415 @param[in] index Index of the field to get from
2416 \p variant_field_type.
2417 @returns 0 on success, or a negative value on error.
2419 @prenotnull{variant_field_type}
2420 @preisvarft{variant_field_type}
2421 @pre \p index is lesser than the number of fields contained in the
2422 variant field type \p variant_field_type (see
2423 bt_ctf_field_type_variant_get_field_count()).
2424 @postrefcountsame{variant_field_type}
2425 @post <strong>On success</strong>, the returned field's type is placed
2426 in \p *field_type and its reference count is incremented.
2428 @sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant
2429 field type's field by name.
2430 @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant
2431 field type's field by current tag value.
2433 extern int bt_ctf_field_type_variant_get_field(
2434 struct bt_ctf_field_type
*variant_field_type
,
2435 const char **field_name
,
2436 struct bt_ctf_field_type
**field_type
, int index
);
2439 @brief Returns the type of the field (choice) named \p field_name
2440 found in the @varft \p variant_field_type.
2442 @param[in] variant_field_type Variant field type of which to get
2444 @param[in] field_name Name of the field to find.
2445 @returns Type of the field named \p field_name in
2446 \p variant_field_type, or
2449 @prenotnull{variant_field_type}
2450 @prenotnull{field_name}
2451 @preisvarft{variant_field_type}
2452 @postrefcountsame{variant_field_type}
2453 @postsuccessrefcountretinc
2455 @sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's
2457 @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant
2458 field type's field by current tag value.
2461 struct bt_ctf_field_type
*bt_ctf_field_type_variant_get_field_type_by_name(
2462 struct bt_ctf_field_type
*variant_field_type
,
2463 const char *field_name
);
2466 @brief Returns the type of the field (choice) selected by the value of
2467 the @enumfield \p tag_field in the @varft \p variant_field_type.
2469 \p tag_field is the current tag value.
2471 The field type of \p tag_field, as returned by bt_ctf_field_get_type(),
2472 \em must be equivalent to the field type returned by
2473 bt_ctf_field_type_variant_get_tag_type() for \p variant_field_type.
2475 @param[in] variant_field_type Variant field type of which to get
2477 @param[in] tag_field Current tag value (variant field type's
2479 @returns Type of the field selected by
2480 \p tag_field in \p variant_field_type,
2481 or \c NULL on error.
2483 @prenotnull{variant_field_type}
2484 @prenotnull{tag_field}
2485 @preisvarft{variant_field_type}
2486 @preisenumfield{tag_field}
2487 @postrefcountsame{variant_field_type}
2488 @postrefcountsame{tag_field}
2489 @postsuccessrefcountretinc
2491 @sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's
2493 @sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant
2494 field type's field by name.
2497 struct bt_ctf_field_type
*bt_ctf_field_type_variant_get_field_type_from_tag(
2498 struct bt_ctf_field_type
*variant_field_type
,
2499 struct bt_ctf_field
*tag_field
);
2502 @brief Adds a field (a choice) named \p field_name with the @ft
2503 \p field_type to the @varft \p variant_field_type.
2505 On success, \p field_type becomes the child of \p variant_field_type.
2507 You \em cannot add a field named \p field_name if there's already a
2508 field named \p field_name in \p variant_field_type.
2510 \p field_name \em must name an existing mapping in the tag's
2511 enumeration field type of \p variant_field_type.
2513 @param[in] variant_field_type Variant field type to which to add
2515 @param[in] field_type Field type of the field to add to
2516 \p variant_field_type.
2517 @param[in] field_name Name of the field to add to
2518 \p variant_field_type
2519 (copied on success).
2520 @returns 0 on success, or a negative value on error.
2522 @prenotnull{variant_field_type}
2523 @prenotnull{field_type}
2524 @prenotnull{field_name}
2525 @preisvarft{variant_field_type}
2526 @pre \p field_type is not and does not contain \p variant_field_type,
2527 recursively, as a field's type.
2528 @prehot{variant_field_type}
2529 @postrefcountsame{variant_field_type}
2530 @postsuccessrefcountinc{field_type}
2532 extern int bt_ctf_field_type_variant_add_field(
2533 struct bt_ctf_field_type
*variant_field_type
,
2534 struct bt_ctf_field_type
*field_type
,
2535 const char *field_name
);
2543 #endif /* BABELTRACE_CTF_IR_FIELD_TYPES_H */