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
33 #include <babeltrace/types.h>
42 @defgroup ctfirfieldtypes CTF IR field types
44 @brief CTF IR field types.
47 #include <babeltrace/ctf-ir/field-types.h>
50 A CTF IR <strong><em>field type</em></strong> is a field type that you
51 can use to create concrete @fields.
53 You can create a @field object from a CTF IR field type object
54 with bt_ctf_field_create().
56 In the CTF IR hierarchy, you can set the root field types of three
59 - \ref ctfirtraceclass
60 - Trace packet header field type: bt_ctf_trace_set_packet_header_type().
61 - \ref ctfirstreamclass
62 - Stream packet context field type:
63 bt_ctf_stream_class_set_packet_context_type().
64 - Stream event header field type:
65 bt_ctf_stream_class_set_event_header_type().
66 - Stream event context field type:
67 bt_ctf_stream_class_set_event_context_type().
68 - \ref ctfireventclass
69 - Event context field type: bt_ctf_event_class_set_context_type().
70 - Event payload field type: bt_ctf_event_class_set_payload_type().
72 As of Babeltrace \btversion, those six previous "root" field types
73 \em must be @structft objects.
75 If, at any level within a given root field type, you add a @seqft or a
76 @varft, you do not need to specify its associated length
77 or tag field type: the length or tag string is enough for the Babeltrace
78 system to resolve the needed field type depending on where this
79 dynamic field type is located within the whole hierarchy. It is
80 guaranteed that this automatic resolving is performed for all the field
81 types contained in a given
82 \link ctfirstreamclass CTF IR stream class\endlink (and in its
83 children \link ctfireventclass CTF IR event classes\endlink) once you
84 add it to a \link ctfirtraceclass CTF IR trace class\endlink with
85 bt_ctf_trace_add_stream_class(). Once a stream class is the child of
86 a trace class, this automatic resolving is performed for the field
87 types of an event class when you add it with
88 bt_ctf_stream_class_add_event_class(). If the system cannot find a path
89 to a field in the hierarchy for a dynamic field type, the adding
92 The standard CTF field types are:
98 <th>CTF IR field which you can create from this field type
101 <td>#BT_CTF_FIELD_TYPE_ID_INTEGER
102 <td>\ref ctfirintfieldtype
103 <td>\ref ctfirintfield
106 <td>#BT_CTF_FIELD_TYPE_ID_FLOAT
107 <td>\ref ctfirfloatfieldtype
108 <td>\ref ctfirfloatfield
111 <td>#BT_CTF_FIELD_TYPE_ID_ENUM
112 <td>\ref ctfirenumfieldtype
113 <td>\ref ctfirenumfield
116 <td>#BT_CTF_FIELD_TYPE_ID_STRING
117 <td>\ref ctfirstringfieldtype
118 <td>\ref ctfirstringfield
121 <td>#BT_CTF_FIELD_TYPE_ID_STRUCT
122 <td>\ref ctfirstructfieldtype
123 <td>\ref ctfirstructfield
126 <td>#BT_CTF_FIELD_TYPE_ID_ARRAY
127 <td>\ref ctfirarrayfieldtype
128 <td>\ref ctfirarrayfield
131 <td>#BT_CTF_FIELD_TYPE_ID_SEQUENCE
132 <td>\ref ctfirseqfieldtype
133 <td>\ref ctfirseqfield
136 <td>#BT_CTF_FIELD_TYPE_ID_VARIANT
137 <td>\ref ctfirvarfieldtype
138 <td>\ref ctfirvarfield
142 Each field type has its own <strong>type ID</strong> (see
143 #bt_ctf_field_type_id). You get the type ID of a field type object
144 with bt_ctf_field_type_get_type_id().
146 You can get a deep copy of a field type with bt_ctf_field_type_copy().
147 This function resets, in the field type copy, the resolved field type
148 of the dynamic field types. The automatic resolving can be done again
149 when you eventually call bt_ctf_event_create(),
150 bt_ctf_stream_class_add_event_class(), or
151 bt_ctf_trace_add_stream_class().
153 You \em must always use bt_ctf_field_type_compare() to compare two
154 field types. Since some parts of the Babeltrace system can copy field
155 types behind the scenes, you \em cannot rely on a simple field type
158 As with any Babeltrace object, CTF IR field type objects have
159 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
160 counts</a>. See \ref refs to learn more about the reference counting
161 management of Babeltrace objects.
163 The following functions can \em freeze field type objects:
165 - bt_ctf_field_create() freezes its field type parameter.
166 - bt_ctf_stream_class_add_event_class(), if its
167 \link ctfirstreamclass CTF IR stream class\endlink parameter has a
168 \link ctfirtraceclass CTF IR trace class\endlink parent, freezes
169 the root field types of its
170 \link ctfireventclass CTF IR event class\endlink parameter.
171 - bt_ctf_trace_add_stream_class() freezes the root field types of the
172 whole trace class hierarchy (trace class, children stream classes,
173 and their children event classes).
174 - bt_ctf_writer_create_stream() freezes the root field types of the
175 whole CTF writer's trace class hierarchy.
176 - bt_ctf_event_create() freezes the root field types of its event class
177 parameter and of ther parent stream class of this event class.
179 You cannot modify a frozen field type object: it is considered
180 immutable, except for \link refs reference counting\endlink.
183 @sa \ref ctfirfieldtypesexamples "Examples"
186 @brief CTF IR field types type and functions.
189 @addtogroup ctfirfieldtypes
194 @struct bt_ctf_field_type
195 @brief A CTF IR field type.
198 struct bt_ctf_field_type
;
199 struct bt_ctf_event_class
;
202 struct bt_ctf_field_path
;
203 struct bt_ctf_field_type_enumeration_mapping_iterator
;
205 /** @cond DOCUMENT */
208 * Babeltrace 1.x enumerations that were also used in CTF writer's API.
209 * They are left here for backward compatibility reasons, but
210 * enum bt_ctf_field_type_id and enum bt_ctf_string_encoding should be used
211 * in new code. Both new enumerations are compatible with their legacy
215 CTF_TYPE_UNKNOWN
= -1,
216 CTF_TYPE_INTEGER
= 0,
221 CTF_TYPE_UNTAGGED_VARIANT
= 5,
222 CTF_TYPE_VARIANT
= 5,
224 CTF_TYPE_SEQUENCE
= 7,
231 enum ctf_string_encoding
{
244 /// Unknown, used for errors.
245 BT_CTF_SCOPE_UNKNOWN
= -1,
247 /// Trace packet header.
248 BT_CTF_SCOPE_TRACE_PACKET_HEADER
= 1,
250 /// Stream packet context.
251 BT_CTF_SCOPE_STREAM_PACKET_CONTEXT
= 2,
253 /// Stream event header.
254 BT_CTF_SCOPE_STREAM_EVENT_HEADER
= 3,
256 /// Stream event context.
257 BT_CTF_SCOPE_STREAM_EVENT_CONTEXT
= 4,
260 BT_CTF_SCOPE_EVENT_CONTEXT
= 5,
263 BT_CTF_SCOPE_EVENT_PAYLOAD
= 6,
266 BT_CTF_SCOPE_ENV
= 0,
267 BT_CTF_SCOPE_EVENT_FIELDS
= 6,
272 @name Type information
277 @brief Type ID of a @ft.
279 enum bt_ctf_field_type_id
{
280 /// Unknown, used for errors.
281 BT_CTF_FIELD_TYPE_ID_UNKNOWN
= CTF_TYPE_UNKNOWN
,
283 /// \ref ctfirintfieldtype
284 BT_CTF_FIELD_TYPE_ID_INTEGER
= CTF_TYPE_INTEGER
,
286 /// \ref ctfirfloatfieldtype
287 BT_CTF_FIELD_TYPE_ID_FLOAT
= CTF_TYPE_FLOAT
,
289 /// \ref ctfirenumfieldtype
290 BT_CTF_FIELD_TYPE_ID_ENUM
= CTF_TYPE_ENUM
,
292 /// \ref ctfirstringfieldtype
293 BT_CTF_FIELD_TYPE_ID_STRING
= CTF_TYPE_STRING
,
295 /// \ref ctfirstructfieldtype
296 BT_CTF_FIELD_TYPE_ID_STRUCT
= CTF_TYPE_STRUCT
,
298 /// \ref ctfirarrayfieldtype
299 BT_CTF_FIELD_TYPE_ID_ARRAY
= CTF_TYPE_ARRAY
,
301 /// \ref ctfirseqfieldtype
302 BT_CTF_FIELD_TYPE_ID_SEQUENCE
= CTF_TYPE_SEQUENCE
,
304 /// \ref ctfirvarfieldtype
305 BT_CTF_FIELD_TYPE_ID_VARIANT
= CTF_TYPE_VARIANT
,
307 /// Number of enumeration entries.
308 BT_CTF_NR_TYPE_IDS
= NR_CTF_TYPES
,
312 @brief Returns the type ID of the @ft \p field_type.
314 @param[in] field_type Field type of which to get the type ID.
315 @returns Type ID of \p field_type,
316 or #BT_CTF_FIELD_TYPE_ID_UNKNOWN on error.
318 @prenotnull{field_type}
319 @postrefcountsame{field_type}
321 @sa #bt_ctf_field_type_id: CTF IR field type ID.
322 @sa bt_ctf_field_type_is_integer(): Returns whether or not a given
323 field type is a @intft.
324 @sa bt_ctf_field_type_is_floating_point(): Returns whether or not a
325 given field type is a @floatft.
326 @sa bt_ctf_field_type_is_enumeration(): Returns whether or not a given
327 field type is a @enumft.
328 @sa bt_ctf_field_type_is_string(): Returns whether or not a given
329 field type is a @stringft.
330 @sa bt_ctf_field_type_is_structure(): Returns whether or not a given
331 field type is a @structft.
332 @sa bt_ctf_field_type_is_array(): Returns whether or not a given
333 field type is a @arrayft.
334 @sa bt_ctf_field_type_is_sequence(): Returns whether or not a given
335 field type is a @seqft.
336 @sa bt_ctf_field_type_is_variant(): Returns whether or not a given
337 field type is a @varft.
339 extern enum bt_ctf_field_type_id
bt_ctf_field_type_get_type_id(
340 struct bt_ctf_field_type
*field_type
);
343 @brief Returns whether or not the @ft \p field_type is a @intft.
345 @param[in] field_type Field type to check (can be \c NULL).
346 @returns #BT_TRUE if \p field_type is an integer field type,
347 or #BT_FALSE otherwise (including if \p field_type is
350 @prenotnull{field_type}
351 @postrefcountsame{field_type}
353 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
356 extern bt_bool
bt_ctf_field_type_is_integer(
357 struct bt_ctf_field_type
*field_type
);
360 @brief Returns whether or not the @ft \p field_type is a @floatft.
362 @param[in] field_type Field type to check (can be \c NULL).
363 @returns #BT_TRUE if \p field_type is a floating point
364 #BT_FALSE field type,
365 or 0 otherwise (including if \p field_type is
368 @postrefcountsame{field_type}
370 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
373 extern bt_bool
bt_ctf_field_type_is_floating_point(
374 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 #BT_TRUE if \p field_type is an enumeration field type,
381 or #BT_FALSE 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 bt_bool
bt_ctf_field_type_is_enumeration(
390 struct bt_ctf_field_type
*field_type
);
393 @brief Returns whether or not the @ft \p field_type is a @stringft.
395 @param[in] field_type Field type to check (can be \c NULL).
396 @returns #BT_TRUE if \p field_type is a string field type,
397 or #BT_FALSE otherwise (including if \p field_type is
400 @postrefcountsame{field_type}
402 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
405 extern bt_bool
bt_ctf_field_type_is_string(
406 struct bt_ctf_field_type
*field_type
);
409 @brief Returns whether or not the @ft \p field_type is a @structft.
411 @param[in] field_type Field type to check (can be \c NULL).
412 @returns #BT_TRUE if \p field_type is a structure field type,
413 or #BT_FALSE otherwise (including if \p field_type is
416 @postrefcountsame{field_type}
418 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
421 extern bt_bool
bt_ctf_field_type_is_structure(
422 struct bt_ctf_field_type
*field_type
);
425 @brief Returns whether or not the @ft \p field_type is a @arrayft.
427 @param[in] field_type Field type to check (can be \c NULL).
428 @returns #BT_TRUE if \p field_type is an array field type,
429 or #BT_FALSE otherwise (including if \p field_type is
432 @postrefcountsame{field_type}
434 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
437 extern bt_bool
bt_ctf_field_type_is_array(
438 struct bt_ctf_field_type
*field_type
);
441 @brief Returns whether or not the @ft \p field_type is a @seqft.
443 @param[in] field_type Field type to check (can be \c NULL).
444 @returns #BT_TRUE if \p field_type is a sequence field type,
445 or #BT_FALSE otherwise (including if \p field_type is
448 @postrefcountsame{field_type}
450 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
453 extern bt_bool
bt_ctf_field_type_is_sequence(
454 struct bt_ctf_field_type
*field_type
);
457 @brief Returns whether or not the @ft \p field_type is a @varft.
459 @param[in] field_type Field type to check (can be \c NULL).
460 @returns #BT_TRUE if \p field_type is a variant field type,
461 or #BT_FALSE otherwise (including if \p field_type is
464 @postrefcountsame{field_type}
466 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
469 extern bt_bool
bt_ctf_field_type_is_variant(
470 struct bt_ctf_field_type
*field_type
);
475 @name Common properties types and functions
480 @brief <a href="https://en.wikipedia.org/wiki/Endianness">Byte order</a>
483 enum bt_ctf_byte_order
{
484 /// Unknown, used for errors.
485 BT_CTF_BYTE_ORDER_UNKNOWN
= -1,
488 * Note that native, in the context of the CTF specification, is defined
489 * as "the byte order described in the trace" and does not mean that the
490 * host's endianness will be used.
492 /// Native (default) byte order.
493 BT_CTF_BYTE_ORDER_NATIVE
= 0,
496 Unspecified byte order; the initial native byte order of a
497 \link ctfirtraceclass CTF IR trace class\endlink.
499 BT_CTF_BYTE_ORDER_UNSPECIFIED
,
502 BT_CTF_BYTE_ORDER_LITTLE_ENDIAN
,
505 BT_CTF_BYTE_ORDER_BIG_ENDIAN
,
507 /// Network byte order (big-endian).
508 BT_CTF_BYTE_ORDER_NETWORK
,
512 @brief String encoding of a @ft.
514 enum bt_ctf_string_encoding
{
515 /// Unknown, used for errors.
516 BT_CTF_STRING_ENCODING_UNKNOWN
= CTF_STRING_UNKNOWN
,
519 BT_CTF_STRING_ENCODING_NONE
= CTF_STRING_NONE
,
521 /// <a href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a>.
522 BT_CTF_STRING_ENCODING_UTF8
= CTF_STRING_UTF8
,
524 /// <a href="https://en.wikipedia.org/wiki/ASCII">ASCII</a>.
525 BT_CTF_STRING_ENCODING_ASCII
= CTF_STRING_ASCII
,
529 @brief Returns the alignment of the @fields described by
530 the @ft \p field_type.
532 @param[in] field_type Field type which describes the
533 fields of which to get the alignment.
534 @returns Alignment of the fields described by
535 \p field_type, or a negative value on error.
537 @prenotnull{field_type}
538 @postrefcountsame{field_type}
540 @sa bt_ctf_field_type_set_alignment(): Sets the alignment
541 of the fields described by a given field type.
543 extern int bt_ctf_field_type_get_alignment(
544 struct bt_ctf_field_type
*field_type
);
547 @brief Sets the alignment of the @fields described by the
548 @ft \p field_type to \p alignment.
550 \p alignment \em must be greater than 0 and a power of two.
552 @param[in] field_type Field type which describes the fields of
553 which to set the alignment.
554 @param[in] alignment Alignment of the fields described by
556 @returns 0 on success, or a negative value on error.
558 @prenotnull{field_type}
560 @pre \p alignment is greater than 0 and a power of two.
561 @postrefcountsame{field_type}
563 @sa bt_ctf_field_type_get_alignment(): Returns the alignment of the
564 fields described by a given field type.
566 extern int bt_ctf_field_type_set_alignment(struct bt_ctf_field_type
*field_type
,
567 unsigned int alignment
);
570 @brief Returns the byte order of the @fields described by
571 the @ft \p field_type.
573 You can only call this function if \p field_type is a @intft, a
574 @floatft, or a @enumft.
576 @param[in] field_type Field type which describes the
577 fields of which to get the byte order.
578 @returns Byte order of the fields described by
579 \p field_type, or #BT_CTF_BYTE_ORDER_UNKNOWN on
582 @prenotnull{field_type}
583 @pre \p field_type is a @intft, a @floatft, or a @enumft.
584 @postrefcountsame{field_type}
586 @sa bt_ctf_field_type_set_byte_order(): Sets the byte order
587 of the fields described by a given field type.
589 extern enum bt_ctf_byte_order
bt_ctf_field_type_get_byte_order(
590 struct bt_ctf_field_type
*field_type
);
593 @brief Sets the byte order of the @fields described by the
594 @ft \p field_type to \p byte_order.
596 If \p field_type is a compound field type, this function also
597 recursively sets the byte order of its children to \p byte_order.
599 @param[in] field_type Field type which describes the fields of
600 which to set the byte order.
601 @param[in] byte_order Alignment of the fields described by
603 @returns 0 on success, or a negative value on error.
605 @prenotnull{field_type}
607 @pre \p byte_order is #BT_CTF_BYTE_ORDER_NATIVE,
608 #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN, #BT_CTF_BYTE_ORDER_BIG_ENDIAN,
609 or #BT_CTF_BYTE_ORDER_NETWORK.
610 @postrefcountsame{field_type}
612 @sa bt_ctf_field_type_get_byte_order(): Returns the byte order of the
613 fields described by a given field type.
615 extern int bt_ctf_field_type_set_byte_order(
616 struct bt_ctf_field_type
*field_type
,
617 enum bt_ctf_byte_order byte_order
);
622 @name Utility functions
627 @brief Returns whether or not the @ft \p field_type_a
628 is equivalent to the field type \p field_type_b.
630 You \em must use this function to compare two field types: it is not
631 safe to compare two pointer values directly, because, for internal
632 reasons, some parts of the Babeltrace system can copy user field types
633 and discard the original ones.
635 @param[in] field_type_a Field type to compare to \p field_type_b.
636 @param[in] field_type_b Field type to compare to \p field_type_a.
637 @returns 0 if \p field_type_a is equivalent to
638 \p field_type_b, 1 if they are not equivalent,
639 or a negative value on error.
641 @prenotnull{field_type_a}
642 @prenotnull{field_type_b}
643 @postrefcountsame{field_type_a}
644 @postrefcountsame{field_type_b}
646 extern int bt_ctf_field_type_compare(struct bt_ctf_field_type
*field_type_a
,
647 struct bt_ctf_field_type
*field_type_b
);
650 @brief Creates a \em deep copy of the @ft \p field_type.
652 You can copy a frozen field type: the resulting copy is
655 This function resets the tag field type of a copied @varft. The
656 automatic field resolving which some functions of the API perform
657 can set it again when the returned field type is used (learn more
658 in the detailed description of this module).
660 @param[in] field_type Field type to copy.
661 @returns Deep copy of \p field_type on success,
664 @prenotnull{field_type}
665 @postrefcountsame{field_type}
666 @postsuccessrefcountret1
667 @post <strong>On success</strong>, the returned field type is not frozen.
669 extern struct bt_ctf_field_type
*bt_ctf_field_type_copy(
670 struct bt_ctf_field_type
*field_type
);
677 @defgroup ctfirintfieldtype CTF IR integer field type
678 @ingroup ctfirfieldtypes
679 @brief CTF IR integer field type.
682 #include <babeltrace/ctf-ir/field-types.h>
685 A CTF IR <strong><em>integer field type</em></strong> is a field type that
686 you can use to create concrete @intfield objects.
688 You can create an integer field type
689 with bt_ctf_field_type_integer_create().
691 An integer field type has the following properties:
696 <th>Value at creation
701 <td>\b Alignment (bits) of the described integer fields
703 <td>bt_ctf_field_type_get_alignment()
704 <td>bt_ctf_field_type_set_alignment()
707 <td><strong>Byte order</strong> of the described integer fields
708 <td>#BT_CTF_BYTE_ORDER_NATIVE
709 <td>bt_ctf_field_type_get_byte_order()
710 <td>bt_ctf_field_type_set_byte_order()
713 <td><strong>Storage size</strong> (bits) of the described
715 <td>Specified at creation
716 <td>bt_ctf_field_type_integer_get_size()
717 <td>bt_ctf_field_type_integer_set_size()
720 <td><strong>Signedness</strong> of the described integer fields
722 <td>bt_ctf_field_type_integer_is_signed()
723 <td>bt_ctf_field_type_integer_set_is_signed()
726 <td><strong>Preferred display base</strong> of the described
728 <td>#BT_CTF_INTEGER_BASE_DECIMAL
729 <td>bt_ctf_field_type_integer_get_base()
730 <td>bt_ctf_field_type_integer_set_base()
733 <td>\b Encoding of the described integer fields
734 <td>#BT_CTF_STRING_ENCODING_NONE
735 <td>bt_ctf_field_type_integer_get_encoding()
736 <td>bt_ctf_field_type_integer_set_encoding()
740 \link ctfirclockclass CTF IR clock class\endlink</strong>
742 <td>bt_ctf_field_type_integer_get_mapped_clock_class()
743 <td>bt_ctf_field_type_integer_set_mapped_clock_class()
749 @sa \ref ctfirfieldtypesexamples_intfieldtype "Examples"
751 @addtogroup ctfirintfieldtype
756 @brief Preferred display base (radix) of a @intft.
758 enum bt_ctf_integer_base
{
759 /// Unknown, used for errors.
760 BT_CTF_INTEGER_BASE_UNKNOWN
= -1,
762 /// Unspecified by the tracer.
763 BT_CTF_INTEGER_BASE_UNSPECIFIED
= 0,
766 BT_CTF_INTEGER_BASE_BINARY
= 2,
769 BT_CTF_INTEGER_BASE_OCTAL
= 8,
772 BT_CTF_INTEGER_BASE_DECIMAL
= 10,
775 BT_CTF_INTEGER_BASE_HEXADECIMAL
= 16,
779 @brief Creates a default @intft with \p size bits as the storage size
780 of the @intfields it describes.
782 You can change the storage size of the integer fields described by
783 the created integer field type later with
784 bt_ctf_field_type_integer_set_size().
786 @param[in] size Storage size (bits) of the described integer fields.
787 @returns Created integer field type, or \c NULL on error.
789 @pre \p size is greater than 0 and lesser than or equal to 64.
790 @postsuccessrefcountret1
792 extern struct bt_ctf_field_type
*bt_ctf_field_type_integer_create(
796 @brief Returns the storage size, in bits, of the @intfields
797 described by the @intft \p int_field_type.
799 @param[in] int_field_type Integer field type which describes the
800 integer fields of which to get the
802 @returns Storage size (bits) of the integer
803 fields described by \p int_field_type,
804 or a negative value on error.
806 @prenotnull{int_field_type}
807 @preisintft{int_field_type}
808 @postrefcountsame{int_field_type}
810 @sa bt_ctf_field_type_integer_set_size(): Sets the storage size of the
811 integer fields described by a given integer field type.
813 extern int bt_ctf_field_type_integer_get_size(
814 struct bt_ctf_field_type
*int_field_type
);
817 @brief Sets the storage size, in bits, of the @intfields described by
818 the @intft \p int_field_type.
820 @param[in] int_field_type Integer field type which describes the
821 integer fields of which to set the
823 @param[in] size Storage size (bits) of the integer fields
824 described by \p int_field_type.
825 @returns 0 on success, or a negative value on error.
827 @prenotnull{int_field_type}
828 @preisintft{int_field_type}
829 @prehot{int_field_type}
830 @pre \p size is greater than 0 and lesser than or equal to 64.
831 @postrefcountsame{int_field_type}
833 @sa bt_ctf_field_type_integer_get_size(): Returns the storage size of
834 the integer fields described by a given integer field type.
836 extern int bt_ctf_field_type_integer_set_size(
837 struct bt_ctf_field_type
*int_field_type
, unsigned int size
);
840 @brief Returns whether or not the @intfields described by the @intft
841 \p int_field_type are signed.
843 @param[in] int_field_type Integer field type which describes the
844 integer fields of which to get the
846 @returns #BT_TRUE if the integer fields described by
847 \p int_field_type are signed, #BT_FALSE if they
850 @prenotnull{int_field_type}
851 @preisintft{int_field_type}
852 @postrefcountsame{int_field_type}
854 @sa bt_ctf_field_type_integer_set_is_signed(): Sets the signedness of the
855 integer fields described by a given integer field type.
857 extern bt_bool
bt_ctf_field_type_integer_is_signed(
858 struct bt_ctf_field_type
*int_field_type
);
860 /** @cond DOCUMENT */
862 extern int bt_ctf_field_type_integer_get_signed(
863 struct bt_ctf_field_type
*int_field_type
);
868 @brief Sets whether or not the @intfields described by
869 the @intft \p int_field_type are signed.
871 @param[in] int_field_type Integer field type which describes the
872 integer fields of which to set the
874 @param[in] is_signed Signedness of the integer fields
875 described by \p int_field_type; #BT_FALSE means
876 \em unsigned, #BT_TRUE means \em signed.
877 @returns 0 on success, or a negative value on error.
879 @prenotnull{int_field_type}
880 @preisintft{int_field_type}
881 @prehot{int_field_type}
882 @postrefcountsame{int_field_type}
884 @sa bt_ctf_field_type_integer_is_signed(): Returns the signedness of
885 the integer fields described by a given integer field type.
887 extern int bt_ctf_field_type_integer_set_is_signed(
888 struct bt_ctf_field_type
*int_field_type
, bt_bool is_signed
);
890 /* Pre-2.0 CTF writer compatibility */
891 #define bt_ctf_field_type_integer_set_signed bt_ctf_field_type_integer_set_is_signed
894 @brief Returns the preferred display base (radix) of the @intfields
895 described by the @intft \p int_field_type.
897 @param[in] int_field_type Integer field type which describes the
898 integer fields of which to get the
899 preferred display base.
900 @returns Preferred display base of the integer
901 fields described by \p int_field_type,
902 #BT_CTF_INTEGER_BASE_UNSPECIFIED if
904 #BT_CTF_INTEGER_BASE_UNKNOWN on error.
906 @prenotnull{int_field_type}
907 @preisintft{int_field_type}
908 @postrefcountsame{int_field_type}
910 @sa bt_ctf_field_type_integer_set_base(): Sets the preferred display
911 base of the integer fields described by a given integer field
914 extern enum bt_ctf_integer_base
bt_ctf_field_type_integer_get_base(
915 struct bt_ctf_field_type
*int_field_type
);
918 @brief Sets the preferred display base (radix) of the @intfields
919 described by the @intft \p int_field_type to \p base.
921 @param[in] int_field_type Integer field type which describes the
922 integer fields of which to set the
923 preferred display base.
924 @param[in] base Preferred display base of the integer
925 fields described by \p int_field_type.
926 @returns 0 on success, or a negative value on error.
928 @prenotnull{int_field_type}
929 @preisintft{int_field_type}
930 @prehot{int_field_type}
931 @pre \p base is #BT_CTF_INTEGER_BASE_UNSPECIFIED,
932 #BT_CTF_INTEGER_BASE_BINARY, #BT_CTF_INTEGER_BASE_OCTAL,
933 #BT_CTF_INTEGER_BASE_DECIMAL, or #BT_CTF_INTEGER_BASE_HEXADECIMAL.
934 @postrefcountsame{int_field_type}
936 @sa bt_ctf_field_type_integer_get_base(): Returns the preferred display
937 base of the integer fields described by a given
940 extern int bt_ctf_field_type_integer_set_base(
941 struct bt_ctf_field_type
*int_field_type
,
942 enum bt_ctf_integer_base base
);
945 @brief Returns the encoding of the @intfields described by
946 the @intft \p int_field_type.
948 @param[in] int_field_type Integer field type which describes the
949 integer fields of which to get the
951 @returns Encoding of the integer
952 fields described by \p int_field_type,
953 or #BT_CTF_STRING_ENCODING_UNKNOWN on
956 @prenotnull{int_field_type}
957 @preisintft{int_field_type}
958 @postrefcountsame{int_field_type}
960 @sa bt_ctf_field_type_integer_set_encoding(): Sets the encoding
961 of the integer fields described by a given integer field type.
963 extern enum bt_ctf_string_encoding
bt_ctf_field_type_integer_get_encoding(
964 struct bt_ctf_field_type
*int_field_type
);
967 @brief Sets the encoding of the @intfields described by the @intft
968 \p int_field_type to \p encoding.
970 You can use this property, in CTF IR, to create "text" @arrayfts or
971 @seqfts. A text array field type is array field type with an unsigned,
972 8-bit integer field type having an encoding as its element field type.
974 @param[in] int_field_type Integer field type which describes the
975 integer fields of which to set the
977 @param[in] encoding Encoding of the integer
978 fields described by \p int_field_type.
979 @returns 0 on success, or a negative value on error.
981 @prenotnull{int_field_type}
982 @preisintft{int_field_type}
983 @prehot{int_field_type}
984 @pre \p encoding is #BT_CTF_STRING_ENCODING_NONE,
985 #BT_CTF_STRING_ENCODING_ASCII, or
986 #BT_CTF_STRING_ENCODING_UTF8.
987 @postrefcountsame{int_field_type}
989 @sa bt_ctf_field_type_integer_get_encoding(): Returns the encoding of
990 the integer fields described by a given integer field type.
992 extern int bt_ctf_field_type_integer_set_encoding(
993 struct bt_ctf_field_type
*int_field_type
,
994 enum bt_ctf_string_encoding encoding
);
997 @brief Returns the \link ctfirclockclass CTF IR clock class\endlink
998 mapped to the @intft \p int_field_type.
1000 The mapped clock class, if any, indicates the class of the clock which
1001 an @intfield described by \p int_field_type should sample or update.
1002 This mapped clock class is only indicative.
1004 @param[in] int_field_type Integer field type of which to get the
1006 @returns Mapped clock class of \p int_field_type,
1007 or \c NULL if there's no mapped clock
1010 @prenotnull{int_field_type}
1011 @preisintft{int_field_type}
1012 @postrefcountsame{int_field_type}
1013 @postsuccessrefcountretinc
1015 @sa bt_ctf_field_type_integer_set_mapped_clock_class(): Sets the mapped
1016 clock class of a given integer field type.
1018 extern struct bt_ctf_clock_class
*bt_ctf_field_type_integer_get_mapped_clock_class(
1019 struct bt_ctf_field_type
*int_field_type
);
1022 @brief Sets the \link ctfirclockclass CTF IR clock class\endlink mapped
1023 to the @intft \p int_field_type to \p clock_class.
1025 The mapped clock class, if any, indicates the class of the clock which
1026 an integer field described by \p int_field_type should sample or update.
1027 This mapped clock class is only indicative.
1029 @param[in] int_field_type Integer field type of which to set the
1031 @param[in] clock_class Mapped clock class of \p int_field_type.
1032 @returns 0 on success, or a negative value on error.
1034 @prenotnull{int_field_type}
1035 @prenotnull{clock_class}
1036 @preisintft{int_field_type}
1037 @prehot{int_field_type}
1038 @postrefcountsame{int_field_type}
1039 @postsuccessrefcountinc{clock_class}
1041 @sa bt_ctf_field_type_integer_get_mapped_clock_class(): Returns the mapped
1042 clock class of a given integer field type.
1044 extern int bt_ctf_field_type_integer_set_mapped_clock_class(
1045 struct bt_ctf_field_type
*int_field_type
,
1046 struct bt_ctf_clock_class
*clock_class
);
1051 @defgroup ctfirfloatfieldtype CTF IR floating point number field type
1052 @ingroup ctfirfieldtypes
1053 @brief CTF IR floating point number field type.
1056 #include <babeltrace/ctf-ir/field-types.h>
1059 A CTF IR <strong><em>floating point number field type</em></strong> is
1060 a field type that you can use to create concrete @floatfields.
1062 You can create a floating point number field type
1063 with bt_ctf_field_type_floating_point_create().
1065 A floating point number field type has the following properties:
1070 <th>Value at creation
1075 <td>\b Alignment (bits) of the described floating point
1078 <td>bt_ctf_field_type_get_alignment()
1079 <td>bt_ctf_field_type_set_alignment()
1082 <td><strong>Byte order</strong> of the described floating point
1084 <td>#BT_CTF_BYTE_ORDER_NATIVE
1085 <td>bt_ctf_field_type_get_byte_order()
1086 <td>bt_ctf_field_type_set_byte_order()
1089 <td><strong>Exponent storage size</strong> (bits) of the described
1090 floating point number fields
1092 <td>bt_ctf_field_type_floating_point_get_exponent_digits()
1093 <td>bt_ctf_field_type_floating_point_set_exponent_digits()
1096 <td><strong>Mantissa and sign storage size</strong> (bits) of the
1097 described floating point number fields
1098 <td>24 (23-bit mantissa, 1-bit sign)
1099 <td>bt_ctf_field_type_floating_point_get_mantissa_digits()
1100 <td>bt_ctf_field_type_floating_point_set_mantissa_digits()
1106 @sa \ref ctfirfieldtypesexamples_floatfieldtype "Examples"
1108 @addtogroup ctfirfloatfieldtype
1113 @brief Creates a default @floatft.
1115 @returns Created floating point number field type,
1116 or \c NULL on error.
1118 @postsuccessrefcountret1
1120 extern struct bt_ctf_field_type
*bt_ctf_field_type_floating_point_create(void);
1123 @brief Returns the exponent storage size of the @floatfields
1124 described by the @floatft \p float_field_type.
1126 @param[in] float_field_type Floating point number field type which
1127 describes the floating point number
1128 fields of which to get the exponent
1130 @returns Exponent storage size of the
1131 floating point number fields
1132 described by \p float_field_type,
1133 or a negative value on error.
1135 @prenotnull{float_field_type}
1136 @preisfloatft{float_field_type}
1137 @postrefcountsame{float_field_type}
1139 @sa bt_ctf_field_type_floating_point_set_exponent_digits(): Sets the
1140 exponent storage size of the floating point number fields
1141 described by a given floating point number field type.
1143 extern int bt_ctf_field_type_floating_point_get_exponent_digits(
1144 struct bt_ctf_field_type
*float_field_type
);
1147 @brief Sets the exponent storage size of the @floatfields described by
1148 the @floatft \p float_field_type to \p exponent_size.
1150 As of Babeltrace \btversion, \p exponent_size can only be 8 or 11.
1152 @param[in] float_field_type Floating point number field type which
1153 describes the floating point number
1154 fields of which to set the exponent
1156 @param[in] exponent_size Exponent storage size of the floating
1157 point number fields described by \p
1159 @returns 0 on success, or a negative value on error.
1161 @prenotnull{float_field_type}
1162 @preisfloatft{float_field_type}
1163 @prehot{float_field_type}
1164 @pre \p exponent_size is 8 or 11.
1165 @postrefcountsame{float_field_type}
1167 @sa bt_ctf_field_type_floating_point_get_exponent_digits(): Returns the
1168 exponent storage size of the floating point number fields
1169 described by a given floating point number field type.
1171 extern int bt_ctf_field_type_floating_point_set_exponent_digits(
1172 struct bt_ctf_field_type
*float_field_type
,
1173 unsigned int exponent_size
);
1176 @brief Returns the mantissa and sign storage size of the @floatfields
1177 described by the @floatft \p float_field_type.
1179 On success, the returned value is the sum of the mantissa \em and
1182 @param[in] float_field_type Floating point number field type which
1183 describes the floating point number
1184 fields of which to get the mantissa and
1186 @returns Mantissa and sign storage size of the
1187 floating point number fields
1188 described by \p float_field_type,
1189 or a negative value on error.
1191 @prenotnull{float_field_type}
1192 @preisfloatft{float_field_type}
1193 @postrefcountsame{float_field_type}
1195 @sa bt_ctf_field_type_floating_point_set_mantissa_digits(): Sets the
1196 mantissa and size storage size of the floating point number
1197 fields described by a given floating point number field type.
1199 extern int bt_ctf_field_type_floating_point_get_mantissa_digits(
1200 struct bt_ctf_field_type
*float_field_type
);
1203 @brief Sets the mantissa and sign storage size of the @floatfields
1204 described by the @floatft \p float_field_type to \p
1207 As of Babeltrace \btversion, \p mantissa_sign_size can only be 24 or 53.
1209 @param[in] float_field_type Floating point number field type which
1210 describes the floating point number
1211 fields of which to set the mantissa and
1213 @param[in] mantissa_sign_size Mantissa and sign storage size of the
1214 floating point number fields described
1215 by \p float_field_type.
1216 @returns 0 on success, or a negative value on error.
1218 @prenotnull{float_field_type}
1219 @preisfloatft{float_field_type}
1220 @prehot{float_field_type}
1221 @pre \p mantissa_sign_size is 24 or 53.
1222 @postrefcountsame{float_field_type}
1224 @sa bt_ctf_field_type_floating_point_get_mantissa_digits(): Returns the
1225 mantissa and sign storage size of the floating point number
1226 fields described by a given floating point number field type.
1228 extern int bt_ctf_field_type_floating_point_set_mantissa_digits(
1229 struct bt_ctf_field_type
*float_field_type
,
1230 unsigned int mantissa_sign_size
);
1235 @defgroup ctfirenumfieldtype CTF IR enumeration field type
1236 @ingroup ctfirfieldtypes
1237 @brief CTF IR enumeration field type.
1240 #include <babeltrace/ctf-ir/field-types.h>
1243 A CTF IR <strong><em>enumeration field type</em></strong> is
1244 a field type that you can use to create concrete @enumfields.
1246 You can create an enumeration field type with
1247 bt_ctf_field_type_enumeration_create(). This function needs a @intft
1248 which represents the storage field type of the created enumeration field
1249 type. In other words, an enumeration field type wraps an integer field
1250 type and adds label-value mappings to it.
1252 An enumeration mapping has:
1254 - A <strong>name</strong>.
1255 - A <strong>range of values</strong> given by a beginning and an ending
1256 value, both included in the range.
1258 You can add a mapping to an enumeration field type with
1259 bt_ctf_field_type_enumeration_add_mapping_signed() or
1260 bt_ctf_field_type_enumeration_add_mapping_unsigned(), depending on the
1261 signedness of the wrapped @intft.
1263 You can find mappings by name or by value with the following find
1266 - bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
1267 mappings with a given name.
1268 - bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value():
1269 Finds the mappings which contain a given unsigned value in their
1271 - bt_ctf_field_type_enumeration_find_mappings_by_signed_value():
1272 Finds the mappings which contain a given signed value in their range.
1274 Those functions return a @enumftiter on the result set of the find
1277 Many mappings can share the same name, and the ranges of a given
1278 enumeration field type are allowed to overlap. For example,
1279 this is a valid set of mappings:
1288 The following set of mappings is also valid:
1297 Here, the range of the second \c APPLE mapping overlaps the range of
1298 the \c CHERRY mapping.
1300 @sa ctfirenumftmappingiter
1304 @addtogroup ctfirenumfieldtype
1309 @brief Creates a default @enumft wrapping the @intft \p int_field_type.
1311 @param[in] int_field_type Integer field type wrapped by the
1312 created enumeration field type.
1313 @returns Created enumeration field type,
1314 or \c NULL on error.
1316 @prenotnull{int_field_type}
1317 @preisintft{int_field_type}
1318 @postsuccessrefcountinc{int_field_type}
1319 @postsuccessrefcountret1
1321 extern struct bt_ctf_field_type
*bt_ctf_field_type_enumeration_create(
1322 struct bt_ctf_field_type
*int_field_type
);
1325 @brief Returns the @intft wrapped by the @enumft \p enum_field_type.
1327 @param[in] enum_field_type Enumeration field type of which to get
1328 the wrapped integer field type.
1329 @returns Integer field type wrapped by
1330 \p enum_field_type, or \c NULL on
1333 @prenotnull{enum_field_type}
1334 @preisenumft{enum_field_type}
1335 @postrefcountsame{enum_field_type}
1336 @postsuccessrefcountretinc
1339 struct bt_ctf_field_type
*bt_ctf_field_type_enumeration_get_container_type(
1340 struct bt_ctf_field_type
*enum_field_type
);
1343 @brief Returns the number of mappings contained in the
1344 @enumft \p enum_field_type.
1346 @param[in] enum_field_type Enumeration field type of which to get
1347 the number of contained mappings.
1348 @returns Number of mappings contained in
1349 \p enum_field_type, or a negative
1352 @prenotnull{enum_field_type}
1353 @preisenumft{enum_field_type}
1354 @postrefcountsame{enum_field_type}
1356 extern int64_t bt_ctf_field_type_enumeration_get_mapping_count(
1357 struct bt_ctf_field_type
*enum_field_type
);
1360 @brief Returns the signed mapping of the @enumft
1361 \p enum_field_type at index \p index.
1363 The @intft wrapped by \p enum_field_type, as returned by
1364 bt_ctf_field_type_enumeration_get_container_type(), must be \b signed
1365 to use this function.
1367 On success, \p enum_field_type remains the sole owner of \p *name.
1369 @param[in] enum_field_type Enumeration field type of which to get
1370 the mapping at index \p index.
1371 @param[in] index Index of the mapping to get from
1373 @param[out] name Returned name of the mapping at index
1375 @param[out] range_begin Returned beginning of the range
1376 (included) of the mapping at index \p
1378 @param[out] range_end Returned end of the range (included) of
1379 the mapping at index \p index.
1380 @returns 0 on success, or a negative value on error.
1382 @prenotnull{enum_field_type}
1384 @prenotnull{range_begin}
1385 @prenotnull{range_end}
1386 @preisenumft{enum_field_type}
1387 @pre The wrapped @intft of \p enum_field_type is signed.
1388 @pre \p index is lesser than the number of mappings contained in the
1389 enumeration field type \p enum_field_type (see
1390 bt_ctf_field_type_enumeration_get_mapping_count()).
1391 @postrefcountsame{enum_field_type}
1393 @sa bt_ctf_field_type_enumeration_get_mapping_unsigned(): Returns the
1394 unsigned mapping contained by a given enumeration field type
1397 extern int bt_ctf_field_type_enumeration_get_mapping_signed(
1398 struct bt_ctf_field_type
*enum_field_type
, uint64_t index
,
1399 const char **name
, int64_t *range_begin
, int64_t *range_end
);
1402 @brief Returns the unsigned mapping of the @enumft
1403 \p enum_field_type at index \p index.
1405 The @intft wrapped by \p enum_field_type, as returned by
1406 bt_ctf_field_type_enumeration_get_container_type(), must be
1407 \b unsigned to use this function.
1409 On success, \p enum_field_type remains the sole owner of \p *name.
1411 @param[in] enum_field_type Enumeration field type of which to get
1412 the mapping at index \p index.
1413 @param[in] index Index of the mapping to get from
1415 @param[out] name Returned name of the mapping at index
1417 @param[out] range_begin Returned beginning of the range
1418 (included) of the mapping at index \p
1420 @param[out] range_end Returned end of the range (included) of
1421 the mapping at index \p index.
1422 @returns 0 on success, or a negative value on error.
1424 @prenotnull{enum_field_type}
1426 @prenotnull{range_begin}
1427 @prenotnull{range_end}
1428 @preisenumft{enum_field_type}
1429 @pre The wrapped @intft of \p enum_field_type is unsigned.
1430 @pre \p index is lesser than the number of mappings contained in the
1431 enumeration field type \p enum_field_type (see
1432 bt_ctf_field_type_enumeration_get_mapping_count()).
1433 @postrefcountsame{enum_field_type}
1435 @sa bt_ctf_field_type_enumeration_get_mapping_signed(): Returns the
1436 signed mapping contained by a given enumeration field type
1439 extern int bt_ctf_field_type_enumeration_get_mapping_unsigned(
1440 struct bt_ctf_field_type
*enum_field_type
, uint64_t index
,
1441 const char **name
, uint64_t *range_begin
,
1442 uint64_t *range_end
);
1445 @brief Finds the mappings of the @enumft \p enum_field_type which
1448 This function returns an iterator on the result set of this find
1449 operation. See \ref ctfirenumftmappingiter for more details.
1451 @param[in] enum_field_type Enumeration field type of which to find
1452 the mappings named \p name.
1453 @param[in] name Name of the mappings to find in
1455 @returns @enumftiter on the set of mappings named
1456 \p name in \p enum_field_type, or
1457 \c NULL if no mappings were found or
1460 @prenotnull{enum_field_type}
1462 @preisenumft{enum_field_type}
1463 @postrefcountsame{enum_field_type}
1464 @postsuccessrefcountret1
1465 @post <strong>On success</strong>, the returned @enumftiter can iterate
1466 on at least one mapping.
1468 @sa bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): Finds
1469 the mappings of a given enumeration field type which contain
1470 a given signed value in their range.
1471 @sa bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): Finds
1472 the mappings of a given enumeration field type which contain
1473 a given unsigned value in their range.
1475 extern struct bt_ctf_field_type_enumeration_mapping_iterator
*
1476 bt_ctf_field_type_enumeration_find_mappings_by_name(
1477 struct bt_ctf_field_type
*enum_field_type
,
1481 @brief Finds the mappings of the @enumft \p enum_field_type which
1482 contain the signed value \p value in their range.
1484 This function returns an iterator on the result set of this find
1485 operation. See \ref ctfirenumftmappingiter for more details.
1487 @param[in] enum_field_type Enumeration field type of which to find
1488 the mappings which contain \p value.
1489 @param[in] value Value to find in the ranges of the
1490 mappings of \p enum_field_type.
1491 @returns @enumftiter on the set of mappings of
1492 \p enum_field_type which contain
1493 \p value in their range, or \c NULL if
1494 no mappings were found or on error.
1496 @prenotnull{enum_field_type}
1497 @preisenumft{enum_field_type}
1498 @postrefcountsame{enum_field_type}
1499 @postsuccessrefcountret1
1500 @post <strong>On success</strong>, the returned @enumftiter can iterate
1501 on at least one mapping.
1503 @sa bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
1504 mappings of a given enumeration field type which have a given
1506 @sa bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): Finds
1507 the mappings of a given enumeration field type which contain
1508 a given unsigned value in their range.
1510 extern struct bt_ctf_field_type_enumeration_mapping_iterator
*
1511 bt_ctf_field_type_enumeration_find_mappings_by_signed_value(
1512 struct bt_ctf_field_type
*enum_field_type
,
1516 @brief Finds the mappings of the @enumft \p enum_field_type which
1517 contain the unsigned value \p value in their range.
1519 This function returns an iterator on the result set of this find
1520 operation. See \ref ctfirenumftmappingiter for more details.
1522 @param[in] enum_field_type Enumeration field type of which to find
1523 the mappings which contain \p value.
1524 @param[in] value Value to find in the ranges of the
1525 mappings of \p enum_field_type.
1526 @returns @enumftiter on the set of mappings of
1527 \p enum_field_type which contain
1528 \p value in their range, or \c NULL
1529 if no mappings were found or
1532 @prenotnull{enum_field_type}
1533 @preisenumft{enum_field_type}
1534 @postrefcountsame{enum_field_type}
1535 @postsuccessrefcountret1
1536 @post <strong>On success</strong>, the returned @enumftiter can iterate
1537 on at least one mapping.
1539 @sa bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
1540 mappings of a given enumeration field type which have a given
1542 @sa bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): Finds
1543 the mappings of a given enumeration field type which contain
1544 a given unsigned value in their range.
1546 extern struct bt_ctf_field_type_enumeration_mapping_iterator
*
1547 bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(
1548 struct bt_ctf_field_type
*enum_field_type
,
1552 @brief Adds a mapping to the @enumft \p enum_field_type which maps the
1553 name \p name to the signed range \p range_begin (included) to
1554 \p range_end (included).
1556 Make \p range_begin and \p range_end the same value to add a mapping
1559 The @intft wrapped by \p enum_field_type, as returned by
1560 bt_ctf_field_type_enumeration_get_container_type(), must be
1561 \b signed to use this function.
1563 A mapping in \p enum_field_type can exist with the name \p name.
1565 @param[in] enum_field_type Enumeration field type to which to add
1567 @param[in] name Name of the mapping to add (copied
1569 @param[in] range_begin Beginning of the range of the mapping
1571 @param[in] range_end End of the range of the mapping
1573 @returns 0 on success, or a negative value on error.
1575 @prenotnull{enum_field_type}
1577 @prehot{enum_field_type}
1578 @preisenumft{enum_field_type}
1579 @pre The wrapped @intft of \p enum_field_type is signed.
1580 @pre \p range_end is greater than or equal to \p range_begin.
1581 @postrefcountsame{enum_field_type}
1583 @sa bt_ctf_field_type_enumeration_add_mapping_unsigned(): Adds an
1584 unsigned mapping to a given enumeration field type.
1586 extern int bt_ctf_field_type_enumeration_add_mapping_signed(
1587 struct bt_ctf_field_type
*enum_field_type
, const char *name
,
1588 int64_t range_begin
, int64_t range_end
);
1590 /* Pre-2.0 CTF writer compatibility */
1591 #define bt_ctf_field_type_enumeration_add_mapping bt_ctf_field_type_enumeration_add_mapping_signed
1594 @brief Adds a mapping to the @enumft \p enum_field_type which maps
1595 the name \p name to the unsigned
1596 range \p range_begin (included) to \p range_end (included).
1598 Make \p range_begin and \p range_end the same value to add a mapping
1601 The @intft wrapped by \p enum_field_type, as returned by
1602 bt_ctf_field_type_enumeration_get_container_type(), must be
1603 \b unsigned to use this function.
1605 A mapping in \p enum_field_type can exist with the name \p name.
1607 @param[in] enum_field_type Enumeration field type to which to add
1609 @param[in] name Name of the mapping to add (copied
1611 @param[in] range_begin Beginning of the range of the mapping
1613 @param[in] range_end End of the range of the mapping
1615 @returns 0 on success, or a negative value on error.
1617 @prenotnull{enum_field_type}
1619 @prehot{enum_field_type}
1620 @preisenumft{enum_field_type}
1621 @pre The wrapped @intft of \p enum_field_type is unsigned.
1622 @pre \p range_end is greater than or equal to \p range_begin.
1623 @postrefcountsame{enum_field_type}
1625 @sa bt_ctf_field_type_enumeration_add_mapping_signed(): Adds a signed
1626 mapping to a given enumeration field type.
1628 extern int bt_ctf_field_type_enumeration_add_mapping_unsigned(
1629 struct bt_ctf_field_type
*enum_field_type
, const char *name
,
1630 uint64_t range_begin
, uint64_t range_end
);
1635 @defgroup ctfirenumftmappingiter CTF IR enumeration field type mapping iterator
1636 @ingroup ctfirenumfieldtype
1637 @brief CTF IR enumeration field type mapping iterator.
1640 #include <babeltrace/ctf-ir/field-types.h>
1643 A CTF IR <strong><em>enumeration field type mapping
1644 iterator</em></strong> is an iterator on @enumft mappings.
1646 You can get an enumeration mapping iterator from one of the following
1649 - Find operations of an @enumft object:
1650 - bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
1651 mappings with a given name.
1652 - bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value():
1653 Finds the mappings which contain a given unsigned value in their
1655 - bt_ctf_field_type_enumeration_find_mappings_by_signed_value():
1656 Finds the mappings which contain a given signed value in their range.
1657 - bt_ctf_field_enumeration_get_mappings(): Finds the mappings in the
1658 @enumft of an @enumfield containing its current integral value in
1661 Those functions guarantee that the returned iterator can iterate on
1662 at least one mapping. Otherwise, they return \c NULL.
1664 You can get the name and the range of a mapping iterator's current
1666 bt_ctf_field_type_enumeration_mapping_iterator_get_signed()
1668 bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(),
1669 depending on the signedness of the @intft wrapped by the
1670 @enumft. If you only need the name of the current mapping, you can
1671 use any of the two functions and set the \p range_begin and \p range_end
1672 parameters to \c NULL.
1674 You can advance an enumeration field type mapping iterator to the next
1676 bt_ctf_field_type_enumeration_mapping_iterator_next(). This
1677 function returns a negative value when you reach the end of the
1680 As with any Babeltrace object, CTF IR enumeration field type mapping
1681 iterator objects have <a
1682 href="https://en.wikipedia.org/wiki/Reference_counting">reference
1683 counts</a>. See \ref refs to learn more about the reference counting
1684 management of Babeltrace objects.
1686 @sa ctfirenumfieldtype
1688 @addtogroup ctfirenumftmappingiter
1693 @struct bt_ctf_field_type_enumeration_mapping_iterator
1694 @brief A CTF IR enumeration field type mapping iterator.
1695 @sa ctfirenumftmappingiter
1699 @brief Returns the name and the range of the current (signed) mapping
1700 of the @enumftiter \p iter.
1702 If one of \p range_begin or \p range_end is not \c NULL, the @intft
1703 wrapped by the @enumft from which \p iter was obtained, as returned by
1704 bt_ctf_field_type_enumeration_get_container_type(), must be
1705 \b signed to use this function. Otherwise, if you only need to get the
1706 name of the current mapping, set \p range_begin and \p range_end to
1709 On success, if \p name is not \c NULL, \p *name remains valid as long
1710 as \p iter exists and
1711 bt_ctf_field_type_enumeration_mapping_iterator_next() is
1712 \em not called on \p iter.
1714 @param[in] iter Enumeration field type mapping iterator
1715 of which to get the range of the current
1717 @param[out] name Returned name of the current mapping of
1718 \p iter (can be \c NULL to ignore).
1719 @param[out] range_begin Returned beginning of the range
1720 (included) of the current mapping of
1721 \p iter (can be \c NULL to ignore).
1722 @param[out] range_end Returned end of the range
1723 (included) of the current mapping of
1724 \p iter (can be \c NULL to ignore).
1725 @returns 0 on success, or a negative value on error.
1728 @postrefcountsame{iter}
1730 @sa bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned():
1731 Returns the name and the unsigned range of the current mapping
1732 of a given enumeration field type mapping iterator.
1734 extern int bt_ctf_field_type_enumeration_mapping_iterator_get_signed(
1735 struct bt_ctf_field_type_enumeration_mapping_iterator
*iter
,
1736 const char **name
, int64_t *range_begin
, int64_t *range_end
);
1739 @brief Returns the name and the range of the current (unsigned) mapping
1740 of the @enumftiter \p iter.
1742 If one of \p range_begin or \p range_end is not \c NULL, the @intft
1743 wrapped by the @enumft from which \p iter was obtained, as returned by
1744 bt_ctf_field_type_enumeration_get_container_type(), must be
1745 \b unsigned to use this function. Otherwise, if you only need to get the
1746 name of the current mapping, set \p range_begin and \p range_end to
1749 On success, if \p name is not \c NULL, \p *name remains valid as long
1750 as \p iter exists and
1751 bt_ctf_field_type_enumeration_mapping_iterator_next() is
1752 \em not called on \p iter.
1754 @param[in] iter Enumeration field type mapping iterator
1755 of which to get the range of the current
1757 @param[out] name Returned name of the current mapping of
1758 \p iter (can be \c NULL to ignore).
1759 @param[out] range_begin Returned beginning of the range
1760 (included) of the current mapping of
1761 \p iter (can be \c NULL to ignore).
1762 @param[out] range_end Returned end of the range
1763 (included) of the current mapping of
1764 \p iter (can be \c NULL to ignore).
1765 @returns 0 on success, or a negative value on error.
1768 @postrefcountsame{iter}
1771 bt_ctf_field_type_enumeration_mapping_iterator_get_signed():
1772 Returns the name and the signed range of the current mapping of
1773 a given enumeration field type mapping iterator.
1775 extern int bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(
1776 struct bt_ctf_field_type_enumeration_mapping_iterator
*iter
,
1777 const char **name
, uint64_t *range_begin
, uint64_t *range_end
);
1780 @brief Advances the @enumftiter \p iter to the next mapping.
1782 @param[in] iter Enumeration field type mapping iterator to
1784 @returns 0 on success, or a negative value on error or
1785 when you reach the end of the set.
1788 @postrefcountsame{iter}
1790 extern int bt_ctf_field_type_enumeration_mapping_iterator_next(
1791 struct bt_ctf_field_type_enumeration_mapping_iterator
*iter
);
1796 @defgroup ctfirstringfieldtype CTF IR string field type
1797 @ingroup ctfirfieldtypes
1798 @brief CTF IR string field type.
1801 #include <babeltrace/ctf-ir/field-types.h>
1804 A CTF IR <strong><em>string field type</em></strong> is a field type that
1805 you can use to create concrete @stringfields.
1807 You can create a string field type
1808 with bt_ctf_field_type_string_create().
1810 A string field type has only one property: the \b encoding of its
1811 described @stringfields. By default, the encoding of the string fields
1812 described by a string field type is #BT_CTF_STRING_ENCODING_UTF8. You
1813 can set the encoding of the string fields described by a string field
1814 type with bt_ctf_field_type_string_set_encoding().
1816 @sa ctfirstringfield
1819 @addtogroup ctfirstringfieldtype
1824 @brief Creates a default @stringft.
1826 @returns Created string field type, or \c NULL on error.
1828 @postsuccessrefcountret1
1830 extern struct bt_ctf_field_type
*bt_ctf_field_type_string_create(void);
1833 @brief Returns the encoding of the @stringfields described by
1834 the @stringft \p string_field_type.
1836 @param[in] string_field_type String field type which describes the
1837 string fields of which to get the
1839 @returns Encoding of the string
1840 fields described by \p string_field_type,
1841 or #BT_CTF_STRING_ENCODING_UNKNOWN on
1844 @prenotnull{string_field_type}
1845 @preisstringft{string_field_type}
1846 @postrefcountsame{string_field_type}
1848 @sa bt_ctf_field_type_string_set_encoding(): Sets the encoding
1849 of the string fields described by a given string field type.
1851 extern enum bt_ctf_string_encoding
bt_ctf_field_type_string_get_encoding(
1852 struct bt_ctf_field_type
*string_field_type
);
1855 @brief Sets the encoding of the @stringfields described by the
1856 @stringft \p string_field_type to \p encoding.
1858 @param[in] string_field_type String field type which describes the
1859 string fields of which to set the
1861 @param[in] encoding Encoding of the string fields described
1862 by \p string_field_type.
1863 @returns 0 on success, or a negative value on error.
1865 @prenotnull{string_field_type}
1866 @preisstringft{string_field_type}
1867 @prehot{string_field_type}
1868 @pre \p encoding is #BT_CTF_STRING_ENCODING_ASCII or
1869 #BT_CTF_STRING_ENCODING_UTF8.
1870 @postrefcountsame{string_field_type}
1872 @sa bt_ctf_field_type_string_get_encoding(): Returns the encoding of
1873 the string fields described by a given string field type.
1875 extern int bt_ctf_field_type_string_set_encoding(
1876 struct bt_ctf_field_type
*string_field_type
,
1877 enum bt_ctf_string_encoding encoding
);
1882 @defgroup ctfirstructfieldtype CTF IR structure field type
1883 @ingroup ctfirfieldtypes
1884 @brief CTF IR structure field type.
1887 #include <babeltrace/ctf-ir/field-types.h>
1890 A CTF IR <strong><em>structure field type</em></strong> is
1891 a field type that you can use to create concrete @structfields.
1893 You can create a structure field type
1894 with bt_ctf_field_type_structure_create(). This function creates
1895 an empty structure field type, with no fields.
1897 You can add a field to a structure field type with
1898 bt_ctf_field_type_structure_add_field(). Two fields in a structure
1899 field type cannot have the same name.
1901 You can set the \em minimum alignment of the structure fields described
1902 by a structure field type with the common
1903 bt_ctf_field_type_set_alignment() function. The \em effective alignment
1904 of the structure fields described by a structure field type, as per
1905 <a href="http://diamon.org/ctf/">CTF</a>, is the \em maximum value amongst
1906 the effective alignments of all its fields. Note that the effective
1907 alignment of @varfields is always 1.
1909 You can set the byte order of <em>all the contained fields</em>,
1910 recursively, of a structure field type with the common
1911 bt_ctf_field_type_set_byte_order() function.
1913 @sa ctfirstructfield
1916 @addtogroup ctfirstructfieldtype
1921 @brief Creates a default, empty @structft.
1923 @returns Created structure field type,
1924 or \c NULL on error.
1926 @postsuccessrefcountret1
1928 extern struct bt_ctf_field_type
*bt_ctf_field_type_structure_create(void);
1931 @brief Returns the number of fields contained in the
1932 @structft \p struct_field_type.
1934 @param[in] struct_field_type Structure field type of which to get
1935 the number of contained fields.
1936 @returns Number of fields contained in
1937 \p struct_field_type, or a negative
1940 @prenotnull{struct_field_type}
1941 @preisstructft{struct_field_type}
1942 @postrefcountsame{struct_field_type}
1944 extern int64_t bt_ctf_field_type_structure_get_field_count(
1945 struct bt_ctf_field_type
*struct_field_type
);
1948 @brief Returns the field of the @structft \p struct_field_type
1951 On success, the field's type is placed in \p *field_type if
1952 \p field_type is not \c NULL. The field's name is placed in
1953 \p *field_name if \p field_name is not \c NULL.
1954 \p struct_field_type remains the sole owner of \p *field_name.
1956 @param[in] struct_field_type Structure field type of which to get
1957 the field at index \p index.
1958 @param[out] field_name Returned name of the field at index
1959 \p index (can be \c NULL).
1960 @param[out] field_type Returned field type of the field
1961 at index \p index (can be \c NULL).
1962 @param[in] index Index of the field to get from
1963 \p struct_field_type.
1964 @returns 0 on success, or a negative value on error.
1966 @prenotnull{struct_field_type}
1967 @preisstructft{struct_field_type}
1968 @pre \p index is lesser than the number of fields contained in the
1969 structure field type \p struct_field_type (see
1970 bt_ctf_field_type_structure_get_field_count()).
1971 @postrefcountsame{struct_field_type}
1972 @post <strong>On success</strong>, the returned field's type is placed
1973 in \p *field_type and its reference count is incremented.
1975 @sa bt_ctf_field_type_structure_get_field_type_by_name(): Finds a
1976 structure field type's field by name.
1978 extern int bt_ctf_field_type_structure_get_field_by_index(
1979 struct bt_ctf_field_type
*struct_field_type
,
1980 const char **field_name
, struct bt_ctf_field_type
**field_type
,
1983 /* Pre-2.0 CTF writer compatibility */
1984 #define bt_ctf_field_type_structure_get_field bt_ctf_field_type_structure_get_field_by_index
1987 @brief Returns the type of the field named \p field_name found in
1988 the @structft \p struct_field_type.
1990 @param[in] struct_field_type Structure field type of which to get
1992 @param[in] field_name Name of the field to find.
1993 @returns Type of the field named \p field_name in
1994 \p struct_field_type, or
1997 @prenotnull{struct_field_type}
1998 @prenotnull{field_name}
1999 @preisstructft{struct_field_type}
2000 @postrefcountsame{struct_field_type}
2001 @postsuccessrefcountretinc
2003 @sa bt_ctf_field_type_structure_get_field_by_index(): Finds a
2004 structure field type's field by index.
2007 struct bt_ctf_field_type
*bt_ctf_field_type_structure_get_field_type_by_name(
2008 struct bt_ctf_field_type
*struct_field_type
,
2009 const char *field_name
);
2012 @brief Adds a field named \p field_name with the @ft
2013 \p field_type to the @structft \p struct_field_type.
2015 On success, \p field_type becomes the child of \p struct_field_type.
2017 This function adds the new field after the current last field of
2018 \p struct_field_type (append mode).
2020 You \em cannot add a field named \p field_name if there's already a
2021 field named \p field_name in \p struct_field_type.
2023 @param[in] struct_field_type Structure field type to which to add
2025 @param[in] field_type Field type of the field to add to
2026 \p struct_field_type.
2027 @param[in] field_name Name of the field to add to
2028 \p struct_field_type
2029 (copied on success).
2030 @returns 0 on success, or a negative value on error.
2032 @prenotnull{struct_field_type}
2033 @prenotnull{field_type}
2034 @prenotnull{field_name}
2035 @preisstructft{struct_field_type}
2036 @pre \p field_type is not and does not contain \p struct_field_type,
2037 recursively, as a field's type.
2038 @prehot{struct_field_type}
2039 @postrefcountsame{struct_field_type}
2040 @postsuccessrefcountinc{field_type}
2042 extern int bt_ctf_field_type_structure_add_field(
2043 struct bt_ctf_field_type
*struct_field_type
,
2044 struct bt_ctf_field_type
*field_type
,
2045 const char *field_name
);
2050 @defgroup ctfirarrayfieldtype CTF IR array field type
2051 @ingroup ctfirfieldtypes
2052 @brief CTF IR array field type.
2055 #include <babeltrace/ctf-ir/field-types.h>
2058 A CTF IR <strong><em>array field type</em></strong> is a field type that
2059 you can use to create concrete @arrayfields.
2061 You can create an array field type
2062 with bt_ctf_field_type_array_create(). This function needs
2063 the @ft of the fields contained by the array fields described by the
2064 array field type to create.
2069 @addtogroup ctfirarrayfieldtype
2074 @brief Creates a default @arrayft with
2075 \p element_field_type as the field type of the fields contained
2076 in its described @arrayfields of length \p length.
2078 @param[in] element_field_type Field type of the fields contained in
2079 the array fields described by the
2080 created array field type.
2081 @param[in] length Length of the array fields described by
2082 the created array field type.
2083 @returns Created array field type, or
2086 @prenotnull{element_field_type}
2087 @postsuccessrefcountinc{element_field_type}
2088 @postsuccessrefcountret1
2090 extern struct bt_ctf_field_type
*bt_ctf_field_type_array_create(
2091 struct bt_ctf_field_type
*element_field_type
,
2092 unsigned int length
);
2095 @brief Returns the @ft of the @fields contained in
2096 the @arrayfields described by the @arrayft \p array_field_type.
2098 @param[in] array_field_type Array field type of which to get
2099 the type of the fields contained in its
2100 described array fields.
2101 @returns Type of the fields contained in the
2102 array fields described by
2103 \p array_field_type, or \c NULL
2106 @prenotnull{array_field_type}
2107 @preisarrayft{array_field_type}
2108 @postrefcountsame{array_field_type}
2109 @postsuccessrefcountretinc
2111 extern struct bt_ctf_field_type
*bt_ctf_field_type_array_get_element_type(
2112 struct bt_ctf_field_type
*array_field_type
);
2115 @brief Returns the number of @fields contained in the
2116 @arrayfields described by the @arrayft \p array_field_type.
2118 @param[in] array_field_type Array field type of which to get
2119 the number of fields contained in its
2120 described array fields.
2121 @returns Number of fields contained in the
2122 array fields described by
2123 \p array_field_type, or a negative value
2126 @prenotnull{array_field_type}
2127 @preisarrayft{array_field_type}
2128 @postrefcountsame{array_field_type}
2130 extern int64_t bt_ctf_field_type_array_get_length(
2131 struct bt_ctf_field_type
*array_field_type
);
2136 @defgroup ctfirseqfieldtype CTF IR sequence field type
2137 @ingroup ctfirfieldtypes
2138 @brief CTF IR sequence field type.
2141 #include <babeltrace/ctf-ir/field-types.h>
2144 A CTF IR <strong><em>sequence field type</em></strong> is
2145 a field type that you can use to create concrete @seqfields.
2147 You can create a sequence field type with
2148 bt_ctf_field_type_sequence_create(). This function needs the @ft
2149 of the fields contained by the sequence fields described by the created
2150 sequence field type. This function also needs the length name of the
2151 sequence field type to create. The length name is used to automatically
2152 resolve the length's field type. See \ref ctfirfieldtypes to learn more
2153 about the automatic resolving.
2158 @addtogroup ctfirseqfieldtype
2163 @brief Creates a default @seqft with \p element_field_type as the
2164 @ft of the @fields contained in its described @seqfields
2165 with the length name \p length_name.
2167 \p length_name can be an absolute or relative reference. See
2168 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2170 @param[in] element_field_type Field type of the fields contained in
2171 the sequence fields described by the
2172 created sequence field type.
2173 @param[in] length_name Length name (copied on success).
2174 @returns Created array field type, or
2177 @prenotnull{element_field_type}
2178 @prenotnull{length_name}
2179 @postsuccessrefcountinc{element_field_type}
2180 @postsuccessrefcountret1
2182 extern struct bt_ctf_field_type
*bt_ctf_field_type_sequence_create(
2183 struct bt_ctf_field_type
*element_field_type
,
2184 const char *length_name
);
2187 @brief Returns the @ft of the @fields contained in the @seqft
2188 described by the @seqft \p sequence_field_type.
2190 @param[in] sequence_field_type Sequence field type of which to get
2191 the type of the fields contained in its
2192 described sequence fields.
2193 @returns Type of the fields contained in the
2194 sequence fields described by
2195 \p sequence_field_type, or \c NULL
2198 @prenotnull{sequence_field_type}
2199 @preisseqft{sequence_field_type}
2200 @postrefcountsame{sequence_field_type}
2201 @postsuccessrefcountretinc
2203 extern struct bt_ctf_field_type
*bt_ctf_field_type_sequence_get_element_type(
2204 struct bt_ctf_field_type
*sequence_field_type
);
2207 @brief Returns the length name of the @seqft \p sequence_field_type.
2209 On success, \p sequence_field_type remains the sole owner of
2210 the returned string.
2212 @param[in] sequence_field_type Sequence field type of which to get the
2214 @returns Length name of \p sequence_field_type,
2215 or \c NULL on error.
2217 @prenotnull{sequence_field_type}
2218 @preisseqft{sequence_field_type}
2220 @sa bt_ctf_field_type_sequence_get_length_field_path(): Returns the
2221 length's CTF IR field path of a given sequence field type.
2223 extern const char *bt_ctf_field_type_sequence_get_length_field_name(
2224 struct bt_ctf_field_type
*sequence_field_type
);
2227 @brief Returns the length's CTF IR field path of the @seqft
2228 \p sequence_field_type.
2230 The length's field path of a sequence field type is set when automatic
2231 resolving is performed (see \ref ctfirfieldtypes).
2233 @param[in] sequence_field_type Sequence field type of which to get the
2234 length's field path.
2235 @returns Length's field path of
2236 \p sequence_field_type, or
2237 \c NULL if the length's field path is
2238 not set yet is not set or on error.
2240 @prenotnull{sequence_field_type}
2241 @preisseqft{sequence_field_type}
2242 @postsuccessrefcountretinc
2244 @sa bt_ctf_field_type_sequence_get_length_field_name(): Returns the
2245 length's name of a given sequence field type.
2247 extern struct bt_ctf_field_path
*bt_ctf_field_type_sequence_get_length_field_path(
2248 struct bt_ctf_field_type
*sequence_field_type
);
2253 @defgroup ctfirvarfieldtype CTF IR variant field type
2254 @ingroup ctfirfieldtypes
2255 @brief CTF IR variant field type.
2258 #include <babeltrace/ctf-ir/field-types.h>
2261 A CTF IR <strong><em>variant field type</em></strong> is
2262 a field type that you can use to create concrete @varfields.
2264 You can create a variant field type with
2265 bt_ctf_field_type_variant_create(). This function expects you to pass
2266 both the tag's @enumft and the tag name of the variant field type to
2267 create. The tag's field type is optional, as the Babeltrace system can
2268 automatically resolve it using the tag name. You can leave the tag name
2269 to \c NULL initially, and set it later with
2270 bt_ctf_field_type_variant_set_tag_name(). The tag name must be set when
2271 the variant field type is frozen. See \ref ctfirfieldtypes to learn more
2272 about the automatic resolving and the conditions under which a field
2275 You can add a field to a variant field type with
2276 bt_ctf_field_type_variant_add_field(). All the field names of a
2277 variant field type \em must exist as mapping names in its tag's @enumft.
2279 The effective alignment of the @varfields described by a
2280 variant field type is always 1, but the individual fields of a
2281 @varfield can have custom alignments.
2283 You can set the byte order of <em>all the contained fields</em>,
2284 recursively, of a variant field type with the common
2285 bt_ctf_field_type_set_byte_order() function.
2290 @addtogroup ctfirvarfieldtype
2295 @brief Creates a default, empty @varft with the tag's @enumft
2296 \p tag_field_type and the tag name \p tag_name.
2298 \p tag_field_type can be \c NULL; the tag's field type can be
2299 automatically resolved from the variant field type's tag name (see
2300 \ref ctfirfieldtypes). If \p tag_name is \c NULL, it \em must be set
2301 with bt_ctf_field_type_variant_set_tag_name() \em before the variant
2302 field type is frozen.
2304 \p tag_name can be an absolute or relative reference. See
2305 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2307 @param[in] tag_field_type Tag's enumeration field type
2309 @param[in] tag_name Tag name (copied on success,
2311 @returns Created variant field type, or
2314 @pre \p tag_field_type is an enumeration field type or \c NULL.
2315 @post <strong>On success, if \p tag_field_type is not \c NULL</strong>,
2316 its reference count is incremented.
2317 @postsuccessrefcountret1
2319 extern struct bt_ctf_field_type
*bt_ctf_field_type_variant_create(
2320 struct bt_ctf_field_type
*tag_field_type
,
2321 const char *tag_name
);
2324 @brief Returns the tag's @enumft of the @varft \p variant_field_type.
2326 @param[in] variant_field_type Variant field type of which to get
2327 the tag's enumeration field type.
2328 @returns Tag's enumeration field type of
2329 \p variant_field_type, or \c NULL if the
2330 tag's field type is not set or on
2333 @prenotnull{variant_field_type}
2334 @preisvarft{variant_field_type}
2335 @postrefcountsame{variant_field_type}
2336 @postsuccessrefcountretinc
2338 extern struct bt_ctf_field_type
*bt_ctf_field_type_variant_get_tag_type(
2339 struct bt_ctf_field_type
*variant_field_type
);
2342 @brief Returns the tag name of the @varft \p variant_field_type.
2344 On success, \p variant_field_type remains the sole owner of
2345 the returned string.
2347 @param[in] variant_field_type Variant field type of which to get the
2349 @returns Tag name of \p variant_field_type, or
2350 \c NULL if the tag name is not set or
2353 @prenotnull{variant_field_type}
2354 @preisvarft{variant_field_type}
2356 @sa bt_ctf_field_type_variant_set_tag_name(): Sets the tag name of
2357 a given variant field type.
2358 @sa bt_ctf_field_type_variant_get_tag_field_path(): Returns the tag's
2359 CTF IR field path of a given variant field type.
2361 extern const char *bt_ctf_field_type_variant_get_tag_name(
2362 struct bt_ctf_field_type
*variant_field_type
);
2365 @brief Sets the tag name of the @varft \p variant_field_type.
2367 \p tag_name can be an absolute or relative reference. See
2368 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2370 @param[in] variant_field_type Variant field type of which to set
2372 @param[in] tag_name Tag name of \p variant_field_type
2373 (copied on success).
2374 @returns 0 on success, or a negative value on error.
2376 @prenotnull{variant_field_type}
2378 @prehot{variant_field_type}
2379 @postrefcountsame{variant_field_type}
2381 @sa bt_ctf_field_type_variant_get_tag_name(): Returns the tag name of
2382 a given variant field type.
2384 extern int bt_ctf_field_type_variant_set_tag_name(
2385 struct bt_ctf_field_type
*variant_field_type
,
2386 const char *tag_name
);
2389 @brief Returns the tag's CTF IR field path of the @varft
2390 \p variant_field_type.
2392 The tag's field path of a variant field type is set when automatic
2393 resolving is performed (see \ref ctfirfieldtypes).
2395 @param[in] variant_field_type Variant field type of which to get the
2397 @returns Tag's field path of
2398 \p variant_field_type, or
2399 \c NULL if the tag's field path is not
2400 set yet is not set or on error.
2402 @prenotnull{variant_field_type}
2403 @preisvarft{variant_field_type}
2404 @postsuccessrefcountretinc
2406 @sa bt_ctf_field_type_variant_get_tag_name(): Returns the tag's
2407 name of a given variant field type.
2409 extern struct bt_ctf_field_path
*bt_ctf_field_type_variant_get_tag_field_path(
2410 struct bt_ctf_field_type
*variant_field_type
);
2413 @brief Returns the number of fields (choices) contained in the @varft
2414 \p variant_field_type.
2416 @param[in] variant_field_type Variant field type of which to get
2417 the number of contained fields.
2418 @returns Number of fields contained in
2419 \p variant_field_type, or a negative
2422 @prenotnull{variant_field_type}
2423 @preisvarft{variant_field_type}
2424 @postrefcountsame{variant_field_type}
2426 extern int64_t bt_ctf_field_type_variant_get_field_count(
2427 struct bt_ctf_field_type
*variant_field_type
);
2430 @brief Returns the field (choice) of the @varft \p variant_field_type
2433 On success, the field's type is placed in \p *field_type if
2434 \p field_type is not \c NULL. The field's name is placed in
2435 \p *field_name if \p field_name is not \c NULL.
2436 \p variant_field_type remains the sole owner of \p *field_name.
2438 @param[in] variant_field_type Variant field type of which to get
2439 the field at index \p index.
2440 @param[out] field_name Returned name of the field at index
2441 \p index (can be \c NULL).
2442 @param[out] field_type Returned field type of the field
2443 at index \p index (can be \c NULL).
2444 @param[in] index Index of the field to get from
2445 \p variant_field_type.
2446 @returns 0 on success, or a negative value on error.
2448 @prenotnull{variant_field_type}
2449 @preisvarft{variant_field_type}
2450 @pre \p index is lesser than the number of fields contained in the
2451 variant field type \p variant_field_type (see
2452 bt_ctf_field_type_variant_get_field_count()).
2453 @postrefcountsame{variant_field_type}
2454 @post <strong>On success</strong>, the returned field's type is placed
2455 in \p *field_type and its reference count is incremented.
2457 @sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant
2458 field type's field by name.
2459 @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant
2460 field type's field by current tag value.
2462 extern int bt_ctf_field_type_variant_get_field_by_index(
2463 struct bt_ctf_field_type
*variant_field_type
,
2464 const char **field_name
,
2465 struct bt_ctf_field_type
**field_type
, uint64_t index
);
2467 /* Pre-2.0 CTF writer compatibility */
2468 #define bt_ctf_field_type_variant_get_field bt_ctf_field_type_variant_get_field_by_index
2471 @brief Returns the type of the field (choice) named \p field_name
2472 found in the @varft \p variant_field_type.
2474 @param[in] variant_field_type Variant field type of which to get
2476 @param[in] field_name Name of the field to find.
2477 @returns Type of the field named \p field_name in
2478 \p variant_field_type, or
2481 @prenotnull{variant_field_type}
2482 @prenotnull{field_name}
2483 @preisvarft{variant_field_type}
2484 @postrefcountsame{variant_field_type}
2485 @postsuccessrefcountretinc
2487 @sa bt_ctf_field_type_variant_get_field_by_index(): Finds a variant field type's
2489 @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant
2490 field type's field by current tag value.
2493 struct bt_ctf_field_type
*bt_ctf_field_type_variant_get_field_type_by_name(
2494 struct bt_ctf_field_type
*variant_field_type
,
2495 const char *field_name
);
2498 @brief Returns the type of the field (choice) selected by the value of
2499 the @enumfield \p tag_field in the @varft \p variant_field_type.
2501 \p tag_field is the current tag value.
2503 The field type of \p tag_field, as returned by bt_ctf_field_get_type(),
2504 \em must be equivalent to the field type returned by
2505 bt_ctf_field_type_variant_get_tag_type() for \p variant_field_type.
2507 @param[in] variant_field_type Variant field type of which to get
2509 @param[in] tag_field Current tag value (variant field type's
2511 @returns Type of the field selected by
2512 \p tag_field in \p variant_field_type,
2513 or \c NULL on error.
2515 @prenotnull{variant_field_type}
2516 @prenotnull{tag_field}
2517 @preisvarft{variant_field_type}
2518 @preisenumfield{tag_field}
2519 @postrefcountsame{variant_field_type}
2520 @postrefcountsame{tag_field}
2521 @postsuccessrefcountretinc
2523 @sa bt_ctf_field_type_variant_get_field_by_index(): Finds a variant field type's
2525 @sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant
2526 field type's field by name.
2529 struct bt_ctf_field_type
*bt_ctf_field_type_variant_get_field_type_from_tag(
2530 struct bt_ctf_field_type
*variant_field_type
,
2531 struct bt_ctf_field
*tag_field
);
2534 @brief Adds a field (a choice) named \p field_name with the @ft
2535 \p field_type to the @varft \p variant_field_type.
2537 On success, \p field_type becomes the child of \p variant_field_type.
2539 You \em cannot add a field named \p field_name if there's already a
2540 field named \p field_name in \p variant_field_type.
2542 \p field_name \em must name an existing mapping in the tag's
2543 enumeration field type of \p variant_field_type.
2545 @param[in] variant_field_type Variant field type to which to add
2547 @param[in] field_type Field type of the field to add to
2548 \p variant_field_type.
2549 @param[in] field_name Name of the field to add to
2550 \p variant_field_type
2551 (copied on success).
2552 @returns 0 on success, or a negative value on error.
2554 @prenotnull{variant_field_type}
2555 @prenotnull{field_type}
2556 @prenotnull{field_name}
2557 @preisvarft{variant_field_type}
2558 @pre \p field_type is not and does not contain \p variant_field_type,
2559 recursively, as a field's type.
2560 @prehot{variant_field_type}
2561 @postrefcountsame{variant_field_type}
2562 @postsuccessrefcountinc{field_type}
2564 extern int bt_ctf_field_type_variant_add_field(
2565 struct bt_ctf_field_type
*variant_field_type
,
2566 struct bt_ctf_field_type
*field_type
,
2567 const char *field_name
);
2575 #endif /* BABELTRACE_CTF_IR_FIELD_TYPES_H */