1 #ifndef BABELTRACE_CTF_IR_FIELD_TYPES_H
2 #define BABELTRACE_CTF_IR_FIELD_TYPES_H
5 * BabelTrace - CTF IR: Event field types
7 * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
9 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
11 * Permission is hereby granted, free of charge, to any person obtaining a copy
12 * of this software and associated documentation files (the "Software"), to deal
13 * in the Software without restriction, including without limitation the rights
14 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15 * copies of the Software, and to permit persons to whom the Software is
16 * furnished to do so, subject to the following conditions:
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
29 * The Common Trace Format (CTF) Specification is available at
30 * http://www.efficios.com/ctf
40 @defgroup ctfirfieldtypes CTF IR field types
42 @brief CTF IR field types.
45 #include <babeltrace/ctf-ir/field-types.h>
48 A CTF IR <strong><em>field type</em></strong> is a field type that you
49 can use to create concrete @fields.
51 You can create a @field object from a CTF IR field type object
52 with bt_ctf_field_create().
54 In the CTF IR hierarchy, you can set the root field types of three
57 - \ref ctfirtraceclass
58 - Trace packet header field type: bt_ctf_trace_set_packet_header_type().
59 - \ref ctfirstreamclass
60 - Stream packet context field type:
61 bt_ctf_stream_class_set_packet_context_type().
62 - Stream event header field type:
63 bt_ctf_stream_class_set_event_header_type().
64 - Stream event context field type:
65 bt_ctf_stream_class_set_event_context_type().
66 - \ref ctfireventclass
67 - Event context field type: bt_ctf_event_class_set_context_type().
68 - Event payload field type: bt_ctf_event_class_set_payload_type().
70 As of Babeltrace \btversion, those six previous "root" field types
71 \em must be @structft objects.
73 If, at any level within a given root field type, you add a @seqft or a
74 @varft, you do not need to specify its associated length
75 or tag field type: the length or tag string is enough for the Babeltrace
76 system to resolve the needed field type depending on where this
77 dynamic field type is located within the whole hierarchy. It is
78 guaranteed that this automatic resolving is performed for all the field
79 types contained in a given
80 \link ctfirstreamclass CTF IR stream class\endlink (and in its
81 children \link ctfireventclass CTF IR event classes\endlink) once you
82 add it to a \link ctfirtraceclass CTF IR trace class\endlink with
83 bt_ctf_trace_add_stream_class(). Once a stream class is the child of
84 a trace class, this automatic resolving is performed for the field
85 types of an event class when you add it with
86 bt_ctf_stream_class_add_event_class(). If the system cannot find a path
87 to a field in the hierarchy for a dynamic field type, the adding
90 The standard CTF field types are:
96 <th>CTF IR field which you can create from this field type
99 <td>#BT_CTF_TYPE_ID_INTEGER
100 <td>\ref ctfirintfieldtype
101 <td>\ref ctfirintfield
104 <td>#BT_CTF_TYPE_ID_FLOAT
105 <td>\ref ctfirfloatfieldtype
106 <td>\ref ctfirfloatfield
109 <td>#BT_CTF_TYPE_ID_ENUM
110 <td>\ref ctfirenumfieldtype
111 <td>\ref ctfirenumfield
114 <td>#BT_CTF_TYPE_ID_STRING
115 <td>\ref ctfirstringfieldtype
116 <td>\ref ctfirstringfield
119 <td>#BT_CTF_TYPE_ID_STRUCT
120 <td>\ref ctfirstructfieldtype
121 <td>\ref ctfirstructfield
124 <td>#BT_CTF_TYPE_ID_ARRAY
125 <td>\ref ctfirarrayfieldtype
126 <td>\ref ctfirarrayfield
129 <td>#BT_CTF_TYPE_ID_SEQUENCE
130 <td>\ref ctfirseqfieldtype
131 <td>\ref ctfirseqfield
134 <td>#BT_CTF_TYPE_ID_VARIANT
135 <td>\ref ctfirvarfieldtype
136 <td>\ref ctfirvarfield
140 Each field type has its own <strong>type ID</strong> (see
141 #bt_ctf_type_id). You get the type ID of a field type object
142 with bt_ctf_field_type_get_type_id().
144 You can get a deep copy of a field type with bt_ctf_field_type_copy().
145 This function resets, in the field type copy, the resolved field type
146 of the dynamic field types. The automatic resolving can be done again
147 when you eventually call bt_ctf_event_create(),
148 bt_ctf_stream_class_add_event_class(), or
149 bt_ctf_trace_add_stream_class().
151 You \em must always use bt_ctf_field_type_compare() to compare two
152 field types. Since some parts of the Babeltrace system can copy field
153 types behind the scenes, you \em cannot rely on a simple field type
156 As with any Babeltrace object, CTF IR field type objects have
157 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
158 counts</a>. See \ref refs to learn more about the reference counting
159 management of Babeltrace objects.
161 The following functions can \em freeze field type objects:
163 - bt_ctf_field_create() freezes its field type parameter.
164 - bt_ctf_stream_class_add_event_class(), if its
165 \link ctfirstreamclass CTF IR stream class\endlink parameter has a
166 \link ctfirtraceclass CTF IR trace class\endlink parent, freezes
167 the root field types of its
168 \link ctfireventclass CTF IR event class\endlink parameter.
169 - bt_ctf_trace_add_stream_class() freezes the root field types of the
170 whole trace class hierarchy (trace class, children stream classes,
171 and their children event classes).
172 - bt_ctf_writer_create_stream() freezes the root field types of the
173 whole CTF writer's trace class hierarchy.
174 - bt_ctf_event_create() freezes the root field types of its event class
175 parameter and of ther parent stream class of this event class.
177 You cannot modify a frozen field type object: it is considered
178 immutable, except for \link refs reference counting\endlink.
181 @sa \ref ctfirfieldtypesexamples "Examples"
184 @brief CTF IR field types type and functions.
187 @addtogroup ctfirfieldtypes
192 @struct bt_ctf_field_type
193 @brief A CTF IR field type.
196 struct bt_ctf_field_type
;
197 struct bt_ctf_event_class
;
200 struct bt_ctf_field_path
;
201 struct bt_ctf_field_type_enumeration_mapping_iterator
;
203 /** @cond DOCUMENT */
206 * Babeltrace 1.x enumerations that were also used in CTF writer's API.
207 * They are left here for backward compatibility reasons, but
208 * enum bt_ctf_type_id and enum bt_ctf_string_encoding should be used
209 * in new code. Both new enumerations are compatible with their legacy
213 CTF_TYPE_UNKNOWN
= 0,
219 CTF_TYPE_UNTAGGED_VARIANT
,
229 enum ctf_string_encoding
{
242 /// Unknown, used for errors.
243 BT_CTF_SCOPE_UNKNOWN
= -1,
245 /// Trace packet header.
246 BT_CTF_SCOPE_TRACE_PACKET_HEADER
= 1,
248 /// Stream packet context.
249 BT_CTF_SCOPE_STREAM_PACKET_CONTEXT
= 2,
251 /// Stream event header.
252 BT_CTF_SCOPE_STREAM_EVENT_HEADER
= 3,
254 /// Stream event context.
255 BT_CTF_SCOPE_STREAM_EVENT_CONTEXT
= 4,
258 BT_CTF_SCOPE_EVENT_CONTEXT
= 5,
261 BT_CTF_SCOPE_EVENT_PAYLOAD
= 6,
264 BT_CTF_SCOPE_ENV
= 0,
265 BT_CTF_SCOPE_EVENT_FIELDS
= 6,
270 @name Type information
275 @brief Type ID of a @ft.
277 enum bt_ctf_type_id
{
278 /// Unknown, used for errors.
279 BT_CTF_TYPE_ID_UNKNOWN
= CTF_TYPE_UNKNOWN
,
281 /// \ref ctfirintfieldtype
282 BT_CTF_TYPE_ID_INTEGER
= CTF_TYPE_INTEGER
,
284 /// \ref ctfirfloatfieldtype
285 BT_CTF_TYPE_ID_FLOAT
= CTF_TYPE_FLOAT
,
287 /// \ref ctfirenumfieldtype
288 BT_CTF_TYPE_ID_ENUM
= CTF_TYPE_ENUM
,
290 /// \ref ctfirstringfieldtype
291 BT_CTF_TYPE_ID_STRING
= CTF_TYPE_STRING
,
293 /// \ref ctfirstructfieldtype
294 BT_CTF_TYPE_ID_STRUCT
= CTF_TYPE_STRUCT
,
297 BT_CTF_TYPE_ID_UNTAGGED_VARIANT
= CTF_TYPE_UNTAGGED_VARIANT
,
300 /// \ref ctfirarrayfieldtype
301 BT_CTF_TYPE_ID_ARRAY
= CTF_TYPE_ARRAY
,
303 /// \ref ctfirseqfieldtype
304 BT_CTF_TYPE_ID_SEQUENCE
= CTF_TYPE_SEQUENCE
,
306 /// \ref ctfirvarfieldtype
307 BT_CTF_TYPE_ID_VARIANT
= CTF_TYPE_VARIANT
,
309 /// Number of enumeration entries.
310 BT_CTF_NR_TYPE_IDS
= NR_CTF_TYPES
,
314 @brief Returns the type ID of the @ft \p field_type.
316 @param[in] field_type Field type of which to get the type ID.
317 @returns Type ID of \p field_type,
318 or #BT_CTF_TYPE_ID_UNKNOWN on error.
320 @prenotnull{field_type}
321 @postrefcountsame{field_type}
323 @sa #bt_ctf_type_id: CTF IR field type ID.
324 @sa bt_ctf_field_type_is_integer(): Returns whether or not a given
325 field type is a @intft.
326 @sa bt_ctf_field_type_is_floating_point(): Returns whether or not a
327 given field type is a @floatft.
328 @sa bt_ctf_field_type_is_enumeration(): Returns whether or not a given
329 field type is a @enumft.
330 @sa bt_ctf_field_type_is_string(): Returns whether or not a given
331 field type is a @stringft.
332 @sa bt_ctf_field_type_is_structure(): Returns whether or not a given
333 field type is a @structft.
334 @sa bt_ctf_field_type_is_array(): Returns whether or not a given
335 field type is a @arrayft.
336 @sa bt_ctf_field_type_is_sequence(): Returns whether or not a given
337 field type is a @seqft.
338 @sa bt_ctf_field_type_is_variant(): Returns whether or not a given
339 field type is a @varft.
341 extern enum bt_ctf_type_id
bt_ctf_field_type_get_type_id(
342 struct bt_ctf_field_type
*field_type
);
345 @brief Returns whether or not the @ft \p field_type is a @intft.
347 @param[in] field_type Field type to check (can be \c NULL).
348 @returns 1 if \p field_type is an integer field type,
349 or 0 otherwise (including if \p field_type is
352 @prenotnull{field_type}
353 @postrefcountsame{field_type}
355 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
358 extern int bt_ctf_field_type_is_integer(struct bt_ctf_field_type
*field_type
);
361 @brief Returns whether or not the @ft \p field_type is a @floatft.
363 @param[in] field_type Field type to check (can be \c NULL).
364 @returns 1 if \p field_type is a floating point
366 or 0 otherwise (including if \p field_type is
369 @postrefcountsame{field_type}
371 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
374 extern int bt_ctf_field_type_is_floating_point(struct bt_ctf_field_type
*field_type
);
377 @brief Returns whether or not the @ft \p field_type is a @enumft.
379 @param[in] field_type Field type to check (can be \c NULL).
380 @returns 1 if \p field_type is an enumeration field type,
381 or 0 otherwise (including if \p field_type is
384 @postrefcountsame{field_type}
386 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
389 extern int bt_ctf_field_type_is_enumeration(struct bt_ctf_field_type
*field_type
);
392 @brief Returns whether or not the @ft \p field_type is a @stringft.
394 @param[in] field_type Field type to check (can be \c NULL).
395 @returns 1 if \p field_type is a string field type,
396 or 0 otherwise (including if \p field_type is
399 @postrefcountsame{field_type}
401 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
404 extern int bt_ctf_field_type_is_string(struct bt_ctf_field_type
*field_type
);
407 @brief Returns whether or not the @ft \p field_type is a @structft.
409 @param[in] field_type Field type to check (can be \c NULL).
410 @returns 1 if \p field_type is a structure field type,
411 or 0 otherwise (including if \p field_type is
414 @postrefcountsame{field_type}
416 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
419 extern int bt_ctf_field_type_is_structure(struct bt_ctf_field_type
*field_type
);
422 @brief Returns whether or not the @ft \p field_type is a @arrayft.
424 @param[in] field_type Field type to check (can be \c NULL).
425 @returns 1 if \p field_type is an array field type,
426 or 0 otherwise (including if \p field_type is
429 @postrefcountsame{field_type}
431 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
434 extern int bt_ctf_field_type_is_array(struct bt_ctf_field_type
*field_type
);
437 @brief Returns whether or not the @ft \p field_type is a @seqft.
439 @param[in] field_type Field type to check (can be \c NULL).
440 @returns 1 if \p field_type is a sequence field type,
441 or 0 otherwise (including if \p field_type is
444 @postrefcountsame{field_type}
446 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
449 extern int bt_ctf_field_type_is_sequence(struct bt_ctf_field_type
*field_type
);
452 @brief Returns whether or not the @ft \p field_type is a @varft.
454 @param[in] field_type Field type to check (can be \c NULL).
455 @returns 1 if \p field_type is a variant field type,
456 or 0 otherwise (including if \p field_type is
459 @postrefcountsame{field_type}
461 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
464 extern int bt_ctf_field_type_is_variant(struct bt_ctf_field_type
*field_type
);
469 @name Common properties types and functions
474 @brief <a href="https://en.wikipedia.org/wiki/Endianness">Byte order</a>
477 enum bt_ctf_byte_order
{
478 /// Unknown, used for errors.
479 BT_CTF_BYTE_ORDER_UNKNOWN
= -1,
482 * Note that native, in the context of the CTF specification, is defined
483 * as "the byte order described in the trace" and does not mean that the
484 * host's endianness will be used.
486 /// Native (default) byte order.
487 BT_CTF_BYTE_ORDER_NATIVE
= 0,
490 BT_CTF_BYTE_ORDER_LITTLE_ENDIAN
,
493 BT_CTF_BYTE_ORDER_BIG_ENDIAN
,
495 /// Network byte order (big-endian).
496 BT_CTF_BYTE_ORDER_NETWORK
,
500 @brief String encoding of a @ft.
502 enum bt_ctf_string_encoding
{
503 /// Unknown, used for errors.
504 BT_CTF_STRING_ENCODING_UNKNOWN
= CTF_STRING_UNKNOWN
,
507 BT_CTF_STRING_ENCODING_NONE
= CTF_STRING_NONE
,
509 /// <a href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a>.
510 BT_CTF_STRING_ENCODING_UTF8
= CTF_STRING_UTF8
,
512 /// <a href="https://en.wikipedia.org/wiki/ASCII">ASCII</a>.
513 BT_CTF_STRING_ENCODING_ASCII
= CTF_STRING_ASCII
,
517 @brief Returns the alignment of the @fields described by
518 the @ft \p field_type.
520 @param[in] field_type Field type which describes the
521 fields of which to get the alignment.
522 @returns Alignment of the fields described by
523 \p field_type, or a negative value on error.
525 @prenotnull{field_type}
526 @postrefcountsame{field_type}
528 @sa bt_ctf_field_type_set_alignment(): Sets the alignment
529 of the fields described by a given field type.
531 extern int bt_ctf_field_type_get_alignment(
532 struct bt_ctf_field_type
*field_type
);
535 @brief Sets the alignment of the @fields described by the
536 @ft \p field_type to \p alignment.
538 \p alignment \em must be greater than 0 and a power of two.
540 @param[in] field_type Field type which describes the fields of
541 which to set the alignment.
542 @param[in] alignment Alignment of the fields described by
544 @returns 0 on success, or a negative value on error.
546 @prenotnull{field_type}
548 @pre \p alignment is greater than 0 and a power of two.
549 @postrefcountsame{field_type}
551 @sa bt_ctf_field_type_get_alignment(): Returns the alignment of the
552 fields described by a given field type.
554 extern int bt_ctf_field_type_set_alignment(struct bt_ctf_field_type
*field_type
,
555 unsigned int alignment
);
558 @brief Returns the byte order of the @fields described by
559 the @ft \p field_type.
561 You can only call this function if \p field_type is a @intft, a
562 @floatft, or a @enumft.
564 @param[in] field_type Field type which describes the
565 fields of which to get the byte order.
566 @returns Byte order of the fields described by
567 \p field_type, or #BT_CTF_BYTE_ORDER_UNKNOWN on
570 @prenotnull{field_type}
571 @pre \p field_type is a @intft, a @floatft, or a @enumft.
572 @postrefcountsame{field_type}
574 @sa bt_ctf_field_type_set_byte_order(): Sets the byte order
575 of the fields described by a given field type.
577 extern enum bt_ctf_byte_order
bt_ctf_field_type_get_byte_order(
578 struct bt_ctf_field_type
*field_type
);
581 @brief Sets the byte order of the @fields described by the
582 @ft \p field_type to \p byte_order.
584 If \p field_type is a compound field type, this function also
585 recursively sets the byte order of its children to \p byte_order.
587 @param[in] field_type Field type which describes the fields of
588 which to set the byte order.
589 @param[in] byte_order Alignment of the fields described by
591 @returns 0 on success, or a negative value on error.
593 @prenotnull{field_type}
595 @pre \p byte_order is #BT_CTF_BYTE_ORDER_NATIVE,
596 #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN, #BT_CTF_BYTE_ORDER_BIG_ENDIAN,
597 or #BT_CTF_BYTE_ORDER_NETWORK.
598 @postrefcountsame{field_type}
600 @sa bt_ctf_field_type_get_byte_order(): Returns the byte order of the
601 fields described by a given field type.
603 extern int bt_ctf_field_type_set_byte_order(
604 struct bt_ctf_field_type
*field_type
,
605 enum bt_ctf_byte_order byte_order
);
610 @name Utility functions
615 @brief Returns whether or not the @ft \p field_type_a
616 is equivalent to the field type \p field_type_b.
618 You \em must use this function to compare two field types: it is not
619 safe to compare two pointer values directly, because, for internal
620 reasons, some parts of the Babeltrace system can copy user field types
621 and discard the original ones.
623 @param[in] field_type_a Field type to compare to \p field_type_b.
624 @param[in] field_type_b Field type to compare to \p field_type_a.
625 @returns 0 if \p field_type_a is equivalent to
626 \p field_type_b, 1 if they are not equivalent,
627 or a negative value on error.
629 @prenotnull{field_type_a}
630 @prenotnull{field_type_b}
631 @postrefcountsame{field_type_a}
632 @postrefcountsame{field_type_b}
634 extern int bt_ctf_field_type_compare(struct bt_ctf_field_type
*field_type_a
,
635 struct bt_ctf_field_type
*field_type_b
);
638 @brief Creates a \em deep copy of the @ft \p field_type.
640 You can copy a frozen field type: the resulting copy is
643 This function resets the tag field type of a copied @varft. The
644 automatic field resolving which some functions of the API perform
645 can set it again when the returned field type is used (learn more
646 in the detailed description of this module).
648 @param[in] field_type Field type to copy.
649 @returns Deep copy of \p field_type on success,
652 @prenotnull{field_type}
653 @postrefcountsame{field_type}
654 @postsuccessrefcountret1
655 @post <strong>On success</strong>, the returned field type is not frozen.
657 extern struct bt_ctf_field_type
*bt_ctf_field_type_copy(
658 struct bt_ctf_field_type
*field_type
);
665 @defgroup ctfirintfieldtype CTF IR integer field type
666 @ingroup ctfirfieldtypes
667 @brief CTF IR integer field type.
670 #include <babeltrace/ctf-ir/field-types.h>
673 A CTF IR <strong><em>integer field type</em></strong> is a field type that
674 you can use to create concrete @intfield objects.
676 You can create an integer field type
677 with bt_ctf_field_type_integer_create().
679 An integer field type has the following properties:
684 <th>Value at creation
689 <td>\b Alignment (bits) of the described integer fields
691 <td>bt_ctf_field_type_get_alignment()
692 <td>bt_ctf_field_type_set_alignment()
695 <td><strong>Byte order</strong> of the described integer fields
696 <td>#BT_CTF_BYTE_ORDER_NATIVE
697 <td>bt_ctf_field_type_get_byte_order()
698 <td>bt_ctf_field_type_set_byte_order()
701 <td><strong>Storage size</strong> (bits) of the described
703 <td>Specified at creation
704 <td>bt_ctf_field_type_integer_get_size()
705 <td>None: specified at creation (bt_ctf_field_type_integer_create())
708 <td><strong>Signedness</strong> of the described integer fields
710 <td>bt_ctf_field_type_integer_get_signed()
711 <td>bt_ctf_field_type_integer_set_signed()
714 <td><strong>Preferred display base</strong> of the described
716 <td>#BT_CTF_INTEGER_BASE_DECIMAL
717 <td>bt_ctf_field_type_integer_get_base()
718 <td>bt_ctf_field_type_integer_set_base()
721 <td>\b Encoding of the described integer fields
722 <td>#BT_CTF_STRING_ENCODING_NONE
723 <td>bt_ctf_field_type_integer_get_encoding()
724 <td>bt_ctf_field_type_integer_set_encoding()
728 \link ctfirclockclass CTF IR clock class\endlink</strong>
730 <td>bt_ctf_field_type_integer_get_mapped_clock_class()
731 <td>bt_ctf_field_type_integer_set_mapped_clock_class()
737 @sa \ref ctfirfieldtypesexamples_intfieldtype "Examples"
739 @addtogroup ctfirintfieldtype
744 @brief Preferred display base (radix) of a @intft.
746 enum bt_ctf_integer_base
{
747 /// Unknown, used for errors.
748 BT_CTF_INTEGER_BASE_UNKNOWN
= -1,
751 BT_CTF_INTEGER_BASE_BINARY
= 2,
754 BT_CTF_INTEGER_BASE_OCTAL
= 8,
757 BT_CTF_INTEGER_BASE_DECIMAL
= 10,
760 BT_CTF_INTEGER_BASE_HEXADECIMAL
= 16,
764 @brief Creates a default @intft with \p size bits as the storage size
765 of the @intfields it describes.
767 @param[in] size Storage size (bits) of the described integer fields.
768 @returns Created integer field type, or \c NULL on error.
770 @pre \p size is greater than 0 and lesser than or equal to 64.
771 @postsuccessrefcountret1
773 extern struct bt_ctf_field_type
*bt_ctf_field_type_integer_create(
777 @brief Returns the storage size, in bits, of the @intfields
778 described by the @intft \p int_field_type.
780 @param[in] int_field_type Integer field type which describes the
781 integer fields of which to get the
783 @returns Storage size (bits) of the integer
784 fields described by \p int_field_type,
785 or a negative value on error.
787 @prenotnull{int_field_type}
788 @preisintft{int_field_type}
789 @postrefcountsame{int_field_type}
791 extern int bt_ctf_field_type_integer_get_size(
792 struct bt_ctf_field_type
*int_field_type
);
795 @brief Returns whether or not the @intfields described by the @intft
796 \p int_field_type are signed.
798 @param[in] int_field_type Integer field type which describes the
799 integer fields of which to get the
801 @returns 1 if the integer fields described by
802 \p int_field_type are signed, 0 if they
803 are unsigned, or a negative value on
806 @prenotnull{int_field_type}
807 @preisintft{int_field_type}
808 @postrefcountsame{int_field_type}
810 @sa bt_ctf_field_type_integer_set_signed(): Sets the signedness of the
811 integer fields described by a given integer field type.
813 extern int bt_ctf_field_type_integer_get_signed(
814 struct bt_ctf_field_type
*int_field_type
);
817 @brief Sets whether or not the @intfields described by
818 the @intft \p int_field_type are signed.
820 @param[in] int_field_type Integer field type which describes the
821 integer fields of which to set the
823 @param[in] is_signed Signedness of the integer fields
824 described by \p int_field_type; 0 means
825 \em unsigned, 1 means \em signed.
826 @returns 0 on success, or a negative value on error.
828 @prenotnull{int_field_type}
829 @preisintft{int_field_type}
830 @prehot{int_field_type}
831 @pre \p is_signed is 0 or 1.
832 @postrefcountsame{event_class}
834 @sa bt_ctf_field_type_integer_get_signed(): Returns the signedness of
835 the integer fields described by a given integer field type.
837 extern int bt_ctf_field_type_integer_set_signed(
838 struct bt_ctf_field_type
*int_field_type
, int is_signed
);
841 @brief Returns the preferred display base (radix) of the @intfields
842 described by the @intft \p int_field_type.
844 @param[in] int_field_type Integer field type which describes the
845 integer fields of which to get the
846 preferred display base.
847 @returns Preferred display base of the integer
848 fields described by \p int_field_type,
849 or #BT_CTF_INTEGER_BASE_UNKNOWN on
852 @prenotnull{int_field_type}
853 @preisintft{int_field_type}
854 @postrefcountsame{int_field_type}
856 @sa bt_ctf_field_type_integer_set_base(): Sets the preferred display
857 base of the integer fields described by a given integer field
860 extern enum bt_ctf_integer_base
bt_ctf_field_type_integer_get_base(
861 struct bt_ctf_field_type
*int_field_type
);
864 @brief Sets the preferred display base (radix) of the @intfields
865 described by the @intft \p int_field_type to \p base.
867 @param[in] int_field_type Integer field type which describes the
868 integer fields of which to set the
869 preferred display base.
870 @param[in] base Preferred display base of the integer
871 fields described by \p int_field_type.
872 @returns 0 on success, or a negative value on error.
874 @prenotnull{int_field_type}
875 @preisintft{int_field_type}
876 @prehot{int_field_type}
877 @pre \p base is #BT_CTF_INTEGER_BASE_BINARY, #BT_CTF_INTEGER_BASE_OCTAL,
878 #BT_CTF_INTEGER_BASE_DECIMAL, or
879 #BT_CTF_INTEGER_BASE_HEXADECIMAL.
880 @postrefcountsame{int_field_type}
882 @sa bt_ctf_field_type_integer_get_base(): Returns the preferred display
883 base of the integer fields described by a given
886 extern int bt_ctf_field_type_integer_set_base(
887 struct bt_ctf_field_type
*int_field_type
,
888 enum bt_ctf_integer_base base
);
891 @brief Returns the encoding of the @intfields described by
892 the @intft \p int_field_type.
894 @param[in] int_field_type Integer field type which describes the
895 integer fields of which to get the
897 @returns Encoding of the integer
898 fields described by \p int_field_type,
899 or #BT_CTF_STRING_ENCODING_UNKNOWN on
902 @prenotnull{int_field_type}
903 @preisintft{int_field_type}
904 @postrefcountsame{int_field_type}
906 @sa bt_ctf_field_type_integer_set_encoding(): Sets the encoding
907 of the integer fields described by a given integer field type.
909 extern enum bt_ctf_string_encoding
bt_ctf_field_type_integer_get_encoding(
910 struct bt_ctf_field_type
*int_field_type
);
913 @brief Sets the encoding of the @intfields described by the @intft
914 \p int_field_type to \p encoding.
916 You can use this property, in CTF IR, to create "text" @arrayfts or
917 @seqfts. A text array field type is array field type with an unsigned,
918 8-bit integer field type having an encoding as its element field type.
920 @param[in] int_field_type Integer field type which describes the
921 integer fields of which to set the
923 @param[in] encoding Encoding of the integer
924 fields described by \p int_field_type.
925 @returns 0 on success, or a negative value on error.
927 @prenotnull{int_field_type}
928 @preisintft{int_field_type}
929 @prehot{int_field_type}
930 @pre \p encoding is #BT_CTF_STRING_ENCODING_NONE,
931 #BT_CTF_STRING_ENCODING_ASCII, or
932 #BT_CTF_STRING_ENCODING_UTF8.
933 @postrefcountsame{int_field_type}
935 @sa bt_ctf_field_type_integer_get_encoding(): Returns the encoding of
936 the integer fields described by a given integer field type.
938 extern int bt_ctf_field_type_integer_set_encoding(
939 struct bt_ctf_field_type
*int_field_type
,
940 enum bt_ctf_string_encoding encoding
);
943 @brief Returns the \link ctfirclockclass CTF IR clock class\endlink
944 mapped to the @intft \p int_field_type.
946 The mapped clock class, if any, indicates the class of the clock which
947 an @intfield described by \p int_field_type should sample or update.
948 This mapped clock class is only indicative.
950 @param[in] int_field_type Integer field type of which to get the
952 @returns Mapped clock class of \p int_field_type,
953 or \c NULL if there's no mapped clock
956 @prenotnull{int_field_type}
957 @preisintft{int_field_type}
958 @postrefcountsame{int_field_type}
959 @postsuccessrefcountretinc
961 @sa bt_ctf_field_type_integer_set_mapped_clock_class(): Sets the mapped
962 clock class of a given integer field type.
964 extern struct bt_ctf_clock_class
*bt_ctf_field_type_integer_get_mapped_clock_class(
965 struct bt_ctf_field_type
*int_field_type
);
968 @brief Sets the \link ctfirclockclass CTF IR clock class\endlink mapped
969 to the @intft \p int_field_type to \p clock_class.
971 The mapped clock class, if any, indicates the class of the clock which
972 an integer field described by \p int_field_type should sample or update.
973 This mapped clock class is only indicative.
975 @param[in] int_field_type Integer field type of which to set the
977 @param[in] clock_class Mapped clock class of \p int_field_type.
978 @returns 0 on success, or a negative value on error.
980 @prenotnull{int_field_type}
981 @prenotnull{clock_class}
982 @preisintft{int_field_type}
983 @prehot{int_field_type}
984 @postrefcountsame{int_field_type}
985 @postsuccessrefcountinc{clock_class}
987 @sa bt_ctf_field_type_integer_get_mapped_clock_class(): Returns the mapped
988 clock class of a given integer field type.
990 extern int bt_ctf_field_type_integer_set_mapped_clock_class(
991 struct bt_ctf_field_type
*int_field_type
,
992 struct bt_ctf_clock_class
*clock_class
);
997 @defgroup ctfirfloatfieldtype CTF IR floating point number field type
998 @ingroup ctfirfieldtypes
999 @brief CTF IR floating point number field type.
1002 #include <babeltrace/ctf-ir/field-types.h>
1005 A CTF IR <strong><em>floating point number field type</em></strong> is
1006 a field type that you can use to create concrete @floatfields.
1008 You can create a floating point number field type
1009 with bt_ctf_field_type_floating_point_create().
1011 A floating point number field type has the following properties:
1016 <th>Value at creation
1021 <td>\b Alignment (bits) of the described floating point
1024 <td>bt_ctf_field_type_get_alignment()
1025 <td>bt_ctf_field_type_set_alignment()
1028 <td><strong>Byte order</strong> of the described floating point
1030 <td>#BT_CTF_BYTE_ORDER_NATIVE
1031 <td>bt_ctf_field_type_get_byte_order()
1032 <td>bt_ctf_field_type_set_byte_order()
1035 <td><strong>Exponent storage size</strong> (bits) of the described
1036 floating point number fields
1038 <td>bt_ctf_field_type_floating_point_get_exponent_digits()
1039 <td>bt_ctf_field_type_floating_point_set_exponent_digits()
1042 <td><strong>Mantissa and sign storage size</strong> (bits) of the
1043 described floating point number fields
1044 <td>24 (23-bit mantissa, 1-bit sign)
1045 <td>bt_ctf_field_type_floating_point_get_mantissa_digits()
1046 <td>bt_ctf_field_type_floating_point_set_mantissa_digits()
1052 @sa \ref ctfirfieldtypesexamples_floatfieldtype "Examples"
1054 @addtogroup ctfirfloatfieldtype
1059 @brief Creates a default @floatft.
1061 @returns Created floating point number field type,
1062 or \c NULL on error.
1064 @postsuccessrefcountret1
1066 extern struct bt_ctf_field_type
*bt_ctf_field_type_floating_point_create(void);
1069 @brief Returns the exponent storage size of the @floatfields
1070 described by the @floatft \p float_field_type.
1072 @param[in] float_field_type Floating point number field type which
1073 describes the floating point number
1074 fields of which to get the exponent
1076 @returns Exponent storage size of the
1077 floating point number fields
1078 described by \p float_field_type,
1079 or a negative value on error.
1081 @prenotnull{float_field_type}
1082 @preisfloatft{float_field_type}
1083 @postrefcountsame{float_field_type}
1085 @sa bt_ctf_field_type_floating_point_set_exponent_digits(): Sets the
1086 exponent storage size of the floating point number fields
1087 described by a given floating point number field type.
1089 extern int bt_ctf_field_type_floating_point_get_exponent_digits(
1090 struct bt_ctf_field_type
*float_field_type
);
1093 @brief Sets the exponent storage size of the @floatfields described by
1094 the @floatft \p float_field_type to \p exponent_size.
1096 As of Babeltrace \btversion, \p exponent_size can only be 8 or 11.
1098 @param[in] float_field_type Floating point number field type which
1099 describes the floating point number
1100 fields of which to set the exponent
1102 @param[in] exponent_size Exponent storage size of the floating
1103 point number fields described by \p
1105 @returns 0 on success, or a negative value on error.
1107 @prenotnull{float_field_type}
1108 @preisfloatft{float_field_type}
1109 @prehot{float_field_type}
1110 @pre \p exponent_size is 8 or 11.
1111 @postrefcountsame{float_field_type}
1113 @sa bt_ctf_field_type_floating_point_get_exponent_digits(): Returns the
1114 exponent storage size of the floating point number fields
1115 described by a given floating point number field type.
1117 extern int bt_ctf_field_type_floating_point_set_exponent_digits(
1118 struct bt_ctf_field_type
*float_field_type
,
1119 unsigned int exponent_size
);
1122 @brief Returns the mantissa and sign storage size of the @floatfields
1123 described by the @floatft \p float_field_type.
1125 On success, the returned value is the sum of the mantissa \em and
1128 @param[in] float_field_type Floating point number field type which
1129 describes the floating point number
1130 fields of which to get the mantissa and
1132 @returns Mantissa and sign storage size of the
1133 floating point number fields
1134 described by \p float_field_type,
1135 or a negative value on error.
1137 @prenotnull{float_field_type}
1138 @preisfloatft{float_field_type}
1139 @postrefcountsame{float_field_type}
1141 @sa bt_ctf_field_type_floating_point_set_mantissa_digits(): Sets the
1142 mantissa and size storage size of the floating point number
1143 fields described by a given floating point number field type.
1145 extern int bt_ctf_field_type_floating_point_get_mantissa_digits(
1146 struct bt_ctf_field_type
*float_field_type
);
1149 @brief Sets the mantissa and sign storage size of the @floatfields
1150 described by the @floatft \p float_field_type to \p
1153 As of Babeltrace \btversion, \p mantissa_sign_size can only be 24 or 53.
1155 @param[in] float_field_type Floating point number field type which
1156 describes the floating point number
1157 fields of which to set the mantissa and
1159 @param[in] mantissa_sign_size Mantissa and sign storage size of the
1160 floating point number fields described
1161 by \p float_field_type.
1162 @returns 0 on success, or a negative value on error.
1164 @prenotnull{float_field_type}
1165 @preisfloatft{float_field_type}
1166 @prehot{float_field_type}
1167 @pre \p mantissa_sign_size is 24 or 53.
1168 @postrefcountsame{float_field_type}
1170 @sa bt_ctf_field_type_floating_point_get_mantissa_digits(): Returns the
1171 mantissa and sign storage size of the floating point number
1172 fields described by a given floating point number field type.
1174 extern int bt_ctf_field_type_floating_point_set_mantissa_digits(
1175 struct bt_ctf_field_type
*float_field_type
,
1176 unsigned int mantissa_sign_size
);
1181 @defgroup ctfirenumfieldtype CTF IR enumeration field type
1182 @ingroup ctfirfieldtypes
1183 @brief CTF IR enumeration field type.
1186 #include <babeltrace/ctf-ir/field-types.h>
1189 A CTF IR <strong><em>enumeration field type</em></strong> is
1190 a field type that you can use to create concrete @enumfields.
1192 You can create an enumeration field type with
1193 bt_ctf_field_type_enumeration_create(). This function needs a @intft
1194 which represents the storage field type of the created enumeration field
1195 type. In other words, an enumeration field type wraps an integer field
1196 type and adds label-value mappings to it.
1198 An enumeration mapping has:
1200 - A <strong>name</strong>.
1201 - A <strong>range of values</strong> given by a beginning and an ending
1202 value, both included in the range.
1204 You can add a mapping to an enumeration field type with
1205 bt_ctf_field_type_enumeration_add_mapping() or
1206 bt_ctf_field_type_enumeration_add_mapping_unsigned(), depending on the
1207 signedness of the wrapped @intft.
1209 You can find mappings by name or by value with the following find
1212 - bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
1213 mappings with a given name.
1214 - bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value():
1215 Finds the mappings which contain a given unsigned value in their
1217 - bt_ctf_field_type_enumeration_find_mappings_by_signed_value():
1218 Finds the mappings which contain a given signed value in their range.
1220 Those functions return a @enumftiter on the result set of the find
1223 Many mappings can share the same name, and the ranges of a given
1224 enumeration field type are allowed to overlap. For example,
1225 this is a valid set of mappings:
1234 The following set of mappings is also valid:
1243 Here, the range of the second \c APPLE mapping overlaps the range of
1244 the \c CHERRY mapping.
1246 @sa ctfirenumftmappingiter
1250 @addtogroup ctfirenumfieldtype
1255 @brief Creates a default @enumft wrapping the @intft \p int_field_type.
1257 @param[in] int_field_type Integer field type wrapped by the
1258 created enumeration field type.
1259 @returns Created enumeration field type,
1260 or \c NULL on error.
1262 @prenotnull{int_field_type}
1263 @preisintft{int_field_type}
1264 @postsuccessrefcountinc{int_field_type}
1265 @postsuccessrefcountret1
1267 extern struct bt_ctf_field_type
*bt_ctf_field_type_enumeration_create(
1268 struct bt_ctf_field_type
*int_field_type
);
1271 @brief Returns the @intft wrapped by the @enumft \p enum_field_type.
1273 @param[in] enum_field_type Enumeration field type of which to get
1274 the wrapped integer field type.
1275 @returns Integer field type wrapped by
1276 \p enum_field_type, or \c NULL on
1279 @prenotnull{enum_field_type}
1280 @preisenumft{enum_field_type}
1281 @postrefcountsame{enum_field_type}
1282 @postsuccessrefcountretinc
1285 struct bt_ctf_field_type
*bt_ctf_field_type_enumeration_get_container_type(
1286 struct bt_ctf_field_type
*enum_field_type
);
1289 @brief Returns the number of mappings contained in the
1290 @enumft \p enum_field_type.
1292 @param[in] enum_field_type Enumeration field type of which to get
1293 the number of contained mappings.
1294 @returns Number of mappings contained in
1295 \p enum_field_type, or a negative
1298 @prenotnull{enum_field_type}
1299 @preisenumft{enum_field_type}
1300 @postrefcountsame{enum_field_type}
1302 extern int bt_ctf_field_type_enumeration_get_mapping_count(
1303 struct bt_ctf_field_type
*enum_field_type
);
1306 @brief Returns the signed mapping of the @enumft
1307 \p enum_field_type at index \p index.
1309 The @intft wrapped by \p enum_field_type, as returned by
1310 bt_ctf_field_type_enumeration_get_container_type(), must be \b signed
1311 to use this function.
1313 On success, \p enum_field_type remains the sole owner of \p *name.
1315 @param[in] enum_field_type Enumeration field type of which to get
1316 the mapping at index \p index.
1317 @param[in] index Index of the mapping to get from
1319 @param[out] name Returned name of the mapping at index
1321 @param[out] range_begin Returned beginning of the range
1322 (included) of the mapping at index \p
1324 @param[out] range_end Returned end of the range (included) of
1325 the mapping at index \p index.
1326 @returns 0 on success, or a negative value on error.
1328 @prenotnull{enum_field_type}
1330 @prenotnull{range_begin}
1331 @prenotnull{range_end}
1332 @preisenumft{enum_field_type}
1333 @pre The wrapped @intft of \p enum_field_type is signed.
1334 @pre \p index is lesser than the number of mappings contained in the
1335 enumeration field type \p enum_field_type (see
1336 bt_ctf_field_type_enumeration_get_mapping_count()).
1337 @postrefcountsame{enum_field_type}
1339 @sa bt_ctf_field_type_enumeration_get_mapping_unsigned(): Returns the
1340 unsigned mapping contained by a given enumeration field type
1343 extern int bt_ctf_field_type_enumeration_get_mapping_signed(
1344 struct bt_ctf_field_type
*enum_field_type
, int index
,
1345 const char **name
, int64_t *range_begin
, int64_t *range_end
);
1348 @brief Returns the unsigned mapping of the @enumft
1349 \p enum_field_type at index \p index.
1351 The @intft wrapped by \p enum_field_type, as returned by
1352 bt_ctf_field_type_enumeration_get_container_type(), must be
1353 \b unsigned to use this function.
1355 On success, \p enum_field_type remains the sole owner of \p *name.
1357 @param[in] enum_field_type Enumeration field type of which to get
1358 the mapping at index \p index.
1359 @param[in] index Index of the mapping to get from
1361 @param[out] name Returned name of the mapping at index
1363 @param[out] range_begin Returned beginning of the range
1364 (included) of the mapping at index \p
1366 @param[out] range_end Returned end of the range (included) of
1367 the mapping at index \p index.
1368 @returns 0 on success, or a negative value on error.
1370 @prenotnull{enum_field_type}
1372 @prenotnull{range_begin}
1373 @prenotnull{range_end}
1374 @preisenumft{enum_field_type}
1375 @pre The wrapped @intft of \p enum_field_type is unsigned.
1376 @pre \p index is lesser than the number of mappings contained in the
1377 enumeration field type \p enum_field_type (see
1378 bt_ctf_field_type_enumeration_get_mapping_count()).
1379 @postrefcountsame{enum_field_type}
1381 @sa bt_ctf_field_type_enumeration_get_mapping_signed(): Returns the
1382 signed mapping contained by a given enumeration field type
1385 extern int bt_ctf_field_type_enumeration_get_mapping_unsigned(
1386 struct bt_ctf_field_type
*enum_field_type
, int index
,
1387 const char **name
, uint64_t *range_begin
,
1388 uint64_t *range_end
);
1391 @brief Finds the mappings of the @enumft \p enum_field_type which
1394 This function returns an iterator on the result set of this find
1395 operation. See \ref ctfirenumftmappingiter for more details.
1397 @param[in] enum_field_type Enumeration field type of which to find
1398 the mappings named \p name.
1399 @param[in] name Name of the mappings to find in
1401 @returns @enumftiter on the set of mappings named
1402 \p name in \p enum_field_type, or
1403 \c NULL if no mappings were found or
1406 @prenotnull{enum_field_type}
1408 @preisenumft{enum_field_type}
1409 @postrefcountsame{enum_field_type}
1410 @postsuccessrefcountret1
1411 @post <strong>On success</strong>, the returned @enumftiter can iterate
1412 on at least one mapping.
1414 @sa bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): Finds
1415 the mappings of a given enumeration field type which contain
1416 a given signed value in their range.
1417 @sa bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): Finds
1418 the mappings of a given enumeration field type which contain
1419 a given unsigned value in their range.
1421 extern struct bt_ctf_field_type_enumeration_mapping_iterator
*
1422 bt_ctf_field_type_enumeration_find_mappings_by_name(
1423 struct bt_ctf_field_type
*enum_field_type
,
1427 @brief Finds the mappings of the @enumft \p enum_field_type which
1428 contain the signed value \p value in their range.
1430 This function returns an iterator on the result set of this find
1431 operation. See \ref ctfirenumftmappingiter for more details.
1433 @param[in] enum_field_type Enumeration field type of which to find
1434 the mappings which contain \p value.
1435 @param[in] value Value to find in the ranges of the
1436 mappings of \p enum_field_type.
1437 @returns @enumftiter on the set of mappings of
1438 \p enum_field_type which contain
1439 \p value in their range, or \c NULL if
1440 no mappings were found or on error.
1442 @prenotnull{enum_field_type}
1443 @preisenumft{enum_field_type}
1444 @postrefcountsame{enum_field_type}
1445 @postsuccessrefcountret1
1446 @post <strong>On success</strong>, the returned @enumftiter can iterate
1447 on at least one mapping.
1449 @sa bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
1450 mappings of a given enumeration field type which have a given
1452 @sa bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): Finds
1453 the mappings of a given enumeration field type which contain
1454 a given unsigned value in their range.
1456 extern struct bt_ctf_field_type_enumeration_mapping_iterator
*
1457 bt_ctf_field_type_enumeration_find_mappings_by_signed_value(
1458 struct bt_ctf_field_type
*enum_field_type
,
1462 @brief Finds the mappings of the @enumft \p enum_field_type which
1463 contain the unsigned value \p value in their range.
1465 This function returns an iterator on the result set of this find
1466 operation. See \ref ctfirenumftmappingiter for more details.
1468 @param[in] enum_field_type Enumeration field type of which to find
1469 the mappings which contain \p value.
1470 @param[in] value Value to find in the ranges of the
1471 mappings of \p enum_field_type.
1472 @returns @enumftiter on the set of mappings of
1473 \p enum_field_type which contain
1474 \p value in their range, or \c NULL
1475 if no mappings were found or
1478 @prenotnull{enum_field_type}
1479 @preisenumft{enum_field_type}
1480 @postrefcountsame{enum_field_type}
1481 @postsuccessrefcountret1
1482 @post <strong>On success</strong>, the returned @enumftiter can iterate
1483 on at least one mapping.
1485 @sa bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
1486 mappings of a given enumeration field type which have a given
1488 @sa bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): Finds
1489 the mappings of a given enumeration field type which contain
1490 a given unsigned value in their range.
1492 extern struct bt_ctf_field_type_enumeration_mapping_iterator
*
1493 bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(
1494 struct bt_ctf_field_type
*enum_field_type
,
1498 @brief Adds a mapping to the @enumft \p enum_field_type which maps the
1499 name \p name to the signed range \p range_begin (included) to
1500 \p range_end (included).
1502 Make \p range_begin and \p range_end the same value to add a mapping
1505 The @intft wrapped by \p enum_field_type, as returned by
1506 bt_ctf_field_type_enumeration_get_container_type(), must be
1507 \b signed to use this function.
1509 A mapping in \p enum_field_type can exist with the name \p name.
1511 @param[in] enum_field_type Enumeration field type to which to add
1513 @param[in] name Name of the mapping to add (copied
1515 @param[in] range_begin Beginning of the range of the mapping
1517 @param[in] range_end End of the range of the mapping
1519 @returns 0 on success, or a negative value on error.
1521 @prenotnull{enum_field_type}
1523 @preisenumft{enum_field_type}
1524 @pre The wrapped @intft of \p enum_field_type is signed.
1525 @pre \p range_end is greater than or equal to \p range_begin.
1526 @postrefcountsame{enum_field_type}
1528 @sa bt_ctf_field_type_enumeration_add_mapping_unsigned(): Adds an
1529 unsigned mapping to a given enumeration field type.
1531 extern int bt_ctf_field_type_enumeration_add_mapping(
1532 struct bt_ctf_field_type
*enum_field_type
, const char *name
,
1533 int64_t range_begin
, int64_t range_end
);
1536 @brief Adds a mapping to the @enumft \p enum_field_type which maps
1537 the name \p name to the unsigned
1538 range \p range_begin (included) to \p range_end (included).
1540 Make \p range_begin and \p range_end the same value to add a mapping
1543 The @intft wrapped by \p enum_field_type, as returned by
1544 bt_ctf_field_type_enumeration_get_container_type(), must be
1545 \b unsigned to use this function.
1547 A mapping in \p enum_field_type can exist with the name \p name.
1549 @param[in] enum_field_type Enumeration field type to which to add
1551 @param[in] name Name of the mapping to add (copied
1553 @param[in] range_begin Beginning of the range of the mapping
1555 @param[in] range_end End of the range of the mapping
1557 @returns 0 on success, or a negative value on error.
1559 @prenotnull{enum_field_type}
1561 @preisenumft{enum_field_type}
1562 @pre The wrapped @intft of \p enum_field_type is unsigned.
1563 @pre \p range_end is greater than or equal to \p range_begin.
1564 @postrefcountsame{enum_field_type}
1566 @sa bt_ctf_field_type_enumeration_add_mapping(): Adds a signed
1567 mapping to a given enumeration field type.
1569 extern int bt_ctf_field_type_enumeration_add_mapping_unsigned(
1570 struct bt_ctf_field_type
*enum_field_type
, const char *name
,
1571 uint64_t range_begin
, uint64_t range_end
);
1576 @defgroup ctfirenumftmappingiter CTF IR enumeration field type mapping iterator
1577 @ingroup ctfirenumfieldtype
1578 @brief CTF IR enumeration field type mapping iterator.
1581 #include <babeltrace/ctf-ir/field-types.h>
1584 A CTF IR <strong><em>enumeration field type mapping
1585 iterator</em></strong> is an iterator on @enumft mappings.
1587 You can get an enumeration mapping iterator from one of the following
1590 - Find operations of an @enumft object:
1591 - bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
1592 mappings with a given name.
1593 - bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value():
1594 Finds the mappings which contain a given unsigned value in their
1596 - bt_ctf_field_type_enumeration_find_mappings_by_signed_value():
1597 Finds the mappings which contain a given signed value in their range.
1598 - bt_ctf_field_enumeration_get_mappings(): Finds the mappings in the
1599 @enumft of an @enumfield containing its current integral value in
1602 Those functions guarantee that the returned iterator can iterate on
1603 at least one mapping. Otherwise, they return \c NULL.
1605 You can get the name and the range of a mapping iterator's current
1607 bt_ctf_field_type_enumeration_mapping_iterator_get_signed()
1609 bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(),
1610 depending on the signedness of the @intft wrapped by the
1611 @enumft. If you only need the name of the current mapping, you can
1612 use any of the two functions and set the \p range_begin and \p range_end
1613 parameters to \c NULL.
1615 You can advance an enumeration field type mapping iterator to the next
1617 bt_ctf_field_type_enumeration_mapping_iterator_next(). This
1618 function returns a negative value when you reach the end of the
1621 As with any Babeltrace object, CTF IR enumeration field type mapping
1622 iterator objects have <a
1623 href="https://en.wikipedia.org/wiki/Reference_counting">reference
1624 counts</a>. See \ref refs to learn more about the reference counting
1625 management of Babeltrace objects.
1627 @sa ctfirenumfieldtype
1629 @addtogroup ctfirenumftmappingiter
1634 @struct bt_ctf_field_type_enumeration_mapping_iterator
1635 @brief A CTF IR enumeration field type mapping iterator.
1636 @sa ctfirenumftmappingiter
1640 @brief Returns the name and the range of the current (signed) mapping
1641 of the @enumftiter \p iter.
1643 If one of \p range_begin or \p range_end is not \c NULL, the @intft
1644 wrapped by the @enumft from which \p iter was obtained, as returned by
1645 bt_ctf_field_type_enumeration_get_container_type(), must be
1646 \b signed to use this function. Otherwise, if you only need to get the
1647 name of the current mapping, set \p range_begin and \p range_end to
1650 On success, if \p name is not \c NULL, \p *name remains valid as long
1651 as \p iter exists and
1652 bt_ctf_field_type_enumeration_mapping_iterator_next() is
1653 \em not called on \p iter.
1655 @param[in] iter Enumeration field type mapping iterator
1656 of which to get the range of the current
1658 @param[out] name Returned name of the current mapping of
1659 \p iter (can be \c NULL to ignore).
1660 @param[out] range_begin Returned beginning of the range
1661 (included) of the current mapping of
1662 \p iter (can be \c NULL to ignore).
1663 @param[out] range_end Returned end of the range
1664 (included) of the current mapping of
1665 \p iter (can be \c NULL to ignore).
1666 @returns 0 on success, or a negative value on error.
1669 @postrefcountsame{iter}
1671 @sa bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned():
1672 Returns the name and the unsigned range of the current mapping
1673 of a given enumeration field type mapping iterator.
1675 extern int bt_ctf_field_type_enumeration_mapping_iterator_get_signed(
1676 struct bt_ctf_field_type_enumeration_mapping_iterator
*iter
,
1677 const char **name
, int64_t *range_begin
, int64_t *range_end
);
1680 @brief Returns the name and the range of the current (unsigned) mapping
1681 of the @enumftiter \p iter.
1683 If one of \p range_begin or \p range_end is not \c NULL, the @intft
1684 wrapped by the @enumft from which \p iter was obtained, as returned by
1685 bt_ctf_field_type_enumeration_get_container_type(), must be
1686 \b unsigned to use this function. Otherwise, if you only need to get the
1687 name of the current mapping, set \p range_begin and \p range_end to
1690 On success, if \p name is not \c NULL, \p *name remains valid as long
1691 as \p iter exists and
1692 bt_ctf_field_type_enumeration_mapping_iterator_next() is
1693 \em not called on \p iter.
1695 @param[in] iter Enumeration field type mapping iterator
1696 of which to get the range of the current
1698 @param[out] name Returned name of the current mapping of
1699 \p iter (can be \c NULL to ignore).
1700 @param[out] range_begin Returned beginning of the range
1701 (included) of the current mapping of
1702 \p iter (can be \c NULL to ignore).
1703 @param[out] range_end Returned end of the range
1704 (included) of the current mapping of
1705 \p iter (can be \c NULL to ignore).
1706 @returns 0 on success, or a negative value on error.
1709 @postrefcountsame{iter}
1712 bt_ctf_field_type_enumeration_mapping_iterator_get_signed():
1713 Returns the name and the signed range of the current mapping of
1714 a given enumeration field type mapping iterator.
1716 extern int bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(
1717 struct bt_ctf_field_type_enumeration_mapping_iterator
*iter
,
1718 const char **name
, uint64_t *range_begin
, uint64_t *range_end
);
1721 @brief Advances the @enumftiter \p iter to the next mapping.
1723 @param[in] iter Enumeration field type mapping iterator to
1725 @returns 0 on success, or a negative value on error or
1726 when you reach the end of the set.
1729 @postrefcountsame{iter}
1731 extern int bt_ctf_field_type_enumeration_mapping_iterator_next(
1732 struct bt_ctf_field_type_enumeration_mapping_iterator
*iter
);
1737 @defgroup ctfirstringfieldtype CTF IR string field type
1738 @ingroup ctfirfieldtypes
1739 @brief CTF IR string field type.
1742 #include <babeltrace/ctf-ir/field-types.h>
1745 A CTF IR <strong><em>string field type</em></strong> is a field type that
1746 you can use to create concrete @stringfields.
1748 You can create a string field type
1749 with bt_ctf_field_type_string_create().
1751 A string field type has only one property: the \b encoding of its
1752 described @stringfields. By default, the encoding of the string fields
1753 described by a string field type is #BT_CTF_STRING_ENCODING_UTF8. You
1754 can set the encoding of the string fields described by a string field
1755 type with bt_ctf_field_type_string_set_encoding().
1757 @sa ctfirstringfield
1760 @addtogroup ctfirstringfieldtype
1765 @brief Creates a default @stringft.
1767 @returns Created string field type, or \c NULL on error.
1769 @postsuccessrefcountret1
1771 extern struct bt_ctf_field_type
*bt_ctf_field_type_string_create(void);
1774 @brief Returns the encoding of the @stringfields described by
1775 the @stringft \p string_field_type.
1777 @param[in] string_field_type String field type which describes the
1778 string fields of which to get the
1780 @returns Encoding of the string
1781 fields described by \p string_field_type,
1782 or #BT_CTF_STRING_ENCODING_UNKNOWN on
1785 @prenotnull{string_field_type}
1786 @preisstringft{string_field_type}
1787 @postrefcountsame{string_field_type}
1789 @sa bt_ctf_field_type_string_set_encoding(): Sets the encoding
1790 of the string fields described by a given string field type.
1792 extern enum bt_ctf_string_encoding
bt_ctf_field_type_string_get_encoding(
1793 struct bt_ctf_field_type
*string_field_type
);
1796 @brief Sets the encoding of the @stringfields described by the
1797 @stringft \p string_field_type to \p encoding.
1799 @param[in] string_field_type String field type which describes the
1800 string fields of which to set the
1802 @param[in] encoding Encoding of the string fields described
1803 by \p string_field_type.
1804 @returns 0 on success, or a negative value on error.
1806 @prenotnull{string_field_type}
1807 @preisstringft{string_field_type}
1808 @prehot{string_field_type}
1809 @pre \p encoding is #BT_CTF_STRING_ENCODING_ASCII or
1810 #BT_CTF_STRING_ENCODING_UTF8.
1811 @postrefcountsame{string_field_type}
1813 @sa bt_ctf_field_type_string_get_encoding(): Returns the encoding of
1814 the string fields described by a given string field type.
1816 extern int bt_ctf_field_type_string_set_encoding(
1817 struct bt_ctf_field_type
*string_field_type
,
1818 enum bt_ctf_string_encoding encoding
);
1823 @defgroup ctfirstructfieldtype CTF IR structure field type
1824 @ingroup ctfirfieldtypes
1825 @brief CTF IR structure field type.
1828 #include <babeltrace/ctf-ir/field-types.h>
1831 A CTF IR <strong><em>structure field type</em></strong> is
1832 a field type that you can use to create concrete @structfields.
1834 You can create a structure field type
1835 with bt_ctf_field_type_structure_create(). This function creates
1836 an empty structure field type, with no fields.
1838 You can add a field to a structure field type with
1839 bt_ctf_field_type_structure_add_field(). Two fields in a structure
1840 field type cannot have the same name.
1842 You can set the \em minimum alignment of the structure fields described
1843 by a structure field type with the common
1844 bt_ctf_field_type_set_alignment() function. The \em effective alignment
1845 of the structure fields described by a structure field type, as per
1846 <a href="http://diamon.org/ctf/">CTF</a>, is the \em maximum value amongst
1847 the effective alignments of all its fields. Note that the effective
1848 alignment of @varfields is always 1.
1850 You can set the byte order of <em>all the contained fields</em>,
1851 recursively, of a structure field type with the common
1852 bt_ctf_field_type_set_byte_order() function.
1854 @sa ctfirstructfield
1857 @addtogroup ctfirstructfieldtype
1862 @brief Creates a default, empty @structft.
1864 @returns Created structure field type,
1865 or \c NULL on error.
1867 @postsuccessrefcountret1
1869 extern struct bt_ctf_field_type
*bt_ctf_field_type_structure_create(void);
1872 @brief Returns the number of fields contained in the
1873 @structft \p struct_field_type.
1875 @param[in] struct_field_type Structure field type of which to get
1876 the number of contained fields.
1877 @returns Number of fields contained in
1878 \p struct_field_type, or a negative
1881 @prenotnull{struct_field_type}
1882 @preisstructft{struct_field_type}
1883 @postrefcountsame{struct_field_type}
1885 extern int bt_ctf_field_type_structure_get_field_count(
1886 struct bt_ctf_field_type
*struct_field_type
);
1889 @brief Returns the field of the @structft \p struct_field_type
1892 On success, the field's type is placed in \p *field_type if
1893 \p field_type is not \c NULL. The field's name is placed in
1894 \p *field_name if \p field_name is not \c NULL.
1895 \p struct_field_type remains the sole owner of \p *field_name.
1897 @param[in] struct_field_type Structure field type of which to get
1898 the field at index \p index.
1899 @param[out] field_name Returned name of the field at index
1900 \p index (can be \c NULL).
1901 @param[out] field_type Returned field type of the field
1902 at index \p index (can be \c NULL).
1903 @param[in] index Index of the field to get from
1904 \p struct_field_type.
1905 @returns 0 on success, or a negative value on error.
1907 @prenotnull{struct_field_type}
1908 @preisstructft{struct_field_type}
1909 @pre \p index is lesser than the number of fields contained in the
1910 structure field type \p struct_field_type (see
1911 bt_ctf_field_type_structure_get_field_count()).
1912 @postrefcountsame{struct_field_type}
1913 @post <strong>On success</strong>, the returned field's type is placed
1914 in \p *field_type and its reference count is incremented.
1916 @sa bt_ctf_field_type_structure_get_field_type_by_name(): Finds a
1917 structure field type's field by name.
1919 extern int bt_ctf_field_type_structure_get_field(
1920 struct bt_ctf_field_type
*struct_field_type
,
1921 const char **field_name
, struct bt_ctf_field_type
**field_type
,
1925 @brief Returns the type of the field named \p field_name found in
1926 the @structft \p struct_field_type.
1928 @param[in] struct_field_type Structure field type of which to get
1930 @param[in] field_name Name of the field to find.
1931 @returns Type of the field named \p field_name in
1932 \p struct_field_type, or
1935 @prenotnull{struct_field_type}
1936 @prenotnull{field_name}
1937 @preisstructft{struct_field_type}
1938 @postrefcountsame{struct_field_type}
1939 @postsuccessrefcountretinc
1941 @sa bt_ctf_field_type_structure_get_field(): Finds a
1942 structure field type's field by index.
1945 struct bt_ctf_field_type
*bt_ctf_field_type_structure_get_field_type_by_name(
1946 struct bt_ctf_field_type
*struct_field_type
,
1947 const char *field_name
);
1950 @brief Adds a field named \p field_name with the @ft
1951 \p field_type to the @structft \p struct_field_type.
1953 On success, \p field_type becomes the child of \p struct_field_type.
1955 This function adds the new field after the current last field of
1956 \p struct_field_type (append mode).
1958 You \em cannot add a field named \p field_name if there's already a
1959 field named \p field_name in \p struct_field_type.
1961 @param[in] struct_field_type Structure field type to which to add
1963 @param[in] field_type Field type of the field to add to
1964 \p struct_field_type.
1965 @param[in] field_name Name of the field to add to
1966 \p struct_field_type
1967 (copied on success).
1968 @returns 0 on success, or a negative value on error.
1970 @prenotnull{struct_field_type}
1971 @prenotnull{field_type}
1972 @prenotnull{field_name}
1973 @preisstructft{struct_field_type}
1974 @pre \p field_type is not and does not contain \p struct_field_type,
1975 recursively, as a field's type.
1976 @prehot{struct_field_type}
1977 @postrefcountsame{struct_field_type}
1978 @postsuccessrefcountinc{field_type}
1980 extern int bt_ctf_field_type_structure_add_field(
1981 struct bt_ctf_field_type
*struct_field_type
,
1982 struct bt_ctf_field_type
*field_type
,
1983 const char *field_name
);
1988 @defgroup ctfirarrayfieldtype CTF IR array field type
1989 @ingroup ctfirfieldtypes
1990 @brief CTF IR array field type.
1993 #include <babeltrace/ctf-ir/field-types.h>
1996 A CTF IR <strong><em>array field type</em></strong> is a field type that
1997 you can use to create concrete @arrayfields.
1999 You can create an array field type
2000 with bt_ctf_field_type_array_create(). This function needs
2001 the @ft of the fields contained by the array fields described by the
2002 array field type to create.
2007 @addtogroup ctfirarrayfieldtype
2012 @brief Creates a default @arrayft with
2013 \p element_field_type as the field type of the fields contained
2014 in its described @arrayfields of length \p length.
2016 @param[in] element_field_type Field type of the fields contained in
2017 the array fields described by the
2018 created array field type.
2019 @param[in] length Length of the array fields described by
2020 the created array field type.
2021 @returns Created array field type, or
2024 @prenotnull{element_field_type}
2025 @postsuccessrefcountinc{element_field_type}
2026 @postsuccessrefcountret1
2028 extern struct bt_ctf_field_type
*bt_ctf_field_type_array_create(
2029 struct bt_ctf_field_type
*element_field_type
,
2030 unsigned int length
);
2033 @brief Returns the @ft of the @fields contained in
2034 the @arrayfields described by the @arrayft \p array_field_type.
2036 @param[in] array_field_type Array field type of which to get
2037 the type of the fields contained in its
2038 described array fields.
2039 @returns Type of the fields contained in the
2040 array fields described by
2041 \p array_field_type, or \c NULL
2044 @prenotnull{array_field_type}
2045 @preisarrayft{array_field_type}
2046 @postrefcountsame{array_field_type}
2047 @postsuccessrefcountretinc
2049 extern struct bt_ctf_field_type
*bt_ctf_field_type_array_get_element_type(
2050 struct bt_ctf_field_type
*array_field_type
);
2053 @brief Returns the number of @fields contained in the
2054 @arrayfields described by the @arrayft \p array_field_type.
2056 @param[in] array_field_type Array field type of which to get
2057 the number of fields contained in its
2058 described array fields.
2059 @returns Number of fields contained in the
2060 array fields described by
2061 \p array_field_type, or a negative value
2064 @prenotnull{array_field_type}
2065 @preisarrayft{array_field_type}
2066 @postrefcountsame{array_field_type}
2068 extern int64_t bt_ctf_field_type_array_get_length(
2069 struct bt_ctf_field_type
*array_field_type
);
2074 @defgroup ctfirseqfieldtype CTF IR sequence field type
2075 @ingroup ctfirfieldtypes
2076 @brief CTF IR sequence field type.
2079 #include <babeltrace/ctf-ir/field-types.h>
2082 A CTF IR <strong><em>sequence field type</em></strong> is
2083 a field type that you can use to create concrete @seqfields.
2085 You can create a sequence field type with
2086 bt_ctf_field_type_sequence_create(). This function needs the @ft
2087 of the fields contained by the sequence fields described by the created
2088 sequence field type. This function also needs the length name of the
2089 sequence field type to create. The length name is used to automatically
2090 resolve the length's field type. See \ref ctfirfieldtypes to learn more
2091 about the automatic resolving.
2096 @addtogroup ctfirseqfieldtype
2101 @brief Creates a default @seqft with \p element_field_type as the
2102 @ft of the @fields contained in its described @seqfields
2103 with the length name \p length_name.
2105 \p length_name can be an absolute or relative reference. See
2106 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2108 @param[in] element_field_type Field type of the fields contained in
2109 the sequence fields described by the
2110 created sequence field type.
2111 @param[in] length_name Length name (copied on success).
2112 @returns Created array field type, or
2115 @prenotnull{element_field_type}
2116 @prenotnull{length_name}
2117 @postsuccessrefcountinc{element_field_type}
2118 @postsuccessrefcountret1
2120 extern struct bt_ctf_field_type
*bt_ctf_field_type_sequence_create(
2121 struct bt_ctf_field_type
*element_field_type
,
2122 const char *length_name
);
2125 @brief Returns the @ft of the @fields contained in the @seqft
2126 described by the @seqft \p sequence_field_type.
2128 @param[in] sequence_field_type Sequence field type of which to get
2129 the type of the fields contained in its
2130 described sequence fields.
2131 @returns Type of the fields contained in the
2132 sequence fields described by
2133 \p sequence_field_type, or \c NULL
2136 @prenotnull{sequence_field_type}
2137 @preisseqft{sequence_field_type}
2138 @postrefcountsame{sequence_field_type}
2139 @postsuccessrefcountretinc
2141 extern struct bt_ctf_field_type
*bt_ctf_field_type_sequence_get_element_type(
2142 struct bt_ctf_field_type
*sequence_field_type
);
2145 @brief Returns the length name of the @seqft \p sequence_field_type.
2147 On success, \p sequence_field_type remains the sole owner of
2148 the returned string.
2150 @param[in] sequence_field_type Sequence field type of which to get the
2152 @returns Length name of \p sequence_field_type,
2153 or \c NULL on error.
2155 @prenotnull{sequence_field_type}
2156 @preisseqft{sequence_field_type}
2158 @sa bt_ctf_field_type_sequence_get_length_field_path(): Returns the
2159 length's CTF IR field path of a given sequence field type.
2161 extern const char *bt_ctf_field_type_sequence_get_length_field_name(
2162 struct bt_ctf_field_type
*sequence_field_type
);
2165 @brief Returns the length's CTF IR field path of the @seqft
2166 \p sequence_field_type.
2168 The length's field path of a sequence field type is set when automatic
2169 resolving is performed (see \ref ctfirfieldtypes).
2171 @param[in] sequence_field_type Sequence field type of which to get the
2172 length's field path.
2173 @returns Length's field path of
2174 \p sequence_field_type, or
2175 \c NULL if the length's field path is
2176 not set yet is not set or on error.
2178 @prenotnull{sequence_field_type}
2179 @preisseqft{sequence_field_type}
2180 @postsuccessrefcountretinc
2182 @sa bt_ctf_field_type_sequence_get_length_field_name(): Returns the
2183 length's name of a given sequence field type.
2185 extern struct bt_ctf_field_path
*bt_ctf_field_type_sequence_get_length_field_path(
2186 struct bt_ctf_field_type
*sequence_field_type
);
2191 @defgroup ctfirvarfieldtype CTF IR variant field type
2192 @ingroup ctfirfieldtypes
2193 @brief CTF IR variant field type.
2196 #include <babeltrace/ctf-ir/field-types.h>
2199 A CTF IR <strong><em>variant field type</em></strong> is
2200 a field type that you can use to create concrete @varfields.
2202 You can create a variant field type with
2203 bt_ctf_field_type_variant_create(). This function expects you to pass
2204 both the tag's @enumft and the tag name of the variant field type to
2205 create. The tag's field type is optional, as the Babeltrace system can
2206 automatically resolve it using the tag name. You can leave the tag name
2207 to \c NULL initially, and set it later with
2208 bt_ctf_field_type_variant_set_tag_name(). The tag name must be set when
2209 the variant field type is frozen. See \ref ctfirfieldtypes to learn more
2210 about the automatic resolving and the conditions under which a field
2213 You can add a field to a variant field type with
2214 bt_ctf_field_type_variant_add_field(). All the field names of a
2215 variant field type \em must exist as mapping names in its tag's @enumft.
2217 The effective alignment of the @varfields described by a
2218 variant field type is always 1, but the individual fields of a
2219 @varfield can have custom alignments.
2221 You can set the byte order of <em>all the contained fields</em>,
2222 recursively, of a variant field type with the common
2223 bt_ctf_field_type_set_byte_order() function.
2228 @addtogroup ctfirvarfieldtype
2233 @brief Creates a default, empty @varft with the tag's @enumft
2234 \p tag_field_type and the tag name \p tag_name.
2236 \p tag_field_type can be \c NULL; the tag's field type can be
2237 automatically resolved from the variant field type's tag name (see
2238 \ref ctfirfieldtypes). If \p tag_name is \c NULL, it \em must be set
2239 with bt_ctf_field_type_variant_set_tag_name() \em before the variant
2240 field type is frozen.
2242 \p tag_name can be an absolute or relative reference. See
2243 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2245 @param[in] tag_field_type Tag's enumeration field type
2247 @param[in] tag_name Tag name (copied on success,
2249 @returns Created variant field type, or
2252 @pre \p tag_field_type is an enumeration field type or \c NULL.
2253 @post <strong>On success, if \p tag_field_type is not \c NULL</strong>,
2254 its reference count is incremented.
2255 @postsuccessrefcountret1
2257 extern struct bt_ctf_field_type
*bt_ctf_field_type_variant_create(
2258 struct bt_ctf_field_type
*tag_field_type
,
2259 const char *tag_name
);
2262 @brief Returns the tag's @enumft of the @varft \p variant_field_type.
2264 @param[in] variant_field_type Variant field type of which to get
2265 the tag's enumeration field type.
2266 @returns Tag's enumeration field type of
2267 \p variant_field_type, or \c NULL if the
2268 tag's field type is not set or on
2271 @prenotnull{variant_field_type}
2272 @preisvarft{variant_field_type}
2273 @postrefcountsame{variant_field_type}
2274 @postsuccessrefcountretinc
2276 extern struct bt_ctf_field_type
*bt_ctf_field_type_variant_get_tag_type(
2277 struct bt_ctf_field_type
*variant_field_type
);
2280 @brief Returns the tag name of the @varft \p variant_field_type.
2282 On success, \p variant_field_type remains the sole owner of
2283 the returned string.
2285 @param[in] variant_field_type Variant field type of which to get the
2287 @returns Tag name of \p variant_field_type, or
2288 \c NULL if the tag name is not set or
2291 @prenotnull{variant_field_type}
2292 @preisvarft{variant_field_type}
2294 @sa bt_ctf_field_type_variant_set_tag_name(): Sets the tag name of
2295 a given variant field type.
2296 @sa bt_ctf_field_type_variant_get_tag_field_path(): Returns the tag's
2297 CTF IR field path of a given variant field type.
2299 extern const char *bt_ctf_field_type_variant_get_tag_name(
2300 struct bt_ctf_field_type
*variant_field_type
);
2303 @brief Sets the tag name of the @varft \p variant_field_type.
2305 \p tag_name can be an absolute or relative reference. See
2306 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2308 @param[in] variant_field_type Variant field type of which to set
2310 @param[in] tag_name Tag name of \p variant_field_type
2311 (copied on success).
2312 @returns 0 on success, or a negative value on error.
2314 @prenotnull{variant_field_type}
2316 @prehot{variant_field_type}
2317 @postrefcountsame{variant_field_type}
2319 @sa bt_ctf_field_type_variant_get_tag_name(): Returns the tag name of
2320 a given variant field type.
2322 extern int bt_ctf_field_type_variant_set_tag_name(
2323 struct bt_ctf_field_type
*variant_field_type
,
2324 const char *tag_name
);
2327 @brief Returns the tag's CTF IR field path of the @varft
2328 \p variant_field_type.
2330 The tag's field path of a variant field type is set when automatic
2331 resolving is performed (see \ref ctfirfieldtypes).
2333 @param[in] variant_field_type Variant field type of which to get the
2335 @returns Tag's field path of
2336 \p variant_field_type, or
2337 \c NULL if the tag's field path is not
2338 set yet is not set or on error.
2340 @prenotnull{variant_field_type}
2341 @preisvarft{variant_field_type}
2342 @postsuccessrefcountretinc
2344 @sa bt_ctf_field_type_variant_get_tag_name(): Returns the tag's
2345 name of a given variant field type.
2347 extern struct bt_ctf_field_path
*bt_ctf_field_type_variant_get_tag_field_path(
2348 struct bt_ctf_field_type
*variant_field_type
);
2351 @brief Returns the number of fields (choices) contained in the @varft
2352 \p variant_field_type.
2354 @param[in] variant_field_type Variant field type of which to get
2355 the number of contained fields.
2356 @returns Number of fields contained in
2357 \p variant_field_type, or a negative
2360 @prenotnull{variant_field_type}
2361 @preisvarft{variant_field_type}
2362 @postrefcountsame{variant_field_type}
2364 extern int bt_ctf_field_type_variant_get_field_count(
2365 struct bt_ctf_field_type
*variant_field_type
);
2368 @brief Returns the field (choice) of the @varft \p variant_field_type
2371 On success, the field's type is placed in \p *field_type if
2372 \p field_type is not \c NULL. The field's name is placed in
2373 \p *field_name if \p field_name is not \c NULL.
2374 \p variant_field_type remains the sole owner of \p *field_name.
2376 @param[in] variant_field_type Variant field type of which to get
2377 the field at index \p index.
2378 @param[out] field_name Returned name of the field at index
2379 \p index (can be \c NULL).
2380 @param[out] field_type Returned field type of the field
2381 at index \p index (can be \c NULL).
2382 @param[in] index Index of the field to get from
2383 \p variant_field_type.
2384 @returns 0 on success, or a negative value on error.
2386 @prenotnull{variant_field_type}
2387 @preisvarft{variant_field_type}
2388 @pre \p index is lesser than the number of fields contained in the
2389 variant field type \p variant_field_type (see
2390 bt_ctf_field_type_variant_get_field_count()).
2391 @postrefcountsame{variant_field_type}
2392 @post <strong>On success</strong>, the returned field's type is placed
2393 in \p *field_type and its reference count is incremented.
2395 @sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant
2396 field type's field by name.
2397 @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant
2398 field type's field by current tag value.
2400 extern int bt_ctf_field_type_variant_get_field(
2401 struct bt_ctf_field_type
*variant_field_type
,
2402 const char **field_name
,
2403 struct bt_ctf_field_type
**field_type
, int index
);
2406 @brief Returns the type of the field (choice) named \p field_name
2407 found in the @varft \p variant_field_type.
2409 @param[in] variant_field_type Variant field type of which to get
2411 @param[in] field_name Name of the field to find.
2412 @returns Type of the field named \p field_name in
2413 \p variant_field_type, or
2416 @prenotnull{variant_field_type}
2417 @prenotnull{field_name}
2418 @preisvarft{variant_field_type}
2419 @postrefcountsame{variant_field_type}
2420 @postsuccessrefcountretinc
2422 @sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's
2424 @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant
2425 field type's field by current tag value.
2428 struct bt_ctf_field_type
*bt_ctf_field_type_variant_get_field_type_by_name(
2429 struct bt_ctf_field_type
*variant_field_type
,
2430 const char *field_name
);
2433 @brief Returns the type of the field (choice) selected by the value of
2434 the @enumfield \p tag_field in the @varft \p variant_field_type.
2436 \p tag_field is the current tag value.
2438 The field type of \p tag_field, as returned by bt_ctf_field_get_type(),
2439 \em must be equivalent to the field type returned by
2440 bt_ctf_field_type_variant_get_tag_type() for \p variant_field_type.
2442 @param[in] variant_field_type Variant field type of which to get
2444 @param[in] tag_field Current tag value (variant field type's
2446 @returns Type of the field selected by
2447 \p tag_field in \p variant_field_type,
2448 or \c NULL on error.
2450 @prenotnull{variant_field_type}
2451 @prenotnull{tag_field}
2452 @preisvarft{variant_field_type}
2453 @preisenumfield{tag_field}
2454 @postrefcountsame{variant_field_type}
2455 @postrefcountsame{tag_field}
2456 @postsuccessrefcountretinc
2458 @sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's
2460 @sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant
2461 field type's field by name.
2464 struct bt_ctf_field_type
*bt_ctf_field_type_variant_get_field_type_from_tag(
2465 struct bt_ctf_field_type
*variant_field_type
,
2466 struct bt_ctf_field
*tag_field
);
2469 @brief Adds a field (a choice) named \p field_name with the @ft
2470 \p field_type to the @varft \p variant_field_type.
2472 On success, \p field_type becomes the child of \p variant_field_type.
2474 You \em cannot add a field named \p field_name if there's already a
2475 field named \p field_name in \p variant_field_type.
2477 \p field_name \em must name an existing mapping in the tag's
2478 enumeration field type of \p variant_field_type.
2480 @param[in] variant_field_type Variant field type to which to add
2482 @param[in] field_type Field type of the field to add to
2483 \p variant_field_type.
2484 @param[in] field_name Name of the field to add to
2485 \p variant_field_type
2486 (copied on success).
2487 @returns 0 on success, or a negative value on error.
2489 @prenotnull{variant_field_type}
2490 @prenotnull{field_type}
2491 @prenotnull{field_name}
2492 @preisvarft{variant_field_type}
2493 @pre \p field_type is not and does not contain \p variant_field_type,
2494 recursively, as a field's type.
2495 @prehot{variant_field_type}
2496 @postrefcountsame{variant_field_type}
2497 @postsuccessrefcountinc{field_type}
2499 extern int bt_ctf_field_type_variant_add_field(
2500 struct bt_ctf_field_type
*variant_field_type
,
2501 struct bt_ctf_field_type
*field_type
,
2502 const char *field_name
);
2510 #endif /* BABELTRACE_CTF_IR_FIELD_TYPES_H */