1 #ifndef BABELTRACE_CTF_IR_FIELD_TYPES_H
2 #define BABELTRACE_CTF_IR_FIELD_TYPES_H
5 * BabelTrace - CTF IR: Event field types
7 * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
9 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
11 * Permission is hereby granted, free of charge, to any person obtaining a copy
12 * of this software and associated documentation files (the "Software"), to deal
13 * in the Software without restriction, including without limitation the rights
14 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15 * copies of the Software, and to permit persons to whom the Software is
16 * furnished to do so, subject to the following conditions:
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
29 * The Common Trace Format (CTF) Specification is available at
30 * http://www.efficios.com/ctf
34 #include <babeltrace/ref.h>
37 #include <babeltrace/types.h>
47 @defgroup ctfirfieldtypes CTF IR field types
49 @brief CTF IR field types.
52 #include <babeltrace/ctf-ir/field-types.h>
55 A CTF IR <strong><em>field type</em></strong> is a field type that you
56 can use to create concrete @fields.
58 You can create a @field object from a CTF IR field type object
59 with bt_field_create().
61 In the CTF IR hierarchy, you can set the root field types of three
64 - \ref ctfirtraceclass
65 - Trace packet header field type: bt_trace_set_packet_header_field_type().
66 - \ref ctfirstreamclass
67 - Stream packet context field type:
68 bt_stream_class_set_packet_context_field_type().
69 - Stream event header field type:
70 bt_stream_class_set_event_header_field_type().
71 - Stream event context field type:
72 bt_stream_class_set_event_context_field_type().
73 - \ref ctfireventclass
74 - Event context field type: bt_event_class_set_context_field_type().
75 - Event payload field type: bt_event_class_set_payload_field_type().
77 As of Babeltrace \btversion, those six previous "root" field types
78 \em must be @structft objects.
80 If, at any level within a given root field type, you add a @seqft or a
81 @varft, you do not need to specify its associated length
82 or tag field type: the length or tag string is enough for the Babeltrace
83 system to resolve the needed field type depending on where this
84 dynamic field type is located within the whole hierarchy. It is
85 guaranteed that this automatic resolving is performed for all the field
86 types contained in a given
87 \link ctfirstreamclass CTF IR stream class\endlink (and in its
88 children \link ctfireventclass CTF IR event classes\endlink) once you
89 add it to a \link ctfirtraceclass CTF IR trace class\endlink with
90 bt_trace_add_stream_class(). Once a stream class is the child of
91 a trace class, this automatic resolving is performed for the field
92 types of an event class when you add it with
93 bt_stream_class_add_event_class(). If the system cannot find a path
94 to a field in the hierarchy for a dynamic field type, the adding
97 The standard CTF field types are:
102 <th>CTF IR field type
103 <th>CTF IR field which you can create from this field type
106 <td>#BT_FIELD_TYPE_ID_INTEGER
107 <td>\ref ctfirintfieldtype
108 <td>\ref ctfirintfield
111 <td>#BT_FIELD_TYPE_ID_FLOAT
112 <td>\ref ctfirfloatfieldtype
113 <td>\ref ctfirfloatfield
116 <td>#BT_FIELD_TYPE_ID_ENUM
117 <td>\ref ctfirenumfieldtype
118 <td>\ref ctfirenumfield
121 <td>#BT_FIELD_TYPE_ID_STRING
122 <td>\ref ctfirstringfieldtype
123 <td>\ref ctfirstringfield
126 <td>#BT_FIELD_TYPE_ID_STRUCT
127 <td>\ref ctfirstructfieldtype
128 <td>\ref ctfirstructfield
131 <td>#BT_FIELD_TYPE_ID_ARRAY
132 <td>\ref ctfirarrayfieldtype
133 <td>\ref ctfirarrayfield
136 <td>#BT_FIELD_TYPE_ID_SEQUENCE
137 <td>\ref ctfirseqfieldtype
138 <td>\ref ctfirseqfield
141 <td>#BT_FIELD_TYPE_ID_VARIANT
142 <td>\ref ctfirvarfieldtype
143 <td>\ref ctfirvarfield
147 Each field type has its own <strong>type ID</strong> (see
148 #bt_field_type_id). You get the type ID of a field type object
149 with bt_field_type_get_type_id().
151 You can get a deep copy of a field type with bt_field_type_copy().
152 This function resets, in the field type copy, the resolved field type
153 of the dynamic field types. The automatic resolving can be done again
154 when you eventually call bt_event_create(),
155 bt_stream_class_add_event_class(), or
156 bt_trace_add_stream_class().
158 You \em must always use bt_field_type_compare() to compare two
159 field types. Since some parts of the Babeltrace system can copy field
160 types behind the scenes, you \em cannot rely on a simple field type
163 As with any Babeltrace object, CTF IR field type objects have
164 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
165 counts</a>. See \ref refs to learn more about the reference counting
166 management of Babeltrace objects.
168 The following functions can \em freeze field type objects:
170 - bt_field_create() freezes its field type parameter.
171 - bt_stream_class_add_event_class(), if its
172 \link ctfirstreamclass CTF IR stream class\endlink parameter has a
173 \link ctfirtraceclass CTF IR trace class\endlink parent, freezes
174 the root field types of its
175 \link ctfireventclass CTF IR event class\endlink parameter.
176 - bt_trace_add_stream_class() freezes the root field types of the
177 whole trace class hierarchy (trace class, children stream classes,
178 and their children event classes).
179 - bt_writer_create_stream() freezes the root field types of the
180 whole CTF writer's trace class hierarchy.
181 - bt_event_create() freezes the root field types of its event class
182 parameter and of ther parent stream class of this event class.
184 You cannot modify a frozen field type object: it is considered
185 immutable, except for \link refs reference counting\endlink.
188 @sa \ref ctfirfieldtypesexamples "Examples"
191 @brief CTF IR field types type and functions.
194 @addtogroup ctfirfieldtypes
199 @struct bt_field_type
200 @brief A CTF IR field type.
203 struct bt_field_type
;
204 struct bt_event_class
;
207 struct bt_field_path
;
208 struct bt_field_type_enumeration_mapping_iterator
;
214 /// Unknown, used for errors.
215 BT_SCOPE_UNKNOWN
= -1,
217 /// Trace packet header.
218 BT_SCOPE_TRACE_PACKET_HEADER
= 1,
220 /// Stream packet context.
221 BT_SCOPE_STREAM_PACKET_CONTEXT
= 2,
223 /// Stream event header.
224 BT_SCOPE_STREAM_EVENT_HEADER
= 3,
226 /// Stream event context.
227 BT_SCOPE_STREAM_EVENT_CONTEXT
= 4,
230 BT_SCOPE_EVENT_CONTEXT
= 5,
233 BT_SCOPE_EVENT_PAYLOAD
= 6,
237 BT_SCOPE_EVENT_FIELDS
= 6,
242 @name Type information
247 @brief Type ID of a @ft.
249 enum bt_field_type_id
{
250 /// Unknown, used for errors.
251 BT_FIELD_TYPE_ID_UNKNOWN
= -1,
253 /// \ref ctfirintfieldtype
254 BT_FIELD_TYPE_ID_INTEGER
= 0,
256 /// \ref ctfirfloatfieldtype
257 BT_FIELD_TYPE_ID_FLOAT
= 1,
259 /// \ref ctfirenumfieldtype
260 BT_FIELD_TYPE_ID_ENUM
= 2,
262 /// \ref ctfirstringfieldtype
263 BT_FIELD_TYPE_ID_STRING
= 3,
265 /// \ref ctfirstructfieldtype
266 BT_FIELD_TYPE_ID_STRUCT
= 4,
268 /// \ref ctfirarrayfieldtype
269 BT_FIELD_TYPE_ID_ARRAY
= 6,
271 /// \ref ctfirseqfieldtype
272 BT_FIELD_TYPE_ID_SEQUENCE
= 7,
274 /// \ref ctfirvarfieldtype
275 BT_FIELD_TYPE_ID_VARIANT
= 5,
277 /// Number of enumeration entries.
278 BT_FIELD_TYPE_ID_NR
= 8,
282 @brief Returns the type ID of the @ft \p field_type.
284 @param[in] field_type Field type of which to get the type ID.
285 @returns Type ID of \p field_type,
286 or #BT_FIELD_TYPE_ID_UNKNOWN on error.
288 @prenotnull{field_type}
289 @postrefcountsame{field_type}
291 @sa #bt_field_type_id: CTF IR field type ID.
292 @sa bt_field_type_is_integer(): Returns whether or not a given
293 field type is a @intft.
294 @sa bt_field_type_is_floating_point(): Returns whether or not a
295 given field type is a @floatft.
296 @sa bt_field_type_is_enumeration(): Returns whether or not a given
297 field type is a @enumft.
298 @sa bt_field_type_is_string(): Returns whether or not a given
299 field type is a @stringft.
300 @sa bt_field_type_is_structure(): Returns whether or not a given
301 field type is a @structft.
302 @sa bt_field_type_is_array(): Returns whether or not a given
303 field type is a @arrayft.
304 @sa bt_field_type_is_sequence(): Returns whether or not a given
305 field type is a @seqft.
306 @sa bt_field_type_is_variant(): Returns whether or not a given
307 field type is a @varft.
309 extern enum bt_field_type_id
bt_field_type_get_type_id(
310 struct bt_field_type
*field_type
);
313 @brief Returns whether or not the @ft \p field_type is a @intft.
315 @param[in] field_type Field type to check (can be \c NULL).
316 @returns #BT_TRUE if \p field_type is an integer field type,
317 or #BT_FALSE otherwise (including if \p field_type is
320 @prenotnull{field_type}
321 @postrefcountsame{field_type}
323 @sa bt_field_type_get_type_id(): Returns the type ID of a given
326 extern bt_bool
bt_field_type_is_integer(
327 struct bt_field_type
*field_type
);
330 @brief Returns whether or not the @ft \p field_type is a @floatft.
332 @param[in] field_type Field type to check (can be \c NULL).
333 @returns #BT_TRUE if \p field_type is a floating point
334 #BT_FALSE field type,
335 or 0 otherwise (including if \p field_type is
338 @postrefcountsame{field_type}
340 @sa bt_field_type_get_type_id(): Returns the type ID of a given
343 extern bt_bool
bt_field_type_is_floating_point(
344 struct bt_field_type
*field_type
);
347 @brief Returns whether or not the @ft \p field_type is a @enumft.
349 @param[in] field_type Field type to check (can be \c NULL).
350 @returns #BT_TRUE if \p field_type is an enumeration field type,
351 or #BT_FALSE otherwise (including if \p field_type is
354 @postrefcountsame{field_type}
356 @sa bt_field_type_get_type_id(): Returns the type ID of a given
359 extern bt_bool
bt_field_type_is_enumeration(
360 struct bt_field_type
*field_type
);
363 @brief Returns whether or not the @ft \p field_type is a @stringft.
365 @param[in] field_type Field type to check (can be \c NULL).
366 @returns #BT_TRUE if \p field_type is a string field type,
367 or #BT_FALSE otherwise (including if \p field_type is
370 @postrefcountsame{field_type}
372 @sa bt_field_type_get_type_id(): Returns the type ID of a given
375 extern bt_bool
bt_field_type_is_string(
376 struct bt_field_type
*field_type
);
379 @brief Returns whether or not the @ft \p field_type is a @structft.
381 @param[in] field_type Field type to check (can be \c NULL).
382 @returns #BT_TRUE if \p field_type is a structure field type,
383 or #BT_FALSE otherwise (including if \p field_type is
386 @postrefcountsame{field_type}
388 @sa bt_field_type_get_type_id(): Returns the type ID of a given
391 extern bt_bool
bt_field_type_is_structure(
392 struct bt_field_type
*field_type
);
395 @brief Returns whether or not the @ft \p field_type is a @arrayft.
397 @param[in] field_type Field type to check (can be \c NULL).
398 @returns #BT_TRUE if \p field_type is an array field type,
399 or #BT_FALSE otherwise (including if \p field_type is
402 @postrefcountsame{field_type}
404 @sa bt_field_type_get_type_id(): Returns the type ID of a given
407 extern bt_bool
bt_field_type_is_array(
408 struct bt_field_type
*field_type
);
411 @brief Returns whether or not the @ft \p field_type is a @seqft.
413 @param[in] field_type Field type to check (can be \c NULL).
414 @returns #BT_TRUE if \p field_type is a sequence field type,
415 or #BT_FALSE otherwise (including if \p field_type is
418 @postrefcountsame{field_type}
420 @sa bt_field_type_get_type_id(): Returns the type ID of a given
423 extern bt_bool
bt_field_type_is_sequence(
424 struct bt_field_type
*field_type
);
427 @brief Returns whether or not the @ft \p field_type is a @varft.
429 @param[in] field_type Field type to check (can be \c NULL).
430 @returns #BT_TRUE if \p field_type is a variant field type,
431 or #BT_FALSE otherwise (including if \p field_type is
434 @postrefcountsame{field_type}
436 @sa bt_field_type_get_type_id(): Returns the type ID of a given
439 extern bt_bool
bt_field_type_is_variant(
440 struct bt_field_type
*field_type
);
445 @name Common properties types and functions
450 @brief <a href="https://en.wikipedia.org/wiki/Endianness">Byte order</a>
454 /// Unknown, used for errors.
455 BT_BYTE_ORDER_UNKNOWN
= -1,
458 * Note that native, in the context of the CTF specification, is defined
459 * as "the byte order described in the trace" and does not mean that the
460 * host's endianness will be used.
462 /// Native (default) byte order.
463 BT_BYTE_ORDER_NATIVE
= 0,
466 Unspecified byte order; the initial native byte order of a
467 \link ctfirtraceclass CTF IR trace class\endlink.
469 BT_BYTE_ORDER_UNSPECIFIED
,
472 BT_BYTE_ORDER_LITTLE_ENDIAN
,
475 BT_BYTE_ORDER_BIG_ENDIAN
,
477 /// Network byte order (big-endian).
478 BT_BYTE_ORDER_NETWORK
,
482 @brief String encoding of a @ft.
484 enum bt_string_encoding
{
485 /// Unknown, used for errors.
486 BT_STRING_ENCODING_UNKNOWN
= -1,
489 BT_STRING_ENCODING_NONE
,
491 /// <a href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a>.
492 BT_STRING_ENCODING_UTF8
,
494 /// <a href="https://en.wikipedia.org/wiki/ASCII">ASCII</a>.
495 BT_STRING_ENCODING_ASCII
,
499 @brief Returns the alignment of the @fields described by
500 the @ft \p field_type.
502 @param[in] field_type Field type which describes the
503 fields of which to get the alignment.
504 @returns Alignment of the fields described by
505 \p field_type, or a negative value on error.
507 @prenotnull{field_type}
508 @postrefcountsame{field_type}
510 @sa bt_field_type_set_alignment(): Sets the alignment
511 of the fields described by a given field type.
513 extern int bt_field_type_get_alignment(
514 struct bt_field_type
*field_type
);
517 @brief Sets the alignment of the @fields described by the
518 @ft \p field_type to \p alignment.
520 \p alignment \em must be greater than 0 and a power of two.
522 @param[in] field_type Field type which describes the fields of
523 which to set the alignment.
524 @param[in] alignment Alignment of the fields described by
526 @returns 0 on success, or a negative value on error.
528 @prenotnull{field_type}
530 @pre \p alignment is greater than 0 and a power of two.
531 @postrefcountsame{field_type}
533 @sa bt_field_type_get_alignment(): Returns the alignment of the
534 fields described by a given field type.
536 extern int bt_field_type_set_alignment(struct bt_field_type
*field_type
,
537 unsigned int alignment
);
540 @brief Returns the byte order of the @fields described by
541 the @ft \p field_type.
543 You can only call this function if \p field_type is a @intft, a
544 @floatft, or a @enumft.
546 @param[in] field_type Field type which describes the
547 fields of which to get the byte order.
548 @returns Byte order of the fields described by
549 \p field_type, or #BT_BYTE_ORDER_UNKNOWN on
552 @prenotnull{field_type}
553 @pre \p field_type is a @intft, a @floatft, or a @enumft.
554 @postrefcountsame{field_type}
556 @sa bt_field_type_set_byte_order(): Sets the byte order
557 of the fields described by a given field type.
559 extern enum bt_byte_order
bt_field_type_get_byte_order(
560 struct bt_field_type
*field_type
);
563 @brief Sets the byte order of the @fields described by the
564 @ft \p field_type to \p byte_order.
566 If \p field_type is a compound field type, this function also
567 recursively sets the byte order of its children to \p byte_order.
569 @param[in] field_type Field type which describes the fields of
570 which to set the byte order.
571 @param[in] byte_order Alignment of the fields described by
573 @returns 0 on success, or a negative value on error.
575 @prenotnull{field_type}
577 @pre \p byte_order is #BT_BYTE_ORDER_NATIVE,
578 #BT_BYTE_ORDER_LITTLE_ENDIAN, #BT_BYTE_ORDER_BIG_ENDIAN,
579 or #BT_BYTE_ORDER_NETWORK.
580 @postrefcountsame{field_type}
582 @sa bt_field_type_get_byte_order(): Returns the byte order of the
583 fields described by a given field type.
585 extern int bt_field_type_set_byte_order(
586 struct bt_field_type
*field_type
,
587 enum bt_byte_order byte_order
);
592 @name Utility functions
597 @brief Returns whether or not the @ft \p field_type_a
598 is equivalent to the field type \p field_type_b.
600 You \em must use this function to compare two field types: it is not
601 safe to compare two pointer values directly, because, for internal
602 reasons, some parts of the Babeltrace system can copy user field types
603 and discard the original ones.
605 @param[in] field_type_a Field type to compare to \p field_type_b.
606 @param[in] field_type_b Field type to compare to \p field_type_a.
607 @returns 0 if \p field_type_a is equivalent to
608 \p field_type_b, 1 if they are not equivalent,
609 or a negative value on error.
611 @prenotnull{field_type_a}
612 @prenotnull{field_type_b}
613 @postrefcountsame{field_type_a}
614 @postrefcountsame{field_type_b}
616 extern int bt_field_type_compare(struct bt_field_type
*field_type_a
,
617 struct bt_field_type
*field_type_b
);
620 @brief Creates a \em deep copy of the @ft \p field_type.
622 You can copy a frozen field type: the resulting copy is
625 This function resets the tag field type of a copied @varft. The
626 automatic field resolving which some functions of the API perform
627 can set it again when the returned field type is used (learn more
628 in the detailed description of this module).
630 @param[in] field_type Field type to copy.
631 @returns Deep copy of \p field_type on success,
634 @prenotnull{field_type}
635 @postrefcountsame{field_type}
636 @postsuccessrefcountret1
637 @post <strong>On success</strong>, the returned field type is not frozen.
639 extern struct bt_field_type
*bt_field_type_copy(
640 struct bt_field_type
*field_type
);
647 @defgroup ctfirintfieldtype CTF IR integer field type
648 @ingroup ctfirfieldtypes
649 @brief CTF IR integer field type.
652 #include <babeltrace/ctf-ir/field-types.h>
655 A CTF IR <strong><em>integer field type</em></strong> is a field type that
656 you can use to create concrete @intfield objects.
658 You can create an integer field type
659 with bt_field_type_integer_create().
661 An integer field type has the following properties:
666 <th>Value at creation
671 <td>\b Alignment (bits) of the described integer fields
673 <td>bt_field_type_get_alignment()
674 <td>bt_field_type_set_alignment()
677 <td><strong>Byte order</strong> of the described integer fields
678 <td>#BT_BYTE_ORDER_NATIVE
679 <td>bt_field_type_get_byte_order()
680 <td>bt_field_type_set_byte_order()
683 <td><strong>Storage size</strong> (bits) of the described
685 <td>Specified at creation
686 <td>bt_field_type_integer_get_size()
687 <td>bt_field_type_integer_set_size()
690 <td><strong>Signedness</strong> of the described integer fields
692 <td>bt_field_type_integer_is_signed()
693 <td>bt_field_type_integer_set_is_signed()
696 <td><strong>Preferred display base</strong> of the described
698 <td>#BT_INTEGER_BASE_DECIMAL
699 <td>bt_field_type_integer_get_base()
700 <td>bt_field_type_integer_set_base()
703 <td>\b Encoding of the described integer fields
704 <td>#BT_STRING_ENCODING_NONE
705 <td>bt_field_type_integer_get_encoding()
706 <td>bt_field_type_integer_set_encoding()
710 \link ctfirclockclass CTF IR clock class\endlink</strong>
712 <td>bt_field_type_integer_get_mapped_clock_class()
713 <td>bt_field_type_integer_set_mapped_clock_class()
719 @sa \ref ctfirfieldtypesexamples_intfieldtype "Examples"
721 @addtogroup ctfirintfieldtype
726 @brief Preferred display base (radix) of a @intft.
728 enum bt_integer_base
{
729 /// Unknown, used for errors.
730 BT_INTEGER_BASE_UNKNOWN
= -1,
732 /// Unspecified by the tracer.
733 BT_INTEGER_BASE_UNSPECIFIED
= 0,
736 BT_INTEGER_BASE_BINARY
= 2,
739 BT_INTEGER_BASE_OCTAL
= 8,
742 BT_INTEGER_BASE_DECIMAL
= 10,
745 BT_INTEGER_BASE_HEXADECIMAL
= 16,
749 @brief Creates a default @intft with \p size bits as the storage size
750 of the @intfields it describes.
752 You can change the storage size of the integer fields described by
753 the created integer field type later with
754 bt_field_type_integer_set_size().
756 @param[in] size Storage size (bits) of the described integer fields.
757 @returns Created integer field type, or \c NULL on error.
759 @pre \p size is greater than 0 and lesser than or equal to 64.
760 @postsuccessrefcountret1
762 extern struct bt_field_type
*bt_field_type_integer_create(
766 @brief Returns the storage size, in bits, of the @intfields
767 described by the @intft \p int_field_type.
769 @param[in] int_field_type Integer field type which describes the
770 integer fields of which to get the
772 @returns Storage size (bits) of the integer
773 fields described by \p int_field_type,
774 or a negative value on error.
776 @prenotnull{int_field_type}
777 @preisintft{int_field_type}
778 @postrefcountsame{int_field_type}
780 @sa bt_field_type_integer_set_size(): Sets the storage size of the
781 integer fields described by a given integer field type.
783 extern int bt_field_type_integer_get_size(
784 struct bt_field_type
*int_field_type
);
787 @brief Sets the storage size, in bits, of the @intfields described by
788 the @intft \p int_field_type.
790 @param[in] int_field_type Integer field type which describes the
791 integer fields of which to set the
793 @param[in] size Storage size (bits) of the integer fields
794 described by \p int_field_type.
795 @returns 0 on success, or a negative value on error.
797 @prenotnull{int_field_type}
798 @preisintft{int_field_type}
799 @prehot{int_field_type}
800 @pre \p size is greater than 0 and lesser than or equal to 64.
801 @postrefcountsame{int_field_type}
803 @sa bt_field_type_integer_get_size(): Returns the storage size of
804 the integer fields described by a given integer field type.
806 extern int bt_field_type_integer_set_size(
807 struct bt_field_type
*int_field_type
, unsigned int size
);
810 @brief Returns whether or not the @intfields described by the @intft
811 \p int_field_type are signed.
813 @param[in] int_field_type Integer field type which describes the
814 integer fields of which to get the
816 @returns #BT_TRUE if the integer fields described by
817 \p int_field_type are signed, #BT_FALSE if they
820 @prenotnull{int_field_type}
821 @preisintft{int_field_type}
822 @postrefcountsame{int_field_type}
824 @sa bt_field_type_integer_set_is_signed(): Sets the signedness of the
825 integer fields described by a given integer field type.
827 extern bt_bool
bt_field_type_integer_is_signed(
828 struct bt_field_type
*int_field_type
);
831 @brief Sets whether or not the @intfields described by
832 the @intft \p int_field_type are signed.
834 @param[in] int_field_type Integer field type which describes the
835 integer fields of which to set the
837 @param[in] is_signed Signedness of the integer fields
838 described by \p int_field_type; #BT_FALSE means
839 \em unsigned, #BT_TRUE means \em signed.
840 @returns 0 on success, or a negative value on error.
842 @prenotnull{int_field_type}
843 @preisintft{int_field_type}
844 @prehot{int_field_type}
845 @postrefcountsame{int_field_type}
847 @sa bt_field_type_integer_is_signed(): Returns the signedness of
848 the integer fields described by a given integer field type.
850 extern int bt_field_type_integer_set_is_signed(
851 struct bt_field_type
*int_field_type
, bt_bool is_signed
);
854 @brief Returns the preferred display base (radix) of the @intfields
855 described by the @intft \p int_field_type.
857 @param[in] int_field_type Integer field type which describes the
858 integer fields of which to get the
859 preferred display base.
860 @returns Preferred display base of the integer
861 fields described by \p int_field_type,
862 #BT_INTEGER_BASE_UNSPECIFIED if
864 #BT_INTEGER_BASE_UNKNOWN on error.
866 @prenotnull{int_field_type}
867 @preisintft{int_field_type}
868 @postrefcountsame{int_field_type}
870 @sa bt_field_type_integer_set_base(): Sets the preferred display
871 base of the integer fields described by a given integer field
874 extern enum bt_integer_base
bt_field_type_integer_get_base(
875 struct bt_field_type
*int_field_type
);
878 @brief Sets the preferred display base (radix) of the @intfields
879 described by the @intft \p int_field_type to \p base.
881 @param[in] int_field_type Integer field type which describes the
882 integer fields of which to set the
883 preferred display base.
884 @param[in] base Preferred display base of the integer
885 fields described by \p int_field_type.
886 @returns 0 on success, or a negative value on error.
888 @prenotnull{int_field_type}
889 @preisintft{int_field_type}
890 @prehot{int_field_type}
891 @pre \p base is #BT_INTEGER_BASE_UNSPECIFIED,
892 #BT_INTEGER_BASE_BINARY, #BT_INTEGER_BASE_OCTAL,
893 #BT_INTEGER_BASE_DECIMAL, or #BT_INTEGER_BASE_HEXADECIMAL.
894 @postrefcountsame{int_field_type}
896 @sa bt_field_type_integer_get_base(): Returns the preferred display
897 base of the integer fields described by a given
900 extern int bt_field_type_integer_set_base(
901 struct bt_field_type
*int_field_type
,
902 enum bt_integer_base base
);
905 @brief Returns the encoding of the @intfields described by
906 the @intft \p int_field_type.
908 @param[in] int_field_type Integer field type which describes the
909 integer fields of which to get the
911 @returns Encoding of the integer
912 fields described by \p int_field_type,
913 or #BT_STRING_ENCODING_UNKNOWN on
916 @prenotnull{int_field_type}
917 @preisintft{int_field_type}
918 @postrefcountsame{int_field_type}
920 @sa bt_field_type_integer_set_encoding(): Sets the encoding
921 of the integer fields described by a given integer field type.
923 extern enum bt_string_encoding
bt_field_type_integer_get_encoding(
924 struct bt_field_type
*int_field_type
);
927 @brief Sets the encoding of the @intfields described by the @intft
928 \p int_field_type to \p encoding.
930 You can use this property, in CTF IR, to create "text" @arrayfts or
931 @seqfts. A text array field type is array field type with an unsigned,
932 8-bit integer field type having an encoding as its element field type.
934 @param[in] int_field_type Integer field type which describes the
935 integer fields of which to set the
937 @param[in] encoding Encoding of the integer
938 fields described by \p int_field_type.
939 @returns 0 on success, or a negative value on error.
941 @prenotnull{int_field_type}
942 @preisintft{int_field_type}
943 @prehot{int_field_type}
944 @pre \p encoding is #BT_STRING_ENCODING_NONE,
945 #BT_STRING_ENCODING_ASCII, or
946 #BT_STRING_ENCODING_UTF8.
947 @postrefcountsame{int_field_type}
949 @sa bt_field_type_integer_get_encoding(): Returns the encoding of
950 the integer fields described by a given integer field type.
952 extern int bt_field_type_integer_set_encoding(
953 struct bt_field_type
*int_field_type
,
954 enum bt_string_encoding encoding
);
956 extern struct bt_clock_class
*bt_field_type_integer_borrow_mapped_clock_class(
957 struct bt_field_type
*int_field_type
);
960 @brief Returns the \link ctfirclockclass CTF IR clock class\endlink
961 mapped to the @intft \p int_field_type.
963 The mapped clock class, if any, indicates the class of the clock which
964 an @intfield described by \p int_field_type should sample or update.
965 This mapped clock class is only indicative.
967 @param[in] int_field_type Integer field type of which to get the
969 @returns Mapped clock class of \p int_field_type,
970 or \c NULL if there's no mapped clock
973 @prenotnull{int_field_type}
974 @preisintft{int_field_type}
975 @postrefcountsame{int_field_type}
976 @postsuccessrefcountretinc
978 @sa bt_field_type_integer_set_mapped_clock_class(): Sets the mapped
979 clock class of a given integer field type.
982 struct bt_clock_class
*bt_field_type_integer_get_mapped_clock_class(
983 struct bt_field_type
*int_field_type
)
985 return bt_get(bt_field_type_integer_borrow_mapped_clock_class(
990 @brief Sets the \link ctfirclockclass CTF IR clock class\endlink mapped
991 to the @intft \p int_field_type to \p clock_class.
993 The mapped clock class, if any, indicates the class of the clock which
994 an integer field described by \p int_field_type should sample or update.
995 This mapped clock class is only indicative.
997 @param[in] int_field_type Integer field type of which to set the
999 @param[in] clock_class Mapped clock class of \p int_field_type.
1000 @returns 0 on success, or a negative value on error.
1002 @prenotnull{int_field_type}
1003 @prenotnull{clock_class}
1004 @preisintft{int_field_type}
1005 @prehot{int_field_type}
1006 @postrefcountsame{int_field_type}
1007 @postsuccessrefcountinc{clock_class}
1009 @sa bt_field_type_integer_get_mapped_clock_class(): Returns the mapped
1010 clock class of a given integer field type.
1012 extern int bt_field_type_integer_set_mapped_clock_class(
1013 struct bt_field_type
*int_field_type
,
1014 struct bt_clock_class
*clock_class
);
1019 @defgroup ctfirfloatfieldtype CTF IR floating point number field type
1020 @ingroup ctfirfieldtypes
1021 @brief CTF IR floating point number field type.
1024 #include <babeltrace/ctf-ir/field-types.h>
1027 A CTF IR <strong><em>floating point number field type</em></strong> is
1028 a field type that you can use to create concrete @floatfields.
1030 You can create a floating point number field type
1031 with bt_field_type_floating_point_create().
1033 A floating point number field type has the following properties:
1038 <th>Value at creation
1043 <td>\b Alignment (bits) of the described floating point
1046 <td>bt_field_type_get_alignment()
1047 <td>bt_field_type_set_alignment()
1050 <td><strong>Byte order</strong> of the described floating point
1052 <td>#BT_BYTE_ORDER_NATIVE
1053 <td>bt_field_type_get_byte_order()
1054 <td>bt_field_type_set_byte_order()
1057 <td><strong>Exponent storage size</strong> (bits) of the described
1058 floating point number fields
1060 <td>bt_field_type_floating_point_get_exponent_digits()
1061 <td>bt_field_type_floating_point_set_exponent_digits()
1064 <td><strong>Mantissa and sign storage size</strong> (bits) of the
1065 described floating point number fields
1066 <td>24 (23-bit mantissa, 1-bit sign)
1067 <td>bt_field_type_floating_point_get_mantissa_digits()
1068 <td>bt_field_type_floating_point_set_mantissa_digits()
1074 @sa \ref ctfirfieldtypesexamples_floatfieldtype "Examples"
1076 @addtogroup ctfirfloatfieldtype
1081 @brief Creates a default @floatft.
1083 @returns Created floating point number field type,
1084 or \c NULL on error.
1086 @postsuccessrefcountret1
1088 extern struct bt_field_type
*bt_field_type_floating_point_create(void);
1091 @brief Returns the exponent storage size of the @floatfields
1092 described by the @floatft \p float_field_type.
1094 @param[in] float_field_type Floating point number field type which
1095 describes the floating point number
1096 fields of which to get the exponent
1098 @returns Exponent storage size of the
1099 floating point number fields
1100 described by \p float_field_type,
1101 or a negative value on error.
1103 @prenotnull{float_field_type}
1104 @preisfloatft{float_field_type}
1105 @postrefcountsame{float_field_type}
1107 @sa bt_field_type_floating_point_set_exponent_digits(): Sets the
1108 exponent storage size of the floating point number fields
1109 described by a given floating point number field type.
1111 extern int bt_field_type_floating_point_get_exponent_digits(
1112 struct bt_field_type
*float_field_type
);
1115 @brief Sets the exponent storage size of the @floatfields described by
1116 the @floatft \p float_field_type to \p exponent_size.
1118 As of Babeltrace \btversion, \p exponent_size can only be 8 or 11.
1120 @param[in] float_field_type Floating point number field type which
1121 describes the floating point number
1122 fields of which to set the exponent
1124 @param[in] exponent_size Exponent storage size of the floating
1125 point number fields described by \p
1127 @returns 0 on success, or a negative value on error.
1129 @prenotnull{float_field_type}
1130 @preisfloatft{float_field_type}
1131 @prehot{float_field_type}
1132 @pre \p exponent_size is 8 or 11.
1133 @postrefcountsame{float_field_type}
1135 @sa bt_field_type_floating_point_get_exponent_digits(): Returns the
1136 exponent storage size of the floating point number fields
1137 described by a given floating point number field type.
1139 extern int bt_field_type_floating_point_set_exponent_digits(
1140 struct bt_field_type
*float_field_type
,
1141 unsigned int exponent_size
);
1144 @brief Returns the mantissa and sign storage size of the @floatfields
1145 described by the @floatft \p float_field_type.
1147 On success, the returned value is the sum of the mantissa \em and
1150 @param[in] float_field_type Floating point number field type which
1151 describes the floating point number
1152 fields of which to get the mantissa and
1154 @returns Mantissa and sign storage size of the
1155 floating point number fields
1156 described by \p float_field_type,
1157 or a negative value on error.
1159 @prenotnull{float_field_type}
1160 @preisfloatft{float_field_type}
1161 @postrefcountsame{float_field_type}
1163 @sa bt_field_type_floating_point_set_mantissa_digits(): Sets the
1164 mantissa and size storage size of the floating point number
1165 fields described by a given floating point number field type.
1167 extern int bt_field_type_floating_point_get_mantissa_digits(
1168 struct bt_field_type
*float_field_type
);
1171 @brief Sets the mantissa and sign storage size of the @floatfields
1172 described by the @floatft \p float_field_type to \p
1175 As of Babeltrace \btversion, \p mantissa_sign_size can only be 24 or 53.
1177 @param[in] float_field_type Floating point number field type which
1178 describes the floating point number
1179 fields of which to set the mantissa and
1181 @param[in] mantissa_sign_size Mantissa and sign storage size of the
1182 floating point number fields described
1183 by \p float_field_type.
1184 @returns 0 on success, or a negative value on error.
1186 @prenotnull{float_field_type}
1187 @preisfloatft{float_field_type}
1188 @prehot{float_field_type}
1189 @pre \p mantissa_sign_size is 24 or 53.
1190 @postrefcountsame{float_field_type}
1192 @sa bt_field_type_floating_point_get_mantissa_digits(): Returns the
1193 mantissa and sign storage size of the floating point number
1194 fields described by a given floating point number field type.
1196 extern int bt_field_type_floating_point_set_mantissa_digits(
1197 struct bt_field_type
*float_field_type
,
1198 unsigned int mantissa_sign_size
);
1203 @defgroup ctfirenumfieldtype CTF IR enumeration field type
1204 @ingroup ctfirfieldtypes
1205 @brief CTF IR enumeration field type.
1208 #include <babeltrace/ctf-ir/field-types.h>
1211 A CTF IR <strong><em>enumeration field type</em></strong> is
1212 a field type that you can use to create concrete @enumfields.
1214 You can create an enumeration field type with
1215 bt_field_type_enumeration_create(). This function needs a @intft
1216 which represents the storage field type of the created enumeration field
1217 type. In other words, an enumeration field type wraps an integer field
1218 type and adds label-value mappings to it.
1220 An enumeration mapping has:
1222 - A <strong>name</strong>.
1223 - A <strong>range of values</strong> given by a beginning and an ending
1224 value, both included in the range.
1226 You can add a mapping to an enumeration field type with
1227 bt_field_type_enumeration_signed_add_mapping() or
1228 bt_field_type_enumeration_unsigned_add_mapping(), depending on the
1229 signedness of the wrapped @intft.
1231 You can find mappings by name or by value with the following find
1234 - bt_field_type_enumeration_find_mappings_by_name(): Finds the
1235 mappings with a given name.
1236 - bt_field_type_enumeration_unsigned_find_mappings_by_value():
1237 Finds the mappings which contain a given unsigned value in their
1239 - bt_field_type_enumeration_signed_find_mappings_by_value():
1240 Finds the mappings which contain a given signed value in their range.
1242 Those functions return a @enumftiter on the result set of the find
1245 Many mappings can share the same name, and the ranges of a given
1246 enumeration field type are allowed to overlap. For example,
1247 this is a valid set of mappings:
1256 The following set of mappings is also valid:
1265 Here, the range of the second \c APPLE mapping overlaps the range of
1266 the \c CHERRY mapping.
1268 @sa ctfirenumftmappingiter
1272 @addtogroup ctfirenumfieldtype
1277 @brief Creates a default @enumft wrapping the @intft \p int_field_type.
1279 @param[in] int_field_type Integer field type wrapped by the
1280 created enumeration field type.
1281 @returns Created enumeration field type,
1282 or \c NULL on error.
1284 @prenotnull{int_field_type}
1285 @preisintft{int_field_type}
1286 @postsuccessrefcountinc{int_field_type}
1287 @postsuccessrefcountret1
1289 extern struct bt_field_type
*bt_field_type_enumeration_create(
1290 struct bt_field_type
*int_field_type
);
1293 struct bt_field_type
*bt_field_type_enumeration_borrow_container_field_type(
1294 struct bt_field_type
*enum_field_type
);
1297 @brief Returns the @intft wrapped by the @enumft \p enum_field_type.
1299 @param[in] enum_field_type Enumeration field type of which to get
1300 the wrapped integer field type.
1301 @returns Integer field type wrapped by
1302 \p enum_field_type, or \c NULL on
1305 @prenotnull{enum_field_type}
1306 @preisenumft{enum_field_type}
1307 @postrefcountsame{enum_field_type}
1308 @postsuccessrefcountretinc
1311 struct bt_field_type
*bt_field_type_enumeration_get_container_field_type(
1312 struct bt_field_type
*enum_field_type
)
1314 return bt_get(bt_field_type_enumeration_borrow_container_field_type(
1319 @brief Returns the number of mappings contained in the
1320 @enumft \p enum_field_type.
1322 @param[in] enum_field_type Enumeration field type of which to get
1323 the number of contained mappings.
1324 @returns Number of mappings contained in
1325 \p enum_field_type, or a negative
1328 @prenotnull{enum_field_type}
1329 @preisenumft{enum_field_type}
1330 @postrefcountsame{enum_field_type}
1332 extern int64_t bt_field_type_enumeration_get_mapping_count(
1333 struct bt_field_type
*enum_field_type
);
1336 @brief Returns the signed mapping of the @enumft
1337 \p enum_field_type at index \p index.
1339 The @intft wrapped by \p enum_field_type, as returned by
1340 bt_field_type_enumeration_get_container_field_type(), must be \b signed
1341 to use this function.
1343 On success, \p enum_field_type remains the sole owner of \p *name.
1345 @param[in] enum_field_type Enumeration field type of which to get
1346 the mapping at index \p index.
1347 @param[in] index Index of the mapping to get from
1349 @param[out] name Returned name of the mapping at index
1351 @param[out] range_begin Returned beginning of the range
1352 (included) of the mapping at index \p
1354 @param[out] range_end Returned end of the range (included) of
1355 the mapping at index \p index.
1356 @returns 0 on success, or a negative value on error.
1358 @prenotnull{enum_field_type}
1360 @prenotnull{range_begin}
1361 @prenotnull{range_end}
1362 @preisenumft{enum_field_type}
1363 @pre The wrapped @intft of \p enum_field_type is signed.
1364 @pre \p index is lesser than the number of mappings contained in the
1365 enumeration field type \p enum_field_type (see
1366 bt_field_type_enumeration_get_mapping_count()).
1367 @postrefcountsame{enum_field_type}
1369 @sa bt_field_type_enumeration_unsigned_get_mapping_by_index(): Returns the
1370 unsigned mapping contained by a given enumeration field type
1373 extern int bt_field_type_enumeration_signed_get_mapping_by_index(
1374 struct bt_field_type
*enum_field_type
, uint64_t index
,
1375 const char **name
, int64_t *range_begin
, int64_t *range_end
);
1378 @brief Returns the unsigned mapping of the @enumft
1379 \p enum_field_type at index \p index.
1381 The @intft wrapped by \p enum_field_type, as returned by
1382 bt_field_type_enumeration_get_container_field_type(), must be
1383 \b unsigned to use this function.
1385 On success, \p enum_field_type remains the sole owner of \p *name.
1387 @param[in] enum_field_type Enumeration field type of which to get
1388 the mapping at index \p index.
1389 @param[in] index Index of the mapping to get from
1391 @param[out] name Returned name of the mapping at index
1393 @param[out] range_begin Returned beginning of the range
1394 (included) of the mapping at index \p
1396 @param[out] range_end Returned end of the range (included) of
1397 the mapping at index \p index.
1398 @returns 0 on success, or a negative value on error.
1400 @prenotnull{enum_field_type}
1402 @prenotnull{range_begin}
1403 @prenotnull{range_end}
1404 @preisenumft{enum_field_type}
1405 @pre The wrapped @intft of \p enum_field_type is unsigned.
1406 @pre \p index is lesser than the number of mappings contained in the
1407 enumeration field type \p enum_field_type (see
1408 bt_field_type_enumeration_get_mapping_count()).
1409 @postrefcountsame{enum_field_type}
1411 @sa bt_field_type_enumeration_signed_get_mapping_by_index(): Returns the
1412 signed mapping contained by a given enumeration field type
1415 extern int bt_field_type_enumeration_unsigned_get_mapping_by_index(
1416 struct bt_field_type
*enum_field_type
, uint64_t index
,
1417 const char **name
, uint64_t *range_begin
,
1418 uint64_t *range_end
);
1421 @brief Finds the mappings of the @enumft \p enum_field_type which
1424 This function returns an iterator on the result set of this find
1425 operation. See \ref ctfirenumftmappingiter for more details.
1427 @param[in] enum_field_type Enumeration field type of which to find
1428 the mappings named \p name.
1429 @param[in] name Name of the mappings to find in
1431 @returns @enumftiter on the set of mappings named
1432 \p name in \p enum_field_type, or
1433 \c NULL if no mappings were found or
1436 @prenotnull{enum_field_type}
1438 @preisenumft{enum_field_type}
1439 @postrefcountsame{enum_field_type}
1440 @postsuccessrefcountret1
1441 @post <strong>On success</strong>, the returned @enumftiter can iterate
1442 on at least one mapping.
1444 @sa bt_field_type_enumeration_signed_find_mappings_by_value(): Finds
1445 the mappings of a given enumeration field type which contain
1446 a given signed value in their range.
1447 @sa bt_field_type_enumeration_unsigned_find_mappings_by_value(): Finds
1448 the mappings of a given enumeration field type which contain
1449 a given unsigned value in their range.
1451 extern struct bt_field_type_enumeration_mapping_iterator
*
1452 bt_field_type_enumeration_find_mappings_by_name(
1453 struct bt_field_type
*enum_field_type
,
1457 @brief Finds the mappings of the @enumft \p enum_field_type which
1458 contain the signed value \p value in their range.
1460 This function returns an iterator on the result set of this find
1461 operation. See \ref ctfirenumftmappingiter for more details.
1463 @param[in] enum_field_type Enumeration field type of which to find
1464 the mappings which contain \p value.
1465 @param[in] value Value to find in the ranges of the
1466 mappings of \p enum_field_type.
1467 @returns @enumftiter on the set of mappings of
1468 \p enum_field_type which contain
1469 \p value in their range, or \c NULL if
1470 no mappings were found or on error.
1472 @prenotnull{enum_field_type}
1473 @preisenumft{enum_field_type}
1474 @postrefcountsame{enum_field_type}
1475 @postsuccessrefcountret1
1476 @post <strong>On success</strong>, the returned @enumftiter can iterate
1477 on at least one mapping.
1479 @sa bt_field_type_enumeration_find_mappings_by_name(): Finds the
1480 mappings of a given enumeration field type which have a given
1482 @sa bt_field_type_enumeration_unsigned_find_mappings_by_value(): Finds
1483 the mappings of a given enumeration field type which contain
1484 a given unsigned value in their range.
1486 extern struct bt_field_type_enumeration_mapping_iterator
*
1487 bt_field_type_enumeration_signed_find_mappings_by_value(
1488 struct bt_field_type
*enum_field_type
,
1492 @brief Finds the mappings of the @enumft \p enum_field_type which
1493 contain the unsigned value \p value in their range.
1495 This function returns an iterator on the result set of this find
1496 operation. See \ref ctfirenumftmappingiter for more details.
1498 @param[in] enum_field_type Enumeration field type of which to find
1499 the mappings which contain \p value.
1500 @param[in] value Value to find in the ranges of the
1501 mappings of \p enum_field_type.
1502 @returns @enumftiter on the set of mappings of
1503 \p enum_field_type which contain
1504 \p value in their range, or \c NULL
1505 if no mappings were found or
1508 @prenotnull{enum_field_type}
1509 @preisenumft{enum_field_type}
1510 @postrefcountsame{enum_field_type}
1511 @postsuccessrefcountret1
1512 @post <strong>On success</strong>, the returned @enumftiter can iterate
1513 on at least one mapping.
1515 @sa bt_field_type_enumeration_find_mappings_by_name(): Finds the
1516 mappings of a given enumeration field type which have a given
1518 @sa bt_field_type_enumeration_signed_find_mappings_by_value(): Finds
1519 the mappings of a given enumeration field type which contain
1520 a given unsigned value in their range.
1522 extern struct bt_field_type_enumeration_mapping_iterator
*
1523 bt_field_type_enumeration_unsigned_find_mappings_by_value(
1524 struct bt_field_type
*enum_field_type
,
1528 @brief Adds a mapping to the @enumft \p enum_field_type which maps the
1529 name \p name to the signed range \p range_begin (included) to
1530 \p range_end (included).
1532 Make \p range_begin and \p range_end the same value to add a mapping
1535 The @intft wrapped by \p enum_field_type, as returned by
1536 bt_field_type_enumeration_get_container_field_type(), must be
1537 \b signed to use this function.
1539 A mapping in \p enum_field_type can exist with the name \p name.
1541 @param[in] enum_field_type Enumeration field type to which to add
1543 @param[in] name Name of the mapping to add (copied
1545 @param[in] range_begin Beginning of the range of the mapping
1547 @param[in] range_end End of the range of the mapping
1549 @returns 0 on success, or a negative value on error.
1551 @prenotnull{enum_field_type}
1553 @prehot{enum_field_type}
1554 @preisenumft{enum_field_type}
1555 @pre The wrapped @intft of \p enum_field_type is signed.
1556 @pre \p range_end is greater than or equal to \p range_begin.
1557 @postrefcountsame{enum_field_type}
1559 @sa bt_field_type_enumeration_unsigned_add_mapping(): Adds an
1560 unsigned mapping to a given enumeration field type.
1562 extern int bt_field_type_enumeration_signed_add_mapping(
1563 struct bt_field_type
*enum_field_type
, const char *name
,
1564 int64_t range_begin
, int64_t range_end
);
1567 @brief Adds a mapping to the @enumft \p enum_field_type which maps
1568 the name \p name to the unsigned
1569 range \p range_begin (included) to \p range_end (included).
1571 Make \p range_begin and \p range_end the same value to add a mapping
1574 The @intft wrapped by \p enum_field_type, as returned by
1575 bt_field_type_enumeration_get_container_field_type(), must be
1576 \b unsigned to use this function.
1578 A mapping in \p enum_field_type can exist with the name \p name.
1580 @param[in] enum_field_type Enumeration field type to which to add
1582 @param[in] name Name of the mapping to add (copied
1584 @param[in] range_begin Beginning of the range of the mapping
1586 @param[in] range_end End of the range of the mapping
1588 @returns 0 on success, or a negative value on error.
1590 @prenotnull{enum_field_type}
1592 @prehot{enum_field_type}
1593 @preisenumft{enum_field_type}
1594 @pre The wrapped @intft of \p enum_field_type is unsigned.
1595 @pre \p range_end is greater than or equal to \p range_begin.
1596 @postrefcountsame{enum_field_type}
1598 @sa bt_field_type_enumeration_signed_add_mapping(): Adds a signed
1599 mapping to a given enumeration field type.
1601 extern int bt_field_type_enumeration_unsigned_add_mapping(
1602 struct bt_field_type
*enum_field_type
, const char *name
,
1603 uint64_t range_begin
, uint64_t range_end
);
1608 @defgroup ctfirenumftmappingiter CTF IR enumeration field type mapping iterator
1609 @ingroup ctfirenumfieldtype
1610 @brief CTF IR enumeration field type mapping iterator.
1613 #include <babeltrace/ctf-ir/field-types.h>
1616 A CTF IR <strong><em>enumeration field type mapping
1617 iterator</em></strong> is an iterator on @enumft mappings.
1619 You can get an enumeration mapping iterator from one of the following
1622 - Find operations of an @enumft object:
1623 - bt_field_type_enumeration_find_mappings_by_name(): Finds the
1624 mappings with a given name.
1625 - bt_field_type_enumeration_unsigned_find_mappings_by_value():
1626 Finds the mappings which contain a given unsigned value in their
1628 - bt_field_type_enumeration_signed_find_mappings_by_value():
1629 Finds the mappings which contain a given signed value in their range.
1630 - bt_field_enumeration_get_mappings(): Finds the mappings in the
1631 @enumft of an @enumfield containing its current integral value in
1634 Those functions guarantee that the returned iterator can iterate on
1635 at least one mapping. Otherwise, they return \c NULL.
1637 You can get the name and the range of a mapping iterator's current
1639 bt_field_type_enumeration_mapping_iterator_signed_get()
1641 bt_field_type_enumeration_mapping_iterator_unsigned_get(),
1642 depending on the signedness of the @intft wrapped by the
1643 @enumft. If you only need the name of the current mapping, you can
1644 use any of the two functions and set the \p range_begin and \p range_end
1645 parameters to \c NULL.
1647 You can advance an enumeration field type mapping iterator to the next
1649 bt_field_type_enumeration_mapping_iterator_next(). This
1650 function returns a negative value when you reach the end of the
1653 As with any Babeltrace object, CTF IR enumeration field type mapping
1654 iterator objects have <a
1655 href="https://en.wikipedia.org/wiki/Reference_counting">reference
1656 counts</a>. See \ref refs to learn more about the reference counting
1657 management of Babeltrace objects.
1659 @sa ctfirenumfieldtype
1661 @addtogroup ctfirenumftmappingiter
1666 @struct bt_field_type_enumeration_mapping_iterator
1667 @brief A CTF IR enumeration field type mapping iterator.
1668 @sa ctfirenumftmappingiter
1672 @brief Returns the name and the range of the current (signed) mapping
1673 of the @enumftiter \p iter.
1675 If one of \p range_begin or \p range_end is not \c NULL, the @intft
1676 wrapped by the @enumft from which \p iter was obtained, as returned by
1677 bt_field_type_enumeration_get_container_field_type(), must be
1678 \b signed to use this function. Otherwise, if you only need to get the
1679 name of the current mapping, set \p range_begin and \p range_end to
1682 On success, if \p name is not \c NULL, \p *name remains valid as long
1683 as \p iter exists and
1684 bt_field_type_enumeration_mapping_iterator_next() is
1685 \em not called on \p iter.
1687 @param[in] iter Enumeration field type mapping iterator
1688 of which to get the range of the current
1690 @param[out] name Returned name of the current mapping of
1691 \p iter (can be \c NULL to ignore).
1692 @param[out] range_begin Returned beginning of the range
1693 (included) of the current mapping of
1694 \p iter (can be \c NULL to ignore).
1695 @param[out] range_end Returned end of the range
1696 (included) of the current mapping of
1697 \p iter (can be \c NULL to ignore).
1698 @returns 0 on success, or a negative value on error.
1701 @postrefcountsame{iter}
1703 @sa bt_field_type_enumeration_mapping_iterator_unsigned_get():
1704 Returns the name and the unsigned range of the current mapping
1705 of a given enumeration field type mapping iterator.
1707 extern int bt_field_type_enumeration_mapping_iterator_signed_get(
1708 struct bt_field_type_enumeration_mapping_iterator
*iter
,
1709 const char **name
, int64_t *range_begin
, int64_t *range_end
);
1712 @brief Returns the name and the range of the current (unsigned) mapping
1713 of the @enumftiter \p iter.
1715 If one of \p range_begin or \p range_end is not \c NULL, the @intft
1716 wrapped by the @enumft from which \p iter was obtained, as returned by
1717 bt_field_type_enumeration_get_container_field_type(), must be
1718 \b unsigned to use this function. Otherwise, if you only need to get the
1719 name of the current mapping, set \p range_begin and \p range_end to
1722 On success, if \p name is not \c NULL, \p *name remains valid as long
1723 as \p iter exists and
1724 bt_field_type_enumeration_mapping_iterator_next() is
1725 \em not called on \p iter.
1727 @param[in] iter Enumeration field type mapping iterator
1728 of which to get the range of the current
1730 @param[out] name Returned name of the current mapping of
1731 \p iter (can be \c NULL to ignore).
1732 @param[out] range_begin Returned beginning of the range
1733 (included) of the current mapping of
1734 \p iter (can be \c NULL to ignore).
1735 @param[out] range_end Returned end of the range
1736 (included) of the current mapping of
1737 \p iter (can be \c NULL to ignore).
1738 @returns 0 on success, or a negative value on error.
1741 @postrefcountsame{iter}
1744 bt_field_type_enumeration_mapping_iterator_signed_get():
1745 Returns the name and the signed range of the current mapping of
1746 a given enumeration field type mapping iterator.
1748 extern int bt_field_type_enumeration_mapping_iterator_unsigned_get(
1749 struct bt_field_type_enumeration_mapping_iterator
*iter
,
1750 const char **name
, uint64_t *range_begin
, uint64_t *range_end
);
1753 @brief Advances the @enumftiter \p iter to the next mapping.
1755 @param[in] iter Enumeration field type mapping iterator to
1757 @returns 0 on success, or a negative value on error or
1758 when you reach the end of the set.
1761 @postrefcountsame{iter}
1763 extern int bt_field_type_enumeration_mapping_iterator_next(
1764 struct bt_field_type_enumeration_mapping_iterator
*iter
);
1769 @defgroup ctfirstringfieldtype CTF IR string field type
1770 @ingroup ctfirfieldtypes
1771 @brief CTF IR string field type.
1774 #include <babeltrace/ctf-ir/field-types.h>
1777 A CTF IR <strong><em>string field type</em></strong> is a field type that
1778 you can use to create concrete @stringfields.
1780 You can create a string field type
1781 with bt_field_type_string_create().
1783 A string field type has only one property: the \b encoding of its
1784 described @stringfields. By default, the encoding of the string fields
1785 described by a string field type is #BT_STRING_ENCODING_UTF8. You
1786 can set the encoding of the string fields described by a string field
1787 type with bt_field_type_string_set_encoding().
1789 @sa ctfirstringfield
1792 @addtogroup ctfirstringfieldtype
1797 @brief Creates a default @stringft.
1799 @returns Created string field type, or \c NULL on error.
1801 @postsuccessrefcountret1
1803 extern struct bt_field_type
*bt_field_type_string_create(void);
1806 @brief Returns the encoding of the @stringfields described by
1807 the @stringft \p string_field_type.
1809 @param[in] string_field_type String field type which describes the
1810 string fields of which to get the
1812 @returns Encoding of the string
1813 fields described by \p string_field_type,
1814 or #BT_STRING_ENCODING_UNKNOWN on
1817 @prenotnull{string_field_type}
1818 @preisstringft{string_field_type}
1819 @postrefcountsame{string_field_type}
1821 @sa bt_field_type_string_set_encoding(): Sets the encoding
1822 of the string fields described by a given string field type.
1824 extern enum bt_string_encoding
bt_field_type_string_get_encoding(
1825 struct bt_field_type
*string_field_type
);
1828 @brief Sets the encoding of the @stringfields described by the
1829 @stringft \p string_field_type to \p encoding.
1831 @param[in] string_field_type String field type which describes the
1832 string fields of which to set the
1834 @param[in] encoding Encoding of the string fields described
1835 by \p string_field_type.
1836 @returns 0 on success, or a negative value on error.
1838 @prenotnull{string_field_type}
1839 @preisstringft{string_field_type}
1840 @prehot{string_field_type}
1841 @pre \p encoding is #BT_STRING_ENCODING_ASCII or
1842 #BT_STRING_ENCODING_UTF8.
1843 @postrefcountsame{string_field_type}
1845 @sa bt_field_type_string_get_encoding(): Returns the encoding of
1846 the string fields described by a given string field type.
1848 extern int bt_field_type_string_set_encoding(
1849 struct bt_field_type
*string_field_type
,
1850 enum bt_string_encoding encoding
);
1855 @defgroup ctfirstructfieldtype CTF IR structure field type
1856 @ingroup ctfirfieldtypes
1857 @brief CTF IR structure field type.
1860 #include <babeltrace/ctf-ir/field-types.h>
1863 A CTF IR <strong><em>structure field type</em></strong> is
1864 a field type that you can use to create concrete @structfields.
1866 You can create a structure field type
1867 with bt_field_type_structure_create(). This function creates
1868 an empty structure field type, with no fields.
1870 You can add a field to a structure field type with
1871 bt_field_type_structure_add_field(). Two fields in a structure
1872 field type cannot have the same name.
1874 You can set the \em minimum alignment of the structure fields described
1875 by a structure field type with the common
1876 bt_field_type_set_alignment() function. The \em effective alignment
1877 of the structure fields described by a structure field type, as per
1878 <a href="http://diamon.org/ctf/">CTF</a>, is the \em maximum value amongst
1879 the effective alignments of all its fields. Note that the effective
1880 alignment of @varfields is always 1.
1882 You can set the byte order of <em>all the contained fields</em>,
1883 recursively, of a structure field type with the common
1884 bt_field_type_set_byte_order() function.
1886 @sa ctfirstructfield
1889 @addtogroup ctfirstructfieldtype
1894 @brief Creates a default, empty @structft.
1896 @returns Created structure field type,
1897 or \c NULL on error.
1899 @postsuccessrefcountret1
1901 extern struct bt_field_type
*bt_field_type_structure_create(void);
1904 @brief Returns the number of fields contained in the
1905 @structft \p struct_field_type.
1907 @param[in] struct_field_type Structure field type of which to get
1908 the number of contained fields.
1909 @returns Number of fields contained in
1910 \p struct_field_type, or a negative
1913 @prenotnull{struct_field_type}
1914 @preisstructft{struct_field_type}
1915 @postrefcountsame{struct_field_type}
1917 extern int64_t bt_field_type_structure_get_field_count(
1918 struct bt_field_type
*struct_field_type
);
1920 extern int bt_field_type_structure_borrow_field_by_index(
1921 struct bt_field_type
*struct_field_type
,
1922 const char **field_name
, struct bt_field_type
**field_type
,
1926 @brief Returns the field of the @structft \p struct_field_type
1929 On success, the field's type is placed in \p *field_type if
1930 \p field_type is not \c NULL. The field's name is placed in
1931 \p *field_name if \p field_name is not \c NULL.
1932 \p struct_field_type remains the sole owner of \p *field_name.
1934 @param[in] struct_field_type Structure field type of which to get
1935 the field at index \p index.
1936 @param[out] field_name Returned name of the field at index
1937 \p index (can be \c NULL).
1938 @param[out] field_type Returned field type of the field
1939 at index \p index (can be \c NULL).
1940 @param[in] index Index of the field to get from
1941 \p struct_field_type.
1942 @returns 0 on success, or a negative value on error.
1944 @prenotnull{struct_field_type}
1945 @preisstructft{struct_field_type}
1946 @pre \p index is lesser than the number of fields contained in the
1947 structure field type \p struct_field_type (see
1948 bt_field_type_structure_get_field_count()).
1949 @postrefcountsame{struct_field_type}
1950 @post <strong>On success</strong>, the returned field's type is placed
1951 in \p *field_type and its reference count is incremented.
1953 @sa bt_field_type_structure_get_field_type_by_name(): Finds a
1954 structure field type's field by name.
1957 int bt_field_type_structure_get_field_by_index(
1958 struct bt_field_type
*struct_field_type
,
1959 const char **field_name
, struct bt_field_type
**field_type
,
1962 int ret
= bt_field_type_structure_borrow_field_by_index(
1963 struct_field_type
, field_name
, field_type
, index
);
1965 if (ret
== 0 && field_type
) {
1966 bt_get(*field_type
);
1973 struct bt_field_type
*bt_field_type_structure_borrow_field_type_by_name(
1974 struct bt_field_type
*struct_field_type
,
1975 const char *field_name
);
1978 @brief Returns the type of the field named \p field_name found in
1979 the @structft \p struct_field_type.
1981 @param[in] struct_field_type Structure field type of which to get
1983 @param[in] field_name Name of the field to find.
1984 @returns Type of the field named \p field_name in
1985 \p struct_field_type, or
1988 @prenotnull{struct_field_type}
1989 @prenotnull{field_name}
1990 @preisstructft{struct_field_type}
1991 @postrefcountsame{struct_field_type}
1992 @postsuccessrefcountretinc
1994 @sa bt_field_type_structure_get_field_by_index(): Finds a
1995 structure field type's field by index.
1998 struct bt_field_type
*bt_field_type_structure_get_field_type_by_name(
1999 struct bt_field_type
*struct_field_type
,
2000 const char *field_name
)
2002 return bt_get(bt_field_type_structure_borrow_field_type_by_name(
2003 struct_field_type
, field_name
));
2007 @brief Adds a field named \p field_name with the @ft
2008 \p field_type to the @structft \p struct_field_type.
2010 On success, \p field_type becomes the child of \p struct_field_type.
2012 This function adds the new field after the current last field of
2013 \p struct_field_type (append mode).
2015 You \em cannot add a field named \p field_name if there's already a
2016 field named \p field_name in \p struct_field_type.
2018 @param[in] struct_field_type Structure field type to which to add
2020 @param[in] field_type Field type of the field to add to
2021 \p struct_field_type.
2022 @param[in] field_name Name of the field to add to
2023 \p struct_field_type
2024 (copied on success).
2025 @returns 0 on success, or a negative value on error.
2027 @prenotnull{struct_field_type}
2028 @prenotnull{field_type}
2029 @prenotnull{field_name}
2030 @preisstructft{struct_field_type}
2031 @pre \p field_type is not and does not contain \p struct_field_type,
2032 recursively, as a field's type.
2033 @prehot{struct_field_type}
2034 @postrefcountsame{struct_field_type}
2035 @postsuccessrefcountinc{field_type}
2037 extern int bt_field_type_structure_add_field(
2038 struct bt_field_type
*struct_field_type
,
2039 struct bt_field_type
*field_type
,
2040 const char *field_name
);
2045 @defgroup ctfirarrayfieldtype CTF IR array field type
2046 @ingroup ctfirfieldtypes
2047 @brief CTF IR array field type.
2050 #include <babeltrace/ctf-ir/field-types.h>
2053 A CTF IR <strong><em>array field type</em></strong> is a field type that
2054 you can use to create concrete @arrayfields.
2056 You can create an array field type
2057 with bt_field_type_array_create(). This function needs
2058 the @ft of the fields contained by the array fields described by the
2059 array field type to create.
2064 @addtogroup ctfirarrayfieldtype
2069 @brief Creates a default @arrayft with
2070 \p element_field_type as the field type of the fields contained
2071 in its described @arrayfields of length \p length.
2073 @param[in] element_field_type Field type of the fields contained in
2074 the array fields described by the
2075 created array field type.
2076 @param[in] length Length of the array fields described by
2077 the created array field type.
2078 @returns Created array field type, or
2081 @prenotnull{element_field_type}
2082 @postsuccessrefcountinc{element_field_type}
2083 @postsuccessrefcountret1
2085 extern struct bt_field_type
*bt_field_type_array_create(
2086 struct bt_field_type
*element_field_type
,
2087 unsigned int length
);
2089 extern struct bt_field_type
*bt_field_type_array_borrow_element_field_type(
2090 struct bt_field_type
*array_field_type
);
2093 @brief Returns the @ft of the @fields contained in
2094 the @arrayfields described by the @arrayft \p array_field_type.
2096 @param[in] array_field_type Array field type of which to get
2097 the type of the fields contained in its
2098 described array fields.
2099 @returns Type of the fields contained in the
2100 array fields described by
2101 \p array_field_type, or \c NULL
2104 @prenotnull{array_field_type}
2105 @preisarrayft{array_field_type}
2106 @postrefcountsame{array_field_type}
2107 @postsuccessrefcountretinc
2110 struct bt_field_type
*bt_field_type_array_get_element_field_type(
2111 struct bt_field_type
*array_field_type
)
2113 return bt_get(bt_field_type_array_borrow_element_field_type(
2118 @brief Returns the number of @fields contained in the
2119 @arrayfields described by the @arrayft \p array_field_type.
2121 @param[in] array_field_type Array field type of which to get
2122 the number of fields contained in its
2123 described array fields.
2124 @returns Number of fields contained in the
2125 array fields described by
2126 \p array_field_type, or a negative value
2129 @prenotnull{array_field_type}
2130 @preisarrayft{array_field_type}
2131 @postrefcountsame{array_field_type}
2133 extern int64_t bt_field_type_array_get_length(
2134 struct bt_field_type
*array_field_type
);
2139 @defgroup ctfirseqfieldtype CTF IR sequence field type
2140 @ingroup ctfirfieldtypes
2141 @brief CTF IR sequence field type.
2144 #include <babeltrace/ctf-ir/field-types.h>
2147 A CTF IR <strong><em>sequence field type</em></strong> is
2148 a field type that you can use to create concrete @seqfields.
2150 You can create a sequence field type with
2151 bt_field_type_sequence_create(). This function needs the @ft
2152 of the fields contained by the sequence fields described by the created
2153 sequence field type. This function also needs the length name of the
2154 sequence field type to create. The length name is used to automatically
2155 resolve the length's field type. See \ref ctfirfieldtypes to learn more
2156 about the automatic resolving.
2161 @addtogroup ctfirseqfieldtype
2166 @brief Creates a default @seqft with \p element_field_type as the
2167 @ft of the @fields contained in its described @seqfields
2168 with the length name \p length_name.
2170 \p length_name can be an absolute or relative reference. See
2171 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2173 @param[in] element_field_type Field type of the fields contained in
2174 the sequence fields described by the
2175 created sequence field type.
2176 @param[in] length_name Length name (copied on success).
2177 @returns Created array field type, or
2180 @prenotnull{element_field_type}
2181 @prenotnull{length_name}
2182 @postsuccessrefcountinc{element_field_type}
2183 @postsuccessrefcountret1
2185 extern struct bt_field_type
*bt_field_type_sequence_create(
2186 struct bt_field_type
*element_field_type
,
2187 const char *length_name
);
2189 extern struct bt_field_type
*bt_field_type_sequence_borrow_element_field_type(
2190 struct bt_field_type
*sequence_field_type
);
2193 @brief Returns the @ft of the @fields contained in the @seqft
2194 described by the @seqft \p sequence_field_type.
2196 @param[in] sequence_field_type Sequence field type of which to get
2197 the type of the fields contained in its
2198 described sequence fields.
2199 @returns Type of the fields contained in the
2200 sequence fields described by
2201 \p sequence_field_type, or \c NULL
2204 @prenotnull{sequence_field_type}
2205 @preisseqft{sequence_field_type}
2206 @postrefcountsame{sequence_field_type}
2207 @postsuccessrefcountretinc
2210 struct bt_field_type
*bt_field_type_sequence_get_element_field_type(
2211 struct bt_field_type
*sequence_field_type
)
2213 return bt_get(bt_field_type_sequence_borrow_element_field_type(
2214 sequence_field_type
));
2218 @brief Returns the length name of the @seqft \p sequence_field_type.
2220 On success, \p sequence_field_type remains the sole owner of
2221 the returned string.
2223 @param[in] sequence_field_type Sequence field type of which to get the
2225 @returns Length name of \p sequence_field_type,
2226 or \c NULL on error.
2228 @prenotnull{sequence_field_type}
2229 @preisseqft{sequence_field_type}
2231 @sa bt_field_type_sequence_get_length_field_path(): Returns the
2232 length's CTF IR field path of a given sequence field type.
2234 extern const char *bt_field_type_sequence_get_length_field_name(
2235 struct bt_field_type
*sequence_field_type
);
2237 extern struct bt_field_path
*bt_field_type_sequence_borrow_length_field_path(
2238 struct bt_field_type
*sequence_field_type
);
2241 @brief Returns the length's CTF IR field path of the @seqft
2242 \p sequence_field_type.
2244 The length's field path of a sequence field type is set when automatic
2245 resolving is performed (see \ref ctfirfieldtypes).
2247 @param[in] sequence_field_type Sequence field type of which to get the
2248 length's field path.
2249 @returns Length's field path of
2250 \p sequence_field_type, or
2251 \c NULL if the length's field path is
2252 not set yet is not set or on error.
2254 @prenotnull{sequence_field_type}
2255 @preisseqft{sequence_field_type}
2256 @postsuccessrefcountretinc
2258 @sa bt_field_type_sequence_get_length_field_name(): Returns the
2259 length's name of a given sequence field type.
2262 struct bt_field_path
*bt_field_type_sequence_get_length_field_path(
2263 struct bt_field_type
*sequence_field_type
)
2265 return bt_get(bt_field_type_sequence_borrow_length_field_path(
2266 sequence_field_type
));
2272 @defgroup ctfirvarfieldtype CTF IR variant field type
2273 @ingroup ctfirfieldtypes
2274 @brief CTF IR variant field type.
2277 #include <babeltrace/ctf-ir/field-types.h>
2280 A CTF IR <strong><em>variant field type</em></strong> is
2281 a field type that you can use to create concrete @varfields.
2283 You can create a variant field type with
2284 bt_field_type_variant_create(). This function expects you to pass
2285 both the tag's @enumft and the tag name of the variant field type to
2286 create. The tag's field type is optional, as the Babeltrace system can
2287 automatically resolve it using the tag name. You can leave the tag name
2288 to \c NULL initially, and set it later with
2289 bt_field_type_variant_set_tag_name(). The tag name must be set when
2290 the variant field type is frozen. See \ref ctfirfieldtypes to learn more
2291 about the automatic resolving and the conditions under which a field
2294 You can add a field to a variant field type with
2295 bt_field_type_variant_add_field(). All the field names of a
2296 variant field type \em must exist as mapping names in its tag's @enumft.
2298 The effective alignment of the @varfields described by a
2299 variant field type is always 1, but the individual fields of a
2300 @varfield can have custom alignments.
2302 You can set the byte order of <em>all the contained fields</em>,
2303 recursively, of a variant field type with the common
2304 bt_field_type_set_byte_order() function.
2309 @addtogroup ctfirvarfieldtype
2314 @brief Creates a default, empty @varft with the tag's @enumft
2315 \p tag_field_type and the tag name \p tag_name.
2317 \p tag_field_type can be \c NULL; the tag's field type can be
2318 automatically resolved from the variant field type's tag name (see
2319 \ref ctfirfieldtypes). If \p tag_name is \c NULL, it \em must be set
2320 with bt_field_type_variant_set_tag_name() \em before the variant
2321 field type is frozen.
2323 \p tag_name can be an absolute or relative reference. See
2324 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2326 @param[in] tag_field_type Tag's enumeration field type
2328 @param[in] tag_name Tag name (copied on success,
2330 @returns Created variant field type, or
2333 @pre \p tag_field_type is an enumeration field type or \c NULL.
2334 @post <strong>On success, if \p tag_field_type is not \c NULL</strong>,
2335 its reference count is incremented.
2336 @postsuccessrefcountret1
2338 extern struct bt_field_type
*bt_field_type_variant_create(
2339 struct bt_field_type
*tag_field_type
,
2340 const char *tag_name
);
2342 extern struct bt_field_type
*bt_field_type_variant_borrow_tag_field_type(
2343 struct bt_field_type
*variant_field_type
);
2346 @brief Returns the tag's @enumft of the @varft \p variant_field_type.
2348 @param[in] variant_field_type Variant field type of which to get
2349 the tag's enumeration field type.
2350 @returns Tag's enumeration field type of
2351 \p variant_field_type, or \c NULL if the
2352 tag's field type is not set or on
2355 @prenotnull{variant_field_type}
2356 @preisvarft{variant_field_type}
2357 @postrefcountsame{variant_field_type}
2358 @postsuccessrefcountretinc
2361 struct bt_field_type
*bt_field_type_variant_get_tag_field_type(
2362 struct bt_field_type
*variant_field_type
)
2364 return bt_get(bt_field_type_variant_borrow_tag_field_type(
2365 variant_field_type
));
2369 @brief Returns the tag name of the @varft \p variant_field_type.
2371 On success, \p variant_field_type remains the sole owner of
2372 the returned string.
2374 @param[in] variant_field_type Variant field type of which to get the
2376 @returns Tag name of \p variant_field_type, or
2377 \c NULL if the tag name is not set or
2380 @prenotnull{variant_field_type}
2381 @preisvarft{variant_field_type}
2383 @sa bt_field_type_variant_set_tag_name(): Sets the tag name of
2384 a given variant field type.
2385 @sa bt_field_type_variant_get_tag_field_path(): Returns the tag's
2386 CTF IR field path of a given variant field type.
2388 extern const char *bt_field_type_variant_get_tag_name(
2389 struct bt_field_type
*variant_field_type
);
2392 @brief Sets the tag name of the @varft \p variant_field_type.
2394 \p tag_name can be an absolute or relative reference. See
2395 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2397 @param[in] variant_field_type Variant field type of which to set
2399 @param[in] tag_name Tag name of \p variant_field_type
2400 (copied on success).
2401 @returns 0 on success, or a negative value on error.
2403 @prenotnull{variant_field_type}
2405 @prehot{variant_field_type}
2406 @postrefcountsame{variant_field_type}
2408 @sa bt_field_type_variant_get_tag_name(): Returns the tag name of
2409 a given variant field type.
2411 extern int bt_field_type_variant_set_tag_name(
2412 struct bt_field_type
*variant_field_type
,
2413 const char *tag_name
);
2415 extern struct bt_field_path
*bt_field_type_variant_borrow_tag_field_path(
2416 struct bt_field_type
*variant_field_type
);
2419 @brief Returns the tag's CTF IR field path of the @varft
2420 \p variant_field_type.
2422 The tag's field path of a variant field type is set when automatic
2423 resolving is performed (see \ref ctfirfieldtypes).
2425 @param[in] variant_field_type Variant field type of which to get the
2427 @returns Tag's field path of
2428 \p variant_field_type, or
2429 \c NULL if the tag's field path is not
2430 set yet is not set or on error.
2432 @prenotnull{variant_field_type}
2433 @preisvarft{variant_field_type}
2434 @postsuccessrefcountretinc
2436 @sa bt_field_type_variant_get_tag_name(): Returns the tag's
2437 name of a given variant field type.
2440 struct bt_field_path
*bt_field_type_variant_get_tag_field_path(
2441 struct bt_field_type
*variant_field_type
)
2443 return bt_get(bt_field_type_variant_borrow_tag_field_path(
2444 variant_field_type
));
2448 @brief Returns the number of fields (choices) contained in the @varft
2449 \p variant_field_type.
2451 @param[in] variant_field_type Variant field type of which to get
2452 the number of contained fields.
2453 @returns Number of fields contained in
2454 \p variant_field_type, or a negative
2457 @prenotnull{variant_field_type}
2458 @preisvarft{variant_field_type}
2459 @postrefcountsame{variant_field_type}
2461 extern int64_t bt_field_type_variant_get_field_count(
2462 struct bt_field_type
*variant_field_type
);
2464 extern int bt_field_type_variant_borrow_field_by_index(
2465 struct bt_field_type
*variant_field_type
,
2466 const char **field_name
,
2467 struct bt_field_type
**field_type
, uint64_t index
);
2470 @brief Returns the field (choice) of the @varft \p variant_field_type
2473 On success, the field's type is placed in \p *field_type if
2474 \p field_type is not \c NULL. The field's name is placed in
2475 \p *field_name if \p field_name is not \c NULL.
2476 \p variant_field_type remains the sole owner of \p *field_name.
2478 @param[in] variant_field_type Variant field type of which to get
2479 the field at index \p index.
2480 @param[out] field_name Returned name of the field at index
2481 \p index (can be \c NULL).
2482 @param[out] field_type Returned field type of the field
2483 at index \p index (can be \c NULL).
2484 @param[in] index Index of the field to get from
2485 \p variant_field_type.
2486 @returns 0 on success, or a negative value on error.
2488 @prenotnull{variant_field_type}
2489 @preisvarft{variant_field_type}
2490 @pre \p index is lesser than the number of fields contained in the
2491 variant field type \p variant_field_type (see
2492 bt_field_type_variant_get_field_count()).
2493 @postrefcountsame{variant_field_type}
2494 @post <strong>On success</strong>, the returned field's type is placed
2495 in \p *field_type and its reference count is incremented.
2497 @sa bt_field_type_variant_get_field_type_by_name(): Finds a variant
2498 field type's field by name.
2499 @sa bt_field_type_variant_get_field_type_from_tag(): Finds a variant
2500 field type's field by current tag value.
2503 int bt_field_type_variant_get_field_by_index(
2504 struct bt_field_type
*variant_field_type
,
2505 const char **field_name
,
2506 struct bt_field_type
**field_type
, uint64_t index
)
2508 int ret
= bt_field_type_variant_borrow_field_by_index(
2509 variant_field_type
, field_name
, field_type
, index
);
2511 if (ret
== 0 && field_type
) {
2512 bt_get(*field_type
);
2519 struct bt_field_type
*bt_field_type_variant_borrow_field_type_by_name(
2520 struct bt_field_type
*variant_field_type
,
2521 const char *field_name
);
2524 @brief Returns the type of the field (choice) named \p field_name
2525 found in the @varft \p variant_field_type.
2527 @param[in] variant_field_type Variant field type of which to get
2529 @param[in] field_name Name of the field to find.
2530 @returns Type of the field named \p field_name in
2531 \p variant_field_type, or
2534 @prenotnull{variant_field_type}
2535 @prenotnull{field_name}
2536 @preisvarft{variant_field_type}
2537 @postrefcountsame{variant_field_type}
2538 @postsuccessrefcountretinc
2540 @sa bt_field_type_variant_get_field_by_index(): Finds a variant field type's
2542 @sa bt_field_type_variant_get_field_type_from_tag(): Finds a variant
2543 field type's field by current tag value.
2546 struct bt_field_type
*bt_field_type_variant_get_field_type_by_name(
2547 struct bt_field_type
*variant_field_type
,
2548 const char *field_name
)
2550 return bt_get(bt_field_type_variant_borrow_field_type_by_name(
2551 variant_field_type
, field_name
));
2555 struct bt_field_type
*bt_field_type_variant_borrow_field_type_from_tag(
2556 struct bt_field_type
*variant_field_type
,
2557 struct bt_field
*tag_field
);
2560 @brief Returns the type of the field (choice) selected by the value of
2561 the @enumfield \p tag_field in the @varft \p variant_field_type.
2563 \p tag_field is the current tag value.
2565 The field type of \p tag_field, as returned by bt_field_get_type(),
2566 \em must be equivalent to the field type returned by
2567 bt_field_type_variant_get_tag_field_type() for \p variant_field_type.
2569 @param[in] variant_field_type Variant field type of which to get
2571 @param[in] tag_field Current tag value (variant field type's
2573 @returns Type of the field selected by
2574 \p tag_field in \p variant_field_type,
2575 or \c NULL on error.
2577 @prenotnull{variant_field_type}
2578 @prenotnull{tag_field}
2579 @preisvarft{variant_field_type}
2580 @preisenumfield{tag_field}
2581 @postrefcountsame{variant_field_type}
2582 @postrefcountsame{tag_field}
2583 @postsuccessrefcountretinc
2585 @sa bt_field_type_variant_get_field_by_index(): Finds a variant field type's
2587 @sa bt_field_type_variant_get_field_type_by_name(): Finds a variant
2588 field type's field by name.
2591 struct bt_field_type
*bt_field_type_variant_get_field_type_from_tag(
2592 struct bt_field_type
*variant_field_type
,
2593 struct bt_field
*tag_field
)
2595 return bt_get(bt_field_type_variant_borrow_field_type_from_tag(
2596 variant_field_type
, tag_field
));
2600 @brief Adds a field (a choice) named \p field_name with the @ft
2601 \p field_type to the @varft \p variant_field_type.
2603 On success, \p field_type becomes the child of \p variant_field_type.
2605 You \em cannot add a field named \p field_name if there's already a
2606 field named \p field_name in \p variant_field_type.
2608 \p field_name \em must name an existing mapping in the tag's
2609 enumeration field type of \p variant_field_type.
2611 @param[in] variant_field_type Variant field type to which to add
2613 @param[in] field_type Field type of the field to add to
2614 \p variant_field_type.
2615 @param[in] field_name Name of the field to add to
2616 \p variant_field_type
2617 (copied on success).
2618 @returns 0 on success, or a negative value on error.
2620 @prenotnull{variant_field_type}
2621 @prenotnull{field_type}
2622 @prenotnull{field_name}
2623 @preisvarft{variant_field_type}
2624 @pre \p field_type is not and does not contain \p variant_field_type,
2625 recursively, as a field's type.
2626 @prehot{variant_field_type}
2627 @postrefcountsame{variant_field_type}
2628 @postsuccessrefcountinc{field_type}
2630 extern int bt_field_type_variant_add_field(
2631 struct bt_field_type
*variant_field_type
,
2632 struct bt_field_type
*field_type
,
2633 const char *field_name
);
2641 #endif /* BABELTRACE_CTF_IR_FIELD_TYPES_H */