1 #ifndef BABELTRACE_CTF_IR_FIELD_TYPES_H
2 #define BABELTRACE_CTF_IR_FIELD_TYPES_H
5 * BabelTrace - CTF IR: Event field types
7 * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
9 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
11 * Permission is hereby granted, free of charge, to any person obtaining a copy
12 * of this software and associated documentation files (the "Software"), to deal
13 * in the Software without restriction, including without limitation the rights
14 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15 * copies of the Software, and to permit persons to whom the Software is
16 * furnished to do so, subject to the following conditions:
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
29 * The Common Trace Format (CTF) Specification is available at
30 * http://www.efficios.com/ctf
34 #include <babeltrace/types.h>
44 @defgroup ctfirfieldtypes CTF IR field types
46 @brief CTF IR field types.
49 #include <babeltrace/ctf-ir/field-types.h>
52 A CTF IR <strong><em>field type</em></strong> is a field type that you
53 can use to create concrete @fields.
55 You can create a @field object from a CTF IR field type object
56 with bt_ctf_field_create().
58 In the CTF IR hierarchy, you can set the root field types of three
61 - \ref ctfirtraceclass
62 - Trace packet header field type: bt_ctf_trace_set_packet_header_type().
63 - \ref ctfirstreamclass
64 - Stream packet context field type:
65 bt_ctf_stream_class_set_packet_context_type().
66 - Stream event header field type:
67 bt_ctf_stream_class_set_event_header_type().
68 - Stream event context field type:
69 bt_ctf_stream_class_set_event_context_type().
70 - \ref ctfireventclass
71 - Event context field type: bt_ctf_event_class_set_context_type().
72 - Event payload field type: bt_ctf_event_class_set_payload_type().
74 As of Babeltrace \btversion, those six previous "root" field types
75 \em must be @structft objects.
77 If, at any level within a given root field type, you add a @seqft or a
78 @varft, you do not need to specify its associated length
79 or tag field type: the length or tag string is enough for the Babeltrace
80 system to resolve the needed field type depending on where this
81 dynamic field type is located within the whole hierarchy. It is
82 guaranteed that this automatic resolving is performed for all the field
83 types contained in a given
84 \link ctfirstreamclass CTF IR stream class\endlink (and in its
85 children \link ctfireventclass CTF IR event classes\endlink) once you
86 add it to a \link ctfirtraceclass CTF IR trace class\endlink with
87 bt_ctf_trace_add_stream_class(). Once a stream class is the child of
88 a trace class, this automatic resolving is performed for the field
89 types of an event class when you add it with
90 bt_ctf_stream_class_add_event_class(). If the system cannot find a path
91 to a field in the hierarchy for a dynamic field type, the adding
94 The standard CTF field types are:
100 <th>CTF IR field which you can create from this field type
103 <td>#BT_CTF_FIELD_TYPE_ID_INTEGER
104 <td>\ref ctfirintfieldtype
105 <td>\ref ctfirintfield
108 <td>#BT_CTF_FIELD_TYPE_ID_FLOAT
109 <td>\ref ctfirfloatfieldtype
110 <td>\ref ctfirfloatfield
113 <td>#BT_CTF_FIELD_TYPE_ID_ENUM
114 <td>\ref ctfirenumfieldtype
115 <td>\ref ctfirenumfield
118 <td>#BT_CTF_FIELD_TYPE_ID_STRING
119 <td>\ref ctfirstringfieldtype
120 <td>\ref ctfirstringfield
123 <td>#BT_CTF_FIELD_TYPE_ID_STRUCT
124 <td>\ref ctfirstructfieldtype
125 <td>\ref ctfirstructfield
128 <td>#BT_CTF_FIELD_TYPE_ID_ARRAY
129 <td>\ref ctfirarrayfieldtype
130 <td>\ref ctfirarrayfield
133 <td>#BT_CTF_FIELD_TYPE_ID_SEQUENCE
134 <td>\ref ctfirseqfieldtype
135 <td>\ref ctfirseqfield
138 <td>#BT_CTF_FIELD_TYPE_ID_VARIANT
139 <td>\ref ctfirvarfieldtype
140 <td>\ref ctfirvarfield
144 Each field type has its own <strong>type ID</strong> (see
145 #bt_ctf_field_type_id). You get the type ID of a field type object
146 with bt_ctf_field_type_get_type_id().
148 You can get a deep copy of a field type with bt_ctf_field_type_copy().
149 This function resets, in the field type copy, the resolved field type
150 of the dynamic field types. The automatic resolving can be done again
151 when you eventually call bt_ctf_event_create(),
152 bt_ctf_stream_class_add_event_class(), or
153 bt_ctf_trace_add_stream_class().
155 You \em must always use bt_ctf_field_type_compare() to compare two
156 field types. Since some parts of the Babeltrace system can copy field
157 types behind the scenes, you \em cannot rely on a simple field type
160 As with any Babeltrace object, CTF IR field type objects have
161 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
162 counts</a>. See \ref refs to learn more about the reference counting
163 management of Babeltrace objects.
165 The following functions can \em freeze field type objects:
167 - bt_ctf_field_create() freezes its field type parameter.
168 - bt_ctf_stream_class_add_event_class(), if its
169 \link ctfirstreamclass CTF IR stream class\endlink parameter has a
170 \link ctfirtraceclass CTF IR trace class\endlink parent, freezes
171 the root field types of its
172 \link ctfireventclass CTF IR event class\endlink parameter.
173 - bt_ctf_trace_add_stream_class() freezes the root field types of the
174 whole trace class hierarchy (trace class, children stream classes,
175 and their children event classes).
176 - bt_ctf_writer_create_stream() freezes the root field types of the
177 whole CTF writer's trace class hierarchy.
178 - bt_ctf_event_create() freezes the root field types of its event class
179 parameter and of ther parent stream class of this event class.
181 You cannot modify a frozen field type object: it is considered
182 immutable, except for \link refs reference counting\endlink.
185 @sa \ref ctfirfieldtypesexamples "Examples"
188 @brief CTF IR field types type and functions.
191 @addtogroup ctfirfieldtypes
196 @struct bt_ctf_field_type
197 @brief A CTF IR field type.
200 struct bt_ctf_field_type
;
201 struct bt_ctf_event_class
;
204 struct bt_ctf_field_path
;
205 struct bt_ctf_field_type_enumeration_mapping_iterator
;
207 /** @cond DOCUMENT */
210 * Babeltrace 1.x enumerations that were also used in CTF writer's API.
211 * They are left here for backward compatibility reasons, but
212 * enum bt_ctf_field_type_id and enum bt_ctf_string_encoding should be used
213 * in new code. Both new enumerations are compatible with their legacy
217 CTF_TYPE_UNKNOWN
= -1,
218 CTF_TYPE_INTEGER
= 0,
223 CTF_TYPE_UNTAGGED_VARIANT
= 5,
224 CTF_TYPE_VARIANT
= 5,
226 CTF_TYPE_SEQUENCE
= 7,
233 enum ctf_string_encoding
{
246 /// Unknown, used for errors.
247 BT_CTF_SCOPE_UNKNOWN
= -1,
249 /// Trace packet header.
250 BT_CTF_SCOPE_TRACE_PACKET_HEADER
= 1,
252 /// Stream packet context.
253 BT_CTF_SCOPE_STREAM_PACKET_CONTEXT
= 2,
255 /// Stream event header.
256 BT_CTF_SCOPE_STREAM_EVENT_HEADER
= 3,
258 /// Stream event context.
259 BT_CTF_SCOPE_STREAM_EVENT_CONTEXT
= 4,
262 BT_CTF_SCOPE_EVENT_CONTEXT
= 5,
265 BT_CTF_SCOPE_EVENT_PAYLOAD
= 6,
268 BT_CTF_SCOPE_ENV
= 0,
269 BT_CTF_SCOPE_EVENT_FIELDS
= 6,
274 @name Type information
279 @brief Type ID of a @ft.
281 enum bt_ctf_field_type_id
{
282 /// Unknown, used for errors.
283 BT_CTF_FIELD_TYPE_ID_UNKNOWN
= CTF_TYPE_UNKNOWN
,
285 /// \ref ctfirintfieldtype
286 BT_CTF_FIELD_TYPE_ID_INTEGER
= CTF_TYPE_INTEGER
,
288 /// \ref ctfirfloatfieldtype
289 BT_CTF_FIELD_TYPE_ID_FLOAT
= CTF_TYPE_FLOAT
,
291 /// \ref ctfirenumfieldtype
292 BT_CTF_FIELD_TYPE_ID_ENUM
= CTF_TYPE_ENUM
,
294 /// \ref ctfirstringfieldtype
295 BT_CTF_FIELD_TYPE_ID_STRING
= CTF_TYPE_STRING
,
297 /// \ref ctfirstructfieldtype
298 BT_CTF_FIELD_TYPE_ID_STRUCT
= CTF_TYPE_STRUCT
,
300 /// \ref ctfirarrayfieldtype
301 BT_CTF_FIELD_TYPE_ID_ARRAY
= CTF_TYPE_ARRAY
,
303 /// \ref ctfirseqfieldtype
304 BT_CTF_FIELD_TYPE_ID_SEQUENCE
= CTF_TYPE_SEQUENCE
,
306 /// \ref ctfirvarfieldtype
307 BT_CTF_FIELD_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_FIELD_TYPE_ID_UNKNOWN on error.
320 @prenotnull{field_type}
321 @postrefcountsame{field_type}
323 @sa #bt_ctf_field_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_field_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 #BT_TRUE if \p field_type is an integer field type,
349 or #BT_FALSE 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 bt_bool
bt_ctf_field_type_is_integer(
359 struct bt_ctf_field_type
*field_type
);
362 @brief Returns whether or not the @ft \p field_type is a @floatft.
364 @param[in] field_type Field type to check (can be \c NULL).
365 @returns #BT_TRUE if \p field_type is a floating point
366 #BT_FALSE field type,
367 or 0 otherwise (including if \p field_type is
370 @postrefcountsame{field_type}
372 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
375 extern bt_bool
bt_ctf_field_type_is_floating_point(
376 struct bt_ctf_field_type
*field_type
);
379 @brief Returns whether or not the @ft \p field_type is a @enumft.
381 @param[in] field_type Field type to check (can be \c NULL).
382 @returns #BT_TRUE if \p field_type is an enumeration field type,
383 or #BT_FALSE otherwise (including if \p field_type is
386 @postrefcountsame{field_type}
388 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
391 extern bt_bool
bt_ctf_field_type_is_enumeration(
392 struct bt_ctf_field_type
*field_type
);
395 @brief Returns whether or not the @ft \p field_type is a @stringft.
397 @param[in] field_type Field type to check (can be \c NULL).
398 @returns #BT_TRUE if \p field_type is a string field type,
399 or #BT_FALSE otherwise (including if \p field_type is
402 @postrefcountsame{field_type}
404 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
407 extern bt_bool
bt_ctf_field_type_is_string(
408 struct bt_ctf_field_type
*field_type
);
411 @brief Returns whether or not the @ft \p field_type is a @structft.
413 @param[in] field_type Field type to check (can be \c NULL).
414 @returns #BT_TRUE if \p field_type is a structure field type,
415 or #BT_FALSE otherwise (including if \p field_type is
418 @postrefcountsame{field_type}
420 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
423 extern bt_bool
bt_ctf_field_type_is_structure(
424 struct bt_ctf_field_type
*field_type
);
427 @brief Returns whether or not the @ft \p field_type is a @arrayft.
429 @param[in] field_type Field type to check (can be \c NULL).
430 @returns #BT_TRUE if \p field_type is an array field type,
431 or #BT_FALSE otherwise (including if \p field_type is
434 @postrefcountsame{field_type}
436 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
439 extern bt_bool
bt_ctf_field_type_is_array(
440 struct bt_ctf_field_type
*field_type
);
443 @brief Returns whether or not the @ft \p field_type is a @seqft.
445 @param[in] field_type Field type to check (can be \c NULL).
446 @returns #BT_TRUE if \p field_type is a sequence field type,
447 or #BT_FALSE otherwise (including if \p field_type is
450 @postrefcountsame{field_type}
452 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
455 extern bt_bool
bt_ctf_field_type_is_sequence(
456 struct bt_ctf_field_type
*field_type
);
459 @brief Returns whether or not the @ft \p field_type is a @varft.
461 @param[in] field_type Field type to check (can be \c NULL).
462 @returns #BT_TRUE if \p field_type is a variant field type,
463 or #BT_FALSE otherwise (including if \p field_type is
466 @postrefcountsame{field_type}
468 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
471 extern bt_bool
bt_ctf_field_type_is_variant(
472 struct bt_ctf_field_type
*field_type
);
477 @name Common properties types and functions
482 @brief <a href="https://en.wikipedia.org/wiki/Endianness">Byte order</a>
485 enum bt_ctf_byte_order
{
486 /// Unknown, used for errors.
487 BT_CTF_BYTE_ORDER_UNKNOWN
= -1,
490 * Note that native, in the context of the CTF specification, is defined
491 * as "the byte order described in the trace" and does not mean that the
492 * host's endianness will be used.
494 /// Native (default) byte order.
495 BT_CTF_BYTE_ORDER_NATIVE
= 0,
498 Unspecified byte order; the initial native byte order of a
499 \link ctfirtraceclass CTF IR trace class\endlink.
501 BT_CTF_BYTE_ORDER_UNSPECIFIED
,
504 BT_CTF_BYTE_ORDER_LITTLE_ENDIAN
,
507 BT_CTF_BYTE_ORDER_BIG_ENDIAN
,
509 /// Network byte order (big-endian).
510 BT_CTF_BYTE_ORDER_NETWORK
,
514 @brief String encoding of a @ft.
516 enum bt_ctf_string_encoding
{
517 /// Unknown, used for errors.
518 BT_CTF_STRING_ENCODING_UNKNOWN
= CTF_STRING_UNKNOWN
,
521 BT_CTF_STRING_ENCODING_NONE
= CTF_STRING_NONE
,
523 /// <a href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a>.
524 BT_CTF_STRING_ENCODING_UTF8
= CTF_STRING_UTF8
,
526 /// <a href="https://en.wikipedia.org/wiki/ASCII">ASCII</a>.
527 BT_CTF_STRING_ENCODING_ASCII
= CTF_STRING_ASCII
,
531 @brief Returns the alignment of the @fields described by
532 the @ft \p field_type.
534 @param[in] field_type Field type which describes the
535 fields of which to get the alignment.
536 @returns Alignment of the fields described by
537 \p field_type, or a negative value on error.
539 @prenotnull{field_type}
540 @postrefcountsame{field_type}
542 @sa bt_ctf_field_type_set_alignment(): Sets the alignment
543 of the fields described by a given field type.
545 extern int bt_ctf_field_type_get_alignment(
546 struct bt_ctf_field_type
*field_type
);
549 @brief Sets the alignment of the @fields described by the
550 @ft \p field_type to \p alignment.
552 \p alignment \em must be greater than 0 and a power of two.
554 @param[in] field_type Field type which describes the fields of
555 which to set the alignment.
556 @param[in] alignment Alignment of the fields described by
558 @returns 0 on success, or a negative value on error.
560 @prenotnull{field_type}
562 @pre \p alignment is greater than 0 and a power of two.
563 @postrefcountsame{field_type}
565 @sa bt_ctf_field_type_get_alignment(): Returns the alignment of the
566 fields described by a given field type.
568 extern int bt_ctf_field_type_set_alignment(struct bt_ctf_field_type
*field_type
,
569 unsigned int alignment
);
572 @brief Returns the byte order of the @fields described by
573 the @ft \p field_type.
575 You can only call this function if \p field_type is a @intft, a
576 @floatft, or a @enumft.
578 @param[in] field_type Field type which describes the
579 fields of which to get the byte order.
580 @returns Byte order of the fields described by
581 \p field_type, or #BT_CTF_BYTE_ORDER_UNKNOWN on
584 @prenotnull{field_type}
585 @pre \p field_type is a @intft, a @floatft, or a @enumft.
586 @postrefcountsame{field_type}
588 @sa bt_ctf_field_type_set_byte_order(): Sets the byte order
589 of the fields described by a given field type.
591 extern enum bt_ctf_byte_order
bt_ctf_field_type_get_byte_order(
592 struct bt_ctf_field_type
*field_type
);
595 @brief Sets the byte order of the @fields described by the
596 @ft \p field_type to \p byte_order.
598 If \p field_type is a compound field type, this function also
599 recursively sets the byte order of its children to \p byte_order.
601 @param[in] field_type Field type which describes the fields of
602 which to set the byte order.
603 @param[in] byte_order Alignment of the fields described by
605 @returns 0 on success, or a negative value on error.
607 @prenotnull{field_type}
609 @pre \p byte_order is #BT_CTF_BYTE_ORDER_NATIVE,
610 #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN, #BT_CTF_BYTE_ORDER_BIG_ENDIAN,
611 or #BT_CTF_BYTE_ORDER_NETWORK.
612 @postrefcountsame{field_type}
614 @sa bt_ctf_field_type_get_byte_order(): Returns the byte order of the
615 fields described by a given field type.
617 extern int bt_ctf_field_type_set_byte_order(
618 struct bt_ctf_field_type
*field_type
,
619 enum bt_ctf_byte_order byte_order
);
624 @name Utility functions
629 @brief Returns whether or not the @ft \p field_type_a
630 is equivalent to the field type \p field_type_b.
632 You \em must use this function to compare two field types: it is not
633 safe to compare two pointer values directly, because, for internal
634 reasons, some parts of the Babeltrace system can copy user field types
635 and discard the original ones.
637 @param[in] field_type_a Field type to compare to \p field_type_b.
638 @param[in] field_type_b Field type to compare to \p field_type_a.
639 @returns 0 if \p field_type_a is equivalent to
640 \p field_type_b, 1 if they are not equivalent,
641 or a negative value on error.
643 @prenotnull{field_type_a}
644 @prenotnull{field_type_b}
645 @postrefcountsame{field_type_a}
646 @postrefcountsame{field_type_b}
648 extern int bt_ctf_field_type_compare(struct bt_ctf_field_type
*field_type_a
,
649 struct bt_ctf_field_type
*field_type_b
);
652 @brief Creates a \em deep copy of the @ft \p field_type.
654 You can copy a frozen field type: the resulting copy is
657 This function resets the tag field type of a copied @varft. The
658 automatic field resolving which some functions of the API perform
659 can set it again when the returned field type is used (learn more
660 in the detailed description of this module).
662 @param[in] field_type Field type to copy.
663 @returns Deep copy of \p field_type on success,
666 @prenotnull{field_type}
667 @postrefcountsame{field_type}
668 @postsuccessrefcountret1
669 @post <strong>On success</strong>, the returned field type is not frozen.
671 extern struct bt_ctf_field_type
*bt_ctf_field_type_copy(
672 struct bt_ctf_field_type
*field_type
);
679 @defgroup ctfirintfieldtype CTF IR integer field type
680 @ingroup ctfirfieldtypes
681 @brief CTF IR integer field type.
684 #include <babeltrace/ctf-ir/field-types.h>
687 A CTF IR <strong><em>integer field type</em></strong> is a field type that
688 you can use to create concrete @intfield objects.
690 You can create an integer field type
691 with bt_ctf_field_type_integer_create().
693 An integer field type has the following properties:
698 <th>Value at creation
703 <td>\b Alignment (bits) of the described integer fields
705 <td>bt_ctf_field_type_get_alignment()
706 <td>bt_ctf_field_type_set_alignment()
709 <td><strong>Byte order</strong> of the described integer fields
710 <td>#BT_CTF_BYTE_ORDER_NATIVE
711 <td>bt_ctf_field_type_get_byte_order()
712 <td>bt_ctf_field_type_set_byte_order()
715 <td><strong>Storage size</strong> (bits) of the described
717 <td>Specified at creation
718 <td>bt_ctf_field_type_integer_get_size()
719 <td>bt_ctf_field_type_integer_set_size()
722 <td><strong>Signedness</strong> of the described integer fields
724 <td>bt_ctf_field_type_integer_is_signed()
725 <td>bt_ctf_field_type_integer_set_is_signed()
728 <td><strong>Preferred display base</strong> of the described
730 <td>#BT_CTF_INTEGER_BASE_DECIMAL
731 <td>bt_ctf_field_type_integer_get_base()
732 <td>bt_ctf_field_type_integer_set_base()
735 <td>\b Encoding of the described integer fields
736 <td>#BT_CTF_STRING_ENCODING_NONE
737 <td>bt_ctf_field_type_integer_get_encoding()
738 <td>bt_ctf_field_type_integer_set_encoding()
742 \link ctfirclockclass CTF IR clock class\endlink</strong>
744 <td>bt_ctf_field_type_integer_get_mapped_clock_class()
745 <td>bt_ctf_field_type_integer_set_mapped_clock_class()
751 @sa \ref ctfirfieldtypesexamples_intfieldtype "Examples"
753 @addtogroup ctfirintfieldtype
758 @brief Preferred display base (radix) of a @intft.
760 enum bt_ctf_integer_base
{
761 /// Unknown, used for errors.
762 BT_CTF_INTEGER_BASE_UNKNOWN
= -1,
764 /// Unspecified by the tracer.
765 BT_CTF_INTEGER_BASE_UNSPECIFIED
= 0,
768 BT_CTF_INTEGER_BASE_BINARY
= 2,
771 BT_CTF_INTEGER_BASE_OCTAL
= 8,
774 BT_CTF_INTEGER_BASE_DECIMAL
= 10,
777 BT_CTF_INTEGER_BASE_HEXADECIMAL
= 16,
781 @brief Creates a default @intft with \p size bits as the storage size
782 of the @intfields it describes.
784 You can change the storage size of the integer fields described by
785 the created integer field type later with
786 bt_ctf_field_type_integer_set_size().
788 @param[in] size Storage size (bits) of the described integer fields.
789 @returns Created integer field type, or \c NULL on error.
791 @pre \p size is greater than 0 and lesser than or equal to 64.
792 @postsuccessrefcountret1
794 extern struct bt_ctf_field_type
*bt_ctf_field_type_integer_create(
798 @brief Returns the storage size, in bits, of the @intfields
799 described by the @intft \p int_field_type.
801 @param[in] int_field_type Integer field type which describes the
802 integer fields of which to get the
804 @returns Storage size (bits) of the integer
805 fields described by \p int_field_type,
806 or a negative value on error.
808 @prenotnull{int_field_type}
809 @preisintft{int_field_type}
810 @postrefcountsame{int_field_type}
812 @sa bt_ctf_field_type_integer_set_size(): Sets the storage size of the
813 integer fields described by a given integer field type.
815 extern int bt_ctf_field_type_integer_get_size(
816 struct bt_ctf_field_type
*int_field_type
);
819 @brief Sets the storage size, in bits, of the @intfields described by
820 the @intft \p int_field_type.
822 @param[in] int_field_type Integer field type which describes the
823 integer fields of which to set the
825 @param[in] size Storage size (bits) of the integer fields
826 described by \p int_field_type.
827 @returns 0 on success, or a negative value on error.
829 @prenotnull{int_field_type}
830 @preisintft{int_field_type}
831 @prehot{int_field_type}
832 @pre \p size is greater than 0 and lesser than or equal to 64.
833 @postrefcountsame{int_field_type}
835 @sa bt_ctf_field_type_integer_get_size(): Returns the storage size of
836 the integer fields described by a given integer field type.
838 extern int bt_ctf_field_type_integer_set_size(
839 struct bt_ctf_field_type
*int_field_type
, unsigned int size
);
842 @brief Returns whether or not the @intfields described by the @intft
843 \p int_field_type are signed.
845 @param[in] int_field_type Integer field type which describes the
846 integer fields of which to get the
848 @returns #BT_TRUE if the integer fields described by
849 \p int_field_type are signed, #BT_FALSE if they
852 @prenotnull{int_field_type}
853 @preisintft{int_field_type}
854 @postrefcountsame{int_field_type}
856 @sa bt_ctf_field_type_integer_set_is_signed(): Sets the signedness of the
857 integer fields described by a given integer field type.
859 extern bt_bool
bt_ctf_field_type_integer_is_signed(
860 struct bt_ctf_field_type
*int_field_type
);
862 /** @cond DOCUMENT */
864 extern int bt_ctf_field_type_integer_get_signed(
865 struct bt_ctf_field_type
*int_field_type
);
870 @brief Sets whether or not the @intfields described by
871 the @intft \p int_field_type are signed.
873 @param[in] int_field_type Integer field type which describes the
874 integer fields of which to set the
876 @param[in] is_signed Signedness of the integer fields
877 described by \p int_field_type; #BT_FALSE means
878 \em unsigned, #BT_TRUE means \em signed.
879 @returns 0 on success, or a negative value on error.
881 @prenotnull{int_field_type}
882 @preisintft{int_field_type}
883 @prehot{int_field_type}
884 @postrefcountsame{int_field_type}
886 @sa bt_ctf_field_type_integer_is_signed(): Returns the signedness of
887 the integer fields described by a given integer field type.
889 extern int bt_ctf_field_type_integer_set_is_signed(
890 struct bt_ctf_field_type
*int_field_type
, bt_bool is_signed
);
892 /* Pre-2.0 CTF writer compatibility */
893 #define bt_ctf_field_type_integer_set_signed bt_ctf_field_type_integer_set_is_signed
896 @brief Returns the preferred display base (radix) of the @intfields
897 described by the @intft \p int_field_type.
899 @param[in] int_field_type Integer field type which describes the
900 integer fields of which to get the
901 preferred display base.
902 @returns Preferred display base of the integer
903 fields described by \p int_field_type,
904 #BT_CTF_INTEGER_BASE_UNSPECIFIED if
906 #BT_CTF_INTEGER_BASE_UNKNOWN on error.
908 @prenotnull{int_field_type}
909 @preisintft{int_field_type}
910 @postrefcountsame{int_field_type}
912 @sa bt_ctf_field_type_integer_set_base(): Sets the preferred display
913 base of the integer fields described by a given integer field
916 extern enum bt_ctf_integer_base
bt_ctf_field_type_integer_get_base(
917 struct bt_ctf_field_type
*int_field_type
);
920 @brief Sets the preferred display base (radix) of the @intfields
921 described by the @intft \p int_field_type to \p base.
923 @param[in] int_field_type Integer field type which describes the
924 integer fields of which to set the
925 preferred display base.
926 @param[in] base Preferred display base of the integer
927 fields described by \p int_field_type.
928 @returns 0 on success, or a negative value on error.
930 @prenotnull{int_field_type}
931 @preisintft{int_field_type}
932 @prehot{int_field_type}
933 @pre \p base is #BT_CTF_INTEGER_BASE_UNSPECIFIED,
934 #BT_CTF_INTEGER_BASE_BINARY, #BT_CTF_INTEGER_BASE_OCTAL,
935 #BT_CTF_INTEGER_BASE_DECIMAL, or #BT_CTF_INTEGER_BASE_HEXADECIMAL.
936 @postrefcountsame{int_field_type}
938 @sa bt_ctf_field_type_integer_get_base(): Returns the preferred display
939 base of the integer fields described by a given
942 extern int bt_ctf_field_type_integer_set_base(
943 struct bt_ctf_field_type
*int_field_type
,
944 enum bt_ctf_integer_base base
);
947 @brief Returns the encoding of the @intfields described by
948 the @intft \p int_field_type.
950 @param[in] int_field_type Integer field type which describes the
951 integer fields of which to get the
953 @returns Encoding of the integer
954 fields described by \p int_field_type,
955 or #BT_CTF_STRING_ENCODING_UNKNOWN on
958 @prenotnull{int_field_type}
959 @preisintft{int_field_type}
960 @postrefcountsame{int_field_type}
962 @sa bt_ctf_field_type_integer_set_encoding(): Sets the encoding
963 of the integer fields described by a given integer field type.
965 extern enum bt_ctf_string_encoding
bt_ctf_field_type_integer_get_encoding(
966 struct bt_ctf_field_type
*int_field_type
);
969 @brief Sets the encoding of the @intfields described by the @intft
970 \p int_field_type to \p encoding.
972 You can use this property, in CTF IR, to create "text" @arrayfts or
973 @seqfts. A text array field type is array field type with an unsigned,
974 8-bit integer field type having an encoding as its element field type.
976 @param[in] int_field_type Integer field type which describes the
977 integer fields of which to set the
979 @param[in] encoding Encoding of the integer
980 fields described by \p int_field_type.
981 @returns 0 on success, or a negative value on error.
983 @prenotnull{int_field_type}
984 @preisintft{int_field_type}
985 @prehot{int_field_type}
986 @pre \p encoding is #BT_CTF_STRING_ENCODING_NONE,
987 #BT_CTF_STRING_ENCODING_ASCII, or
988 #BT_CTF_STRING_ENCODING_UTF8.
989 @postrefcountsame{int_field_type}
991 @sa bt_ctf_field_type_integer_get_encoding(): Returns the encoding of
992 the integer fields described by a given integer field type.
994 extern int bt_ctf_field_type_integer_set_encoding(
995 struct bt_ctf_field_type
*int_field_type
,
996 enum bt_ctf_string_encoding encoding
);
999 @brief Returns the \link ctfirclockclass CTF IR clock class\endlink
1000 mapped to the @intft \p int_field_type.
1002 The mapped clock class, if any, indicates the class of the clock which
1003 an @intfield described by \p int_field_type should sample or update.
1004 This mapped clock class is only indicative.
1006 @param[in] int_field_type Integer field type of which to get the
1008 @returns Mapped clock class of \p int_field_type,
1009 or \c NULL if there's no mapped clock
1012 @prenotnull{int_field_type}
1013 @preisintft{int_field_type}
1014 @postrefcountsame{int_field_type}
1015 @postsuccessrefcountretinc
1017 @sa bt_ctf_field_type_integer_set_mapped_clock_class(): Sets the mapped
1018 clock class of a given integer field type.
1020 extern struct bt_ctf_clock_class
*bt_ctf_field_type_integer_get_mapped_clock_class(
1021 struct bt_ctf_field_type
*int_field_type
);
1024 @brief Sets the \link ctfirclockclass CTF IR clock class\endlink mapped
1025 to the @intft \p int_field_type to \p clock_class.
1027 The mapped clock class, if any, indicates the class of the clock which
1028 an integer field described by \p int_field_type should sample or update.
1029 This mapped clock class is only indicative.
1031 @param[in] int_field_type Integer field type of which to set the
1033 @param[in] clock_class Mapped clock class of \p int_field_type.
1034 @returns 0 on success, or a negative value on error.
1036 @prenotnull{int_field_type}
1037 @prenotnull{clock_class}
1038 @preisintft{int_field_type}
1039 @prehot{int_field_type}
1040 @postrefcountsame{int_field_type}
1041 @postsuccessrefcountinc{clock_class}
1043 @sa bt_ctf_field_type_integer_get_mapped_clock_class(): Returns the mapped
1044 clock class of a given integer field type.
1046 extern int bt_ctf_field_type_integer_set_mapped_clock_class(
1047 struct bt_ctf_field_type
*int_field_type
,
1048 struct bt_ctf_clock_class
*clock_class
);
1053 @defgroup ctfirfloatfieldtype CTF IR floating point number field type
1054 @ingroup ctfirfieldtypes
1055 @brief CTF IR floating point number field type.
1058 #include <babeltrace/ctf-ir/field-types.h>
1061 A CTF IR <strong><em>floating point number field type</em></strong> is
1062 a field type that you can use to create concrete @floatfields.
1064 You can create a floating point number field type
1065 with bt_ctf_field_type_floating_point_create().
1067 A floating point number field type has the following properties:
1072 <th>Value at creation
1077 <td>\b Alignment (bits) of the described floating point
1080 <td>bt_ctf_field_type_get_alignment()
1081 <td>bt_ctf_field_type_set_alignment()
1084 <td><strong>Byte order</strong> of the described floating point
1086 <td>#BT_CTF_BYTE_ORDER_NATIVE
1087 <td>bt_ctf_field_type_get_byte_order()
1088 <td>bt_ctf_field_type_set_byte_order()
1091 <td><strong>Exponent storage size</strong> (bits) of the described
1092 floating point number fields
1094 <td>bt_ctf_field_type_floating_point_get_exponent_digits()
1095 <td>bt_ctf_field_type_floating_point_set_exponent_digits()
1098 <td><strong>Mantissa and sign storage size</strong> (bits) of the
1099 described floating point number fields
1100 <td>24 (23-bit mantissa, 1-bit sign)
1101 <td>bt_ctf_field_type_floating_point_get_mantissa_digits()
1102 <td>bt_ctf_field_type_floating_point_set_mantissa_digits()
1108 @sa \ref ctfirfieldtypesexamples_floatfieldtype "Examples"
1110 @addtogroup ctfirfloatfieldtype
1115 @brief Creates a default @floatft.
1117 @returns Created floating point number field type,
1118 or \c NULL on error.
1120 @postsuccessrefcountret1
1122 extern struct bt_ctf_field_type
*bt_ctf_field_type_floating_point_create(void);
1125 @brief Returns the exponent storage size of the @floatfields
1126 described by the @floatft \p float_field_type.
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 exponent
1132 @returns Exponent 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_exponent_digits(): Sets the
1142 exponent storage size of the floating point number fields
1143 described by a given floating point number field type.
1145 extern int bt_ctf_field_type_floating_point_get_exponent_digits(
1146 struct bt_ctf_field_type
*float_field_type
);
1149 @brief Sets the exponent storage size of the @floatfields described by
1150 the @floatft \p float_field_type to \p exponent_size.
1152 As of Babeltrace \btversion, \p exponent_size can only be 8 or 11.
1154 @param[in] float_field_type Floating point number field type which
1155 describes the floating point number
1156 fields of which to set the exponent
1158 @param[in] exponent_size Exponent storage size of the floating
1159 point number fields described by \p
1161 @returns 0 on success, or a negative value on error.
1163 @prenotnull{float_field_type}
1164 @preisfloatft{float_field_type}
1165 @prehot{float_field_type}
1166 @pre \p exponent_size is 8 or 11.
1167 @postrefcountsame{float_field_type}
1169 @sa bt_ctf_field_type_floating_point_get_exponent_digits(): Returns the
1170 exponent storage size of the floating point number fields
1171 described by a given floating point number field type.
1173 extern int bt_ctf_field_type_floating_point_set_exponent_digits(
1174 struct bt_ctf_field_type
*float_field_type
,
1175 unsigned int exponent_size
);
1178 @brief Returns the mantissa and sign storage size of the @floatfields
1179 described by the @floatft \p float_field_type.
1181 On success, the returned value is the sum of the mantissa \em and
1184 @param[in] float_field_type Floating point number field type which
1185 describes the floating point number
1186 fields of which to get the mantissa and
1188 @returns Mantissa and sign storage size of the
1189 floating point number fields
1190 described by \p float_field_type,
1191 or a negative value on error.
1193 @prenotnull{float_field_type}
1194 @preisfloatft{float_field_type}
1195 @postrefcountsame{float_field_type}
1197 @sa bt_ctf_field_type_floating_point_set_mantissa_digits(): Sets the
1198 mantissa and size storage size of the floating point number
1199 fields described by a given floating point number field type.
1201 extern int bt_ctf_field_type_floating_point_get_mantissa_digits(
1202 struct bt_ctf_field_type
*float_field_type
);
1205 @brief Sets the mantissa and sign storage size of the @floatfields
1206 described by the @floatft \p float_field_type to \p
1209 As of Babeltrace \btversion, \p mantissa_sign_size can only be 24 or 53.
1211 @param[in] float_field_type Floating point number field type which
1212 describes the floating point number
1213 fields of which to set the mantissa and
1215 @param[in] mantissa_sign_size Mantissa and sign storage size of the
1216 floating point number fields described
1217 by \p float_field_type.
1218 @returns 0 on success, or a negative value on error.
1220 @prenotnull{float_field_type}
1221 @preisfloatft{float_field_type}
1222 @prehot{float_field_type}
1223 @pre \p mantissa_sign_size is 24 or 53.
1224 @postrefcountsame{float_field_type}
1226 @sa bt_ctf_field_type_floating_point_get_mantissa_digits(): Returns the
1227 mantissa and sign storage size of the floating point number
1228 fields described by a given floating point number field type.
1230 extern int bt_ctf_field_type_floating_point_set_mantissa_digits(
1231 struct bt_ctf_field_type
*float_field_type
,
1232 unsigned int mantissa_sign_size
);
1237 @defgroup ctfirenumfieldtype CTF IR enumeration field type
1238 @ingroup ctfirfieldtypes
1239 @brief CTF IR enumeration field type.
1242 #include <babeltrace/ctf-ir/field-types.h>
1245 A CTF IR <strong><em>enumeration field type</em></strong> is
1246 a field type that you can use to create concrete @enumfields.
1248 You can create an enumeration field type with
1249 bt_ctf_field_type_enumeration_create(). This function needs a @intft
1250 which represents the storage field type of the created enumeration field
1251 type. In other words, an enumeration field type wraps an integer field
1252 type and adds label-value mappings to it.
1254 An enumeration mapping has:
1256 - A <strong>name</strong>.
1257 - A <strong>range of values</strong> given by a beginning and an ending
1258 value, both included in the range.
1260 You can add a mapping to an enumeration field type with
1261 bt_ctf_field_type_enumeration_add_mapping_signed() or
1262 bt_ctf_field_type_enumeration_add_mapping_unsigned(), depending on the
1263 signedness of the wrapped @intft.
1265 You can find mappings by name or by value with the following find
1268 - bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
1269 mappings with a given name.
1270 - bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value():
1271 Finds the mappings which contain a given unsigned value in their
1273 - bt_ctf_field_type_enumeration_find_mappings_by_signed_value():
1274 Finds the mappings which contain a given signed value in their range.
1276 Those functions return a @enumftiter on the result set of the find
1279 Many mappings can share the same name, and the ranges of a given
1280 enumeration field type are allowed to overlap. For example,
1281 this is a valid set of mappings:
1290 The following set of mappings is also valid:
1299 Here, the range of the second \c APPLE mapping overlaps the range of
1300 the \c CHERRY mapping.
1302 @sa ctfirenumftmappingiter
1306 @addtogroup ctfirenumfieldtype
1311 @brief Creates a default @enumft wrapping the @intft \p int_field_type.
1313 @param[in] int_field_type Integer field type wrapped by the
1314 created enumeration field type.
1315 @returns Created enumeration field type,
1316 or \c NULL on error.
1318 @prenotnull{int_field_type}
1319 @preisintft{int_field_type}
1320 @postsuccessrefcountinc{int_field_type}
1321 @postsuccessrefcountret1
1323 extern struct bt_ctf_field_type
*bt_ctf_field_type_enumeration_create(
1324 struct bt_ctf_field_type
*int_field_type
);
1327 @brief Returns the @intft wrapped by the @enumft \p enum_field_type.
1329 @param[in] enum_field_type Enumeration field type of which to get
1330 the wrapped integer field type.
1331 @returns Integer field type wrapped by
1332 \p enum_field_type, or \c NULL on
1335 @prenotnull{enum_field_type}
1336 @preisenumft{enum_field_type}
1337 @postrefcountsame{enum_field_type}
1338 @postsuccessrefcountretinc
1341 struct bt_ctf_field_type
*bt_ctf_field_type_enumeration_get_container_type(
1342 struct bt_ctf_field_type
*enum_field_type
);
1345 @brief Returns the number of mappings contained in the
1346 @enumft \p enum_field_type.
1348 @param[in] enum_field_type Enumeration field type of which to get
1349 the number of contained mappings.
1350 @returns Number of mappings contained in
1351 \p enum_field_type, or a negative
1354 @prenotnull{enum_field_type}
1355 @preisenumft{enum_field_type}
1356 @postrefcountsame{enum_field_type}
1358 extern int64_t bt_ctf_field_type_enumeration_get_mapping_count(
1359 struct bt_ctf_field_type
*enum_field_type
);
1362 @brief Returns the signed mapping of the @enumft
1363 \p enum_field_type at index \p index.
1365 The @intft wrapped by \p enum_field_type, as returned by
1366 bt_ctf_field_type_enumeration_get_container_type(), must be \b signed
1367 to use this function.
1369 On success, \p enum_field_type remains the sole owner of \p *name.
1371 @param[in] enum_field_type Enumeration field type of which to get
1372 the mapping at index \p index.
1373 @param[in] index Index of the mapping to get from
1375 @param[out] name Returned name of the mapping at index
1377 @param[out] range_begin Returned beginning of the range
1378 (included) of the mapping at index \p
1380 @param[out] range_end Returned end of the range (included) of
1381 the mapping at index \p index.
1382 @returns 0 on success, or a negative value on error.
1384 @prenotnull{enum_field_type}
1386 @prenotnull{range_begin}
1387 @prenotnull{range_end}
1388 @preisenumft{enum_field_type}
1389 @pre The wrapped @intft of \p enum_field_type is signed.
1390 @pre \p index is lesser than the number of mappings contained in the
1391 enumeration field type \p enum_field_type (see
1392 bt_ctf_field_type_enumeration_get_mapping_count()).
1393 @postrefcountsame{enum_field_type}
1395 @sa bt_ctf_field_type_enumeration_get_mapping_unsigned(): Returns the
1396 unsigned mapping contained by a given enumeration field type
1399 extern int bt_ctf_field_type_enumeration_get_mapping_signed(
1400 struct bt_ctf_field_type
*enum_field_type
, uint64_t index
,
1401 const char **name
, int64_t *range_begin
, int64_t *range_end
);
1404 @brief Returns the unsigned mapping of the @enumft
1405 \p enum_field_type at index \p index.
1407 The @intft wrapped by \p enum_field_type, as returned by
1408 bt_ctf_field_type_enumeration_get_container_type(), must be
1409 \b unsigned to use this function.
1411 On success, \p enum_field_type remains the sole owner of \p *name.
1413 @param[in] enum_field_type Enumeration field type of which to get
1414 the mapping at index \p index.
1415 @param[in] index Index of the mapping to get from
1417 @param[out] name Returned name of the mapping at index
1419 @param[out] range_begin Returned beginning of the range
1420 (included) of the mapping at index \p
1422 @param[out] range_end Returned end of the range (included) of
1423 the mapping at index \p index.
1424 @returns 0 on success, or a negative value on error.
1426 @prenotnull{enum_field_type}
1428 @prenotnull{range_begin}
1429 @prenotnull{range_end}
1430 @preisenumft{enum_field_type}
1431 @pre The wrapped @intft of \p enum_field_type is unsigned.
1432 @pre \p index is lesser than the number of mappings contained in the
1433 enumeration field type \p enum_field_type (see
1434 bt_ctf_field_type_enumeration_get_mapping_count()).
1435 @postrefcountsame{enum_field_type}
1437 @sa bt_ctf_field_type_enumeration_get_mapping_signed(): Returns the
1438 signed mapping contained by a given enumeration field type
1441 extern int bt_ctf_field_type_enumeration_get_mapping_unsigned(
1442 struct bt_ctf_field_type
*enum_field_type
, uint64_t index
,
1443 const char **name
, uint64_t *range_begin
,
1444 uint64_t *range_end
);
1447 @brief Finds the mappings of the @enumft \p enum_field_type which
1450 This function returns an iterator on the result set of this find
1451 operation. See \ref ctfirenumftmappingiter for more details.
1453 @param[in] enum_field_type Enumeration field type of which to find
1454 the mappings named \p name.
1455 @param[in] name Name of the mappings to find in
1457 @returns @enumftiter on the set of mappings named
1458 \p name in \p enum_field_type, or
1459 \c NULL if no mappings were found or
1462 @prenotnull{enum_field_type}
1464 @preisenumft{enum_field_type}
1465 @postrefcountsame{enum_field_type}
1466 @postsuccessrefcountret1
1467 @post <strong>On success</strong>, the returned @enumftiter can iterate
1468 on at least one mapping.
1470 @sa bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): Finds
1471 the mappings of a given enumeration field type which contain
1472 a given signed value in their range.
1473 @sa bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): Finds
1474 the mappings of a given enumeration field type which contain
1475 a given unsigned value in their range.
1477 extern struct bt_ctf_field_type_enumeration_mapping_iterator
*
1478 bt_ctf_field_type_enumeration_find_mappings_by_name(
1479 struct bt_ctf_field_type
*enum_field_type
,
1483 @brief Finds the mappings of the @enumft \p enum_field_type which
1484 contain the signed value \p value in their range.
1486 This function returns an iterator on the result set of this find
1487 operation. See \ref ctfirenumftmappingiter for more details.
1489 @param[in] enum_field_type Enumeration field type of which to find
1490 the mappings which contain \p value.
1491 @param[in] value Value to find in the ranges of the
1492 mappings of \p enum_field_type.
1493 @returns @enumftiter on the set of mappings of
1494 \p enum_field_type which contain
1495 \p value in their range, or \c NULL if
1496 no mappings were found or on error.
1498 @prenotnull{enum_field_type}
1499 @preisenumft{enum_field_type}
1500 @postrefcountsame{enum_field_type}
1501 @postsuccessrefcountret1
1502 @post <strong>On success</strong>, the returned @enumftiter can iterate
1503 on at least one mapping.
1505 @sa bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
1506 mappings of a given enumeration field type which have a given
1508 @sa bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): Finds
1509 the mappings of a given enumeration field type which contain
1510 a given unsigned value in their range.
1512 extern struct bt_ctf_field_type_enumeration_mapping_iterator
*
1513 bt_ctf_field_type_enumeration_find_mappings_by_signed_value(
1514 struct bt_ctf_field_type
*enum_field_type
,
1518 @brief Finds the mappings of the @enumft \p enum_field_type which
1519 contain the unsigned value \p value in their range.
1521 This function returns an iterator on the result set of this find
1522 operation. See \ref ctfirenumftmappingiter for more details.
1524 @param[in] enum_field_type Enumeration field type of which to find
1525 the mappings which contain \p value.
1526 @param[in] value Value to find in the ranges of the
1527 mappings of \p enum_field_type.
1528 @returns @enumftiter on the set of mappings of
1529 \p enum_field_type which contain
1530 \p value in their range, or \c NULL
1531 if no mappings were found or
1534 @prenotnull{enum_field_type}
1535 @preisenumft{enum_field_type}
1536 @postrefcountsame{enum_field_type}
1537 @postsuccessrefcountret1
1538 @post <strong>On success</strong>, the returned @enumftiter can iterate
1539 on at least one mapping.
1541 @sa bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
1542 mappings of a given enumeration field type which have a given
1544 @sa bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): Finds
1545 the mappings of a given enumeration field type which contain
1546 a given unsigned value in their range.
1548 extern struct bt_ctf_field_type_enumeration_mapping_iterator
*
1549 bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(
1550 struct bt_ctf_field_type
*enum_field_type
,
1554 @brief Adds a mapping to the @enumft \p enum_field_type which maps the
1555 name \p name to the signed range \p range_begin (included) to
1556 \p range_end (included).
1558 Make \p range_begin and \p range_end the same value to add a mapping
1561 The @intft wrapped by \p enum_field_type, as returned by
1562 bt_ctf_field_type_enumeration_get_container_type(), must be
1563 \b signed to use this function.
1565 A mapping in \p enum_field_type can exist with the name \p name.
1567 @param[in] enum_field_type Enumeration field type to which to add
1569 @param[in] name Name of the mapping to add (copied
1571 @param[in] range_begin Beginning of the range of the mapping
1573 @param[in] range_end End of the range of the mapping
1575 @returns 0 on success, or a negative value on error.
1577 @prenotnull{enum_field_type}
1579 @prehot{enum_field_type}
1580 @preisenumft{enum_field_type}
1581 @pre The wrapped @intft of \p enum_field_type is signed.
1582 @pre \p range_end is greater than or equal to \p range_begin.
1583 @postrefcountsame{enum_field_type}
1585 @sa bt_ctf_field_type_enumeration_add_mapping_unsigned(): Adds an
1586 unsigned mapping to a given enumeration field type.
1588 extern int bt_ctf_field_type_enumeration_add_mapping_signed(
1589 struct bt_ctf_field_type
*enum_field_type
, const char *name
,
1590 int64_t range_begin
, int64_t range_end
);
1592 /* Pre-2.0 CTF writer compatibility */
1593 #define bt_ctf_field_type_enumeration_add_mapping bt_ctf_field_type_enumeration_add_mapping_signed
1596 @brief Adds a mapping to the @enumft \p enum_field_type which maps
1597 the name \p name to the unsigned
1598 range \p range_begin (included) to \p range_end (included).
1600 Make \p range_begin and \p range_end the same value to add a mapping
1603 The @intft wrapped by \p enum_field_type, as returned by
1604 bt_ctf_field_type_enumeration_get_container_type(), must be
1605 \b unsigned to use this function.
1607 A mapping in \p enum_field_type can exist with the name \p name.
1609 @param[in] enum_field_type Enumeration field type to which to add
1611 @param[in] name Name of the mapping to add (copied
1613 @param[in] range_begin Beginning of the range of the mapping
1615 @param[in] range_end End of the range of the mapping
1617 @returns 0 on success, or a negative value on error.
1619 @prenotnull{enum_field_type}
1621 @prehot{enum_field_type}
1622 @preisenumft{enum_field_type}
1623 @pre The wrapped @intft of \p enum_field_type is unsigned.
1624 @pre \p range_end is greater than or equal to \p range_begin.
1625 @postrefcountsame{enum_field_type}
1627 @sa bt_ctf_field_type_enumeration_add_mapping_signed(): Adds a signed
1628 mapping to a given enumeration field type.
1630 extern int bt_ctf_field_type_enumeration_add_mapping_unsigned(
1631 struct bt_ctf_field_type
*enum_field_type
, const char *name
,
1632 uint64_t range_begin
, uint64_t range_end
);
1637 @defgroup ctfirenumftmappingiter CTF IR enumeration field type mapping iterator
1638 @ingroup ctfirenumfieldtype
1639 @brief CTF IR enumeration field type mapping iterator.
1642 #include <babeltrace/ctf-ir/field-types.h>
1645 A CTF IR <strong><em>enumeration field type mapping
1646 iterator</em></strong> is an iterator on @enumft mappings.
1648 You can get an enumeration mapping iterator from one of the following
1651 - Find operations of an @enumft object:
1652 - bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the
1653 mappings with a given name.
1654 - bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value():
1655 Finds the mappings which contain a given unsigned value in their
1657 - bt_ctf_field_type_enumeration_find_mappings_by_signed_value():
1658 Finds the mappings which contain a given signed value in their range.
1659 - bt_ctf_field_enumeration_get_mappings(): Finds the mappings in the
1660 @enumft of an @enumfield containing its current integral value in
1663 Those functions guarantee that the returned iterator can iterate on
1664 at least one mapping. Otherwise, they return \c NULL.
1666 You can get the name and the range of a mapping iterator's current
1668 bt_ctf_field_type_enumeration_mapping_iterator_get_signed()
1670 bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(),
1671 depending on the signedness of the @intft wrapped by the
1672 @enumft. If you only need the name of the current mapping, you can
1673 use any of the two functions and set the \p range_begin and \p range_end
1674 parameters to \c NULL.
1676 You can advance an enumeration field type mapping iterator to the next
1678 bt_ctf_field_type_enumeration_mapping_iterator_next(). This
1679 function returns a negative value when you reach the end of the
1682 As with any Babeltrace object, CTF IR enumeration field type mapping
1683 iterator objects have <a
1684 href="https://en.wikipedia.org/wiki/Reference_counting">reference
1685 counts</a>. See \ref refs to learn more about the reference counting
1686 management of Babeltrace objects.
1688 @sa ctfirenumfieldtype
1690 @addtogroup ctfirenumftmappingiter
1695 @struct bt_ctf_field_type_enumeration_mapping_iterator
1696 @brief A CTF IR enumeration field type mapping iterator.
1697 @sa ctfirenumftmappingiter
1701 @brief Returns the name and the range of the current (signed) mapping
1702 of the @enumftiter \p iter.
1704 If one of \p range_begin or \p range_end is not \c NULL, the @intft
1705 wrapped by the @enumft from which \p iter was obtained, as returned by
1706 bt_ctf_field_type_enumeration_get_container_type(), must be
1707 \b signed to use this function. Otherwise, if you only need to get the
1708 name of the current mapping, set \p range_begin and \p range_end to
1711 On success, if \p name is not \c NULL, \p *name remains valid as long
1712 as \p iter exists and
1713 bt_ctf_field_type_enumeration_mapping_iterator_next() is
1714 \em not called on \p iter.
1716 @param[in] iter Enumeration field type mapping iterator
1717 of which to get the range of the current
1719 @param[out] name Returned name of the current mapping of
1720 \p iter (can be \c NULL to ignore).
1721 @param[out] range_begin Returned beginning of the range
1722 (included) of the current mapping of
1723 \p iter (can be \c NULL to ignore).
1724 @param[out] range_end Returned end of the range
1725 (included) of the current mapping of
1726 \p iter (can be \c NULL to ignore).
1727 @returns 0 on success, or a negative value on error.
1730 @postrefcountsame{iter}
1732 @sa bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned():
1733 Returns the name and the unsigned range of the current mapping
1734 of a given enumeration field type mapping iterator.
1736 extern int bt_ctf_field_type_enumeration_mapping_iterator_get_signed(
1737 struct bt_ctf_field_type_enumeration_mapping_iterator
*iter
,
1738 const char **name
, int64_t *range_begin
, int64_t *range_end
);
1741 @brief Returns the name and the range of the current (unsigned) mapping
1742 of the @enumftiter \p iter.
1744 If one of \p range_begin or \p range_end is not \c NULL, the @intft
1745 wrapped by the @enumft from which \p iter was obtained, as returned by
1746 bt_ctf_field_type_enumeration_get_container_type(), must be
1747 \b unsigned to use this function. Otherwise, if you only need to get the
1748 name of the current mapping, set \p range_begin and \p range_end to
1751 On success, if \p name is not \c NULL, \p *name remains valid as long
1752 as \p iter exists and
1753 bt_ctf_field_type_enumeration_mapping_iterator_next() is
1754 \em not called on \p iter.
1756 @param[in] iter Enumeration field type mapping iterator
1757 of which to get the range of the current
1759 @param[out] name Returned name of the current mapping of
1760 \p iter (can be \c NULL to ignore).
1761 @param[out] range_begin Returned beginning of the range
1762 (included) of the current mapping of
1763 \p iter (can be \c NULL to ignore).
1764 @param[out] range_end Returned end of the range
1765 (included) of the current mapping of
1766 \p iter (can be \c NULL to ignore).
1767 @returns 0 on success, or a negative value on error.
1770 @postrefcountsame{iter}
1773 bt_ctf_field_type_enumeration_mapping_iterator_get_signed():
1774 Returns the name and the signed range of the current mapping of
1775 a given enumeration field type mapping iterator.
1777 extern int bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(
1778 struct bt_ctf_field_type_enumeration_mapping_iterator
*iter
,
1779 const char **name
, uint64_t *range_begin
, uint64_t *range_end
);
1782 @brief Advances the @enumftiter \p iter to the next mapping.
1784 @param[in] iter Enumeration field type mapping iterator to
1786 @returns 0 on success, or a negative value on error or
1787 when you reach the end of the set.
1790 @postrefcountsame{iter}
1792 extern int bt_ctf_field_type_enumeration_mapping_iterator_next(
1793 struct bt_ctf_field_type_enumeration_mapping_iterator
*iter
);
1798 @defgroup ctfirstringfieldtype CTF IR string field type
1799 @ingroup ctfirfieldtypes
1800 @brief CTF IR string field type.
1803 #include <babeltrace/ctf-ir/field-types.h>
1806 A CTF IR <strong><em>string field type</em></strong> is a field type that
1807 you can use to create concrete @stringfields.
1809 You can create a string field type
1810 with bt_ctf_field_type_string_create().
1812 A string field type has only one property: the \b encoding of its
1813 described @stringfields. By default, the encoding of the string fields
1814 described by a string field type is #BT_CTF_STRING_ENCODING_UTF8. You
1815 can set the encoding of the string fields described by a string field
1816 type with bt_ctf_field_type_string_set_encoding().
1818 @sa ctfirstringfield
1821 @addtogroup ctfirstringfieldtype
1826 @brief Creates a default @stringft.
1828 @returns Created string field type, or \c NULL on error.
1830 @postsuccessrefcountret1
1832 extern struct bt_ctf_field_type
*bt_ctf_field_type_string_create(void);
1835 @brief Returns the encoding of the @stringfields described by
1836 the @stringft \p string_field_type.
1838 @param[in] string_field_type String field type which describes the
1839 string fields of which to get the
1841 @returns Encoding of the string
1842 fields described by \p string_field_type,
1843 or #BT_CTF_STRING_ENCODING_UNKNOWN on
1846 @prenotnull{string_field_type}
1847 @preisstringft{string_field_type}
1848 @postrefcountsame{string_field_type}
1850 @sa bt_ctf_field_type_string_set_encoding(): Sets the encoding
1851 of the string fields described by a given string field type.
1853 extern enum bt_ctf_string_encoding
bt_ctf_field_type_string_get_encoding(
1854 struct bt_ctf_field_type
*string_field_type
);
1857 @brief Sets the encoding of the @stringfields described by the
1858 @stringft \p string_field_type to \p encoding.
1860 @param[in] string_field_type String field type which describes the
1861 string fields of which to set the
1863 @param[in] encoding Encoding of the string fields described
1864 by \p string_field_type.
1865 @returns 0 on success, or a negative value on error.
1867 @prenotnull{string_field_type}
1868 @preisstringft{string_field_type}
1869 @prehot{string_field_type}
1870 @pre \p encoding is #BT_CTF_STRING_ENCODING_ASCII or
1871 #BT_CTF_STRING_ENCODING_UTF8.
1872 @postrefcountsame{string_field_type}
1874 @sa bt_ctf_field_type_string_get_encoding(): Returns the encoding of
1875 the string fields described by a given string field type.
1877 extern int bt_ctf_field_type_string_set_encoding(
1878 struct bt_ctf_field_type
*string_field_type
,
1879 enum bt_ctf_string_encoding encoding
);
1884 @defgroup ctfirstructfieldtype CTF IR structure field type
1885 @ingroup ctfirfieldtypes
1886 @brief CTF IR structure field type.
1889 #include <babeltrace/ctf-ir/field-types.h>
1892 A CTF IR <strong><em>structure field type</em></strong> is
1893 a field type that you can use to create concrete @structfields.
1895 You can create a structure field type
1896 with bt_ctf_field_type_structure_create(). This function creates
1897 an empty structure field type, with no fields.
1899 You can add a field to a structure field type with
1900 bt_ctf_field_type_structure_add_field(). Two fields in a structure
1901 field type cannot have the same name.
1903 You can set the \em minimum alignment of the structure fields described
1904 by a structure field type with the common
1905 bt_ctf_field_type_set_alignment() function. The \em effective alignment
1906 of the structure fields described by a structure field type, as per
1907 <a href="http://diamon.org/ctf/">CTF</a>, is the \em maximum value amongst
1908 the effective alignments of all its fields. Note that the effective
1909 alignment of @varfields is always 1.
1911 You can set the byte order of <em>all the contained fields</em>,
1912 recursively, of a structure field type with the common
1913 bt_ctf_field_type_set_byte_order() function.
1915 @sa ctfirstructfield
1918 @addtogroup ctfirstructfieldtype
1923 @brief Creates a default, empty @structft.
1925 @returns Created structure field type,
1926 or \c NULL on error.
1928 @postsuccessrefcountret1
1930 extern struct bt_ctf_field_type
*bt_ctf_field_type_structure_create(void);
1933 @brief Returns the number of fields contained in the
1934 @structft \p struct_field_type.
1936 @param[in] struct_field_type Structure field type of which to get
1937 the number of contained fields.
1938 @returns Number of fields contained in
1939 \p struct_field_type, or a negative
1942 @prenotnull{struct_field_type}
1943 @preisstructft{struct_field_type}
1944 @postrefcountsame{struct_field_type}
1946 extern int64_t bt_ctf_field_type_structure_get_field_count(
1947 struct bt_ctf_field_type
*struct_field_type
);
1950 @brief Returns the field of the @structft \p struct_field_type
1953 On success, the field's type is placed in \p *field_type if
1954 \p field_type is not \c NULL. The field's name is placed in
1955 \p *field_name if \p field_name is not \c NULL.
1956 \p struct_field_type remains the sole owner of \p *field_name.
1958 @param[in] struct_field_type Structure field type of which to get
1959 the field at index \p index.
1960 @param[out] field_name Returned name of the field at index
1961 \p index (can be \c NULL).
1962 @param[out] field_type Returned field type of the field
1963 at index \p index (can be \c NULL).
1964 @param[in] index Index of the field to get from
1965 \p struct_field_type.
1966 @returns 0 on success, or a negative value on error.
1968 @prenotnull{struct_field_type}
1969 @preisstructft{struct_field_type}
1970 @pre \p index is lesser than the number of fields contained in the
1971 structure field type \p struct_field_type (see
1972 bt_ctf_field_type_structure_get_field_count()).
1973 @postrefcountsame{struct_field_type}
1974 @post <strong>On success</strong>, the returned field's type is placed
1975 in \p *field_type and its reference count is incremented.
1977 @sa bt_ctf_field_type_structure_get_field_type_by_name(): Finds a
1978 structure field type's field by name.
1980 extern int bt_ctf_field_type_structure_get_field_by_index(
1981 struct bt_ctf_field_type
*struct_field_type
,
1982 const char **field_name
, struct bt_ctf_field_type
**field_type
,
1985 /* Pre-2.0 CTF writer compatibility */
1986 #define bt_ctf_field_type_structure_get_field bt_ctf_field_type_structure_get_field_by_index
1989 @brief Returns the type of the field named \p field_name found in
1990 the @structft \p struct_field_type.
1992 @param[in] struct_field_type Structure field type of which to get
1994 @param[in] field_name Name of the field to find.
1995 @returns Type of the field named \p field_name in
1996 \p struct_field_type, or
1999 @prenotnull{struct_field_type}
2000 @prenotnull{field_name}
2001 @preisstructft{struct_field_type}
2002 @postrefcountsame{struct_field_type}
2003 @postsuccessrefcountretinc
2005 @sa bt_ctf_field_type_structure_get_field_by_index(): Finds a
2006 structure field type's field by index.
2009 struct bt_ctf_field_type
*bt_ctf_field_type_structure_get_field_type_by_name(
2010 struct bt_ctf_field_type
*struct_field_type
,
2011 const char *field_name
);
2014 @brief Adds a field named \p field_name with the @ft
2015 \p field_type to the @structft \p struct_field_type.
2017 On success, \p field_type becomes the child of \p struct_field_type.
2019 This function adds the new field after the current last field of
2020 \p struct_field_type (append mode).
2022 You \em cannot add a field named \p field_name if there's already a
2023 field named \p field_name in \p struct_field_type.
2025 @param[in] struct_field_type Structure field type to which to add
2027 @param[in] field_type Field type of the field to add to
2028 \p struct_field_type.
2029 @param[in] field_name Name of the field to add to
2030 \p struct_field_type
2031 (copied on success).
2032 @returns 0 on success, or a negative value on error.
2034 @prenotnull{struct_field_type}
2035 @prenotnull{field_type}
2036 @prenotnull{field_name}
2037 @preisstructft{struct_field_type}
2038 @pre \p field_type is not and does not contain \p struct_field_type,
2039 recursively, as a field's type.
2040 @prehot{struct_field_type}
2041 @postrefcountsame{struct_field_type}
2042 @postsuccessrefcountinc{field_type}
2044 extern int bt_ctf_field_type_structure_add_field(
2045 struct bt_ctf_field_type
*struct_field_type
,
2046 struct bt_ctf_field_type
*field_type
,
2047 const char *field_name
);
2052 @defgroup ctfirarrayfieldtype CTF IR array field type
2053 @ingroup ctfirfieldtypes
2054 @brief CTF IR array field type.
2057 #include <babeltrace/ctf-ir/field-types.h>
2060 A CTF IR <strong><em>array field type</em></strong> is a field type that
2061 you can use to create concrete @arrayfields.
2063 You can create an array field type
2064 with bt_ctf_field_type_array_create(). This function needs
2065 the @ft of the fields contained by the array fields described by the
2066 array field type to create.
2071 @addtogroup ctfirarrayfieldtype
2076 @brief Creates a default @arrayft with
2077 \p element_field_type as the field type of the fields contained
2078 in its described @arrayfields of length \p length.
2080 @param[in] element_field_type Field type of the fields contained in
2081 the array fields described by the
2082 created array field type.
2083 @param[in] length Length of the array fields described by
2084 the created array field type.
2085 @returns Created array field type, or
2088 @prenotnull{element_field_type}
2089 @postsuccessrefcountinc{element_field_type}
2090 @postsuccessrefcountret1
2092 extern struct bt_ctf_field_type
*bt_ctf_field_type_array_create(
2093 struct bt_ctf_field_type
*element_field_type
,
2094 unsigned int length
);
2097 @brief Returns the @ft of the @fields contained in
2098 the @arrayfields described by the @arrayft \p array_field_type.
2100 @param[in] array_field_type Array field type of which to get
2101 the type of the fields contained in its
2102 described array fields.
2103 @returns Type of the fields contained in the
2104 array fields described by
2105 \p array_field_type, or \c NULL
2108 @prenotnull{array_field_type}
2109 @preisarrayft{array_field_type}
2110 @postrefcountsame{array_field_type}
2111 @postsuccessrefcountretinc
2113 extern struct bt_ctf_field_type
*bt_ctf_field_type_array_get_element_type(
2114 struct bt_ctf_field_type
*array_field_type
);
2117 @brief Returns the number of @fields contained in the
2118 @arrayfields described by the @arrayft \p array_field_type.
2120 @param[in] array_field_type Array field type of which to get
2121 the number of fields contained in its
2122 described array fields.
2123 @returns Number of fields contained in the
2124 array fields described by
2125 \p array_field_type, or a negative value
2128 @prenotnull{array_field_type}
2129 @preisarrayft{array_field_type}
2130 @postrefcountsame{array_field_type}
2132 extern int64_t bt_ctf_field_type_array_get_length(
2133 struct bt_ctf_field_type
*array_field_type
);
2138 @defgroup ctfirseqfieldtype CTF IR sequence field type
2139 @ingroup ctfirfieldtypes
2140 @brief CTF IR sequence field type.
2143 #include <babeltrace/ctf-ir/field-types.h>
2146 A CTF IR <strong><em>sequence field type</em></strong> is
2147 a field type that you can use to create concrete @seqfields.
2149 You can create a sequence field type with
2150 bt_ctf_field_type_sequence_create(). This function needs the @ft
2151 of the fields contained by the sequence fields described by the created
2152 sequence field type. This function also needs the length name of the
2153 sequence field type to create. The length name is used to automatically
2154 resolve the length's field type. See \ref ctfirfieldtypes to learn more
2155 about the automatic resolving.
2160 @addtogroup ctfirseqfieldtype
2165 @brief Creates a default @seqft with \p element_field_type as the
2166 @ft of the @fields contained in its described @seqfields
2167 with the length name \p length_name.
2169 \p length_name can be an absolute or relative reference. See
2170 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2172 @param[in] element_field_type Field type of the fields contained in
2173 the sequence fields described by the
2174 created sequence field type.
2175 @param[in] length_name Length name (copied on success).
2176 @returns Created array field type, or
2179 @prenotnull{element_field_type}
2180 @prenotnull{length_name}
2181 @postsuccessrefcountinc{element_field_type}
2182 @postsuccessrefcountret1
2184 extern struct bt_ctf_field_type
*bt_ctf_field_type_sequence_create(
2185 struct bt_ctf_field_type
*element_field_type
,
2186 const char *length_name
);
2189 @brief Returns the @ft of the @fields contained in the @seqft
2190 described by the @seqft \p sequence_field_type.
2192 @param[in] sequence_field_type Sequence field type of which to get
2193 the type of the fields contained in its
2194 described sequence fields.
2195 @returns Type of the fields contained in the
2196 sequence fields described by
2197 \p sequence_field_type, or \c NULL
2200 @prenotnull{sequence_field_type}
2201 @preisseqft{sequence_field_type}
2202 @postrefcountsame{sequence_field_type}
2203 @postsuccessrefcountretinc
2205 extern struct bt_ctf_field_type
*bt_ctf_field_type_sequence_get_element_type(
2206 struct bt_ctf_field_type
*sequence_field_type
);
2209 @brief Returns the length name of the @seqft \p sequence_field_type.
2211 On success, \p sequence_field_type remains the sole owner of
2212 the returned string.
2214 @param[in] sequence_field_type Sequence field type of which to get the
2216 @returns Length name of \p sequence_field_type,
2217 or \c NULL on error.
2219 @prenotnull{sequence_field_type}
2220 @preisseqft{sequence_field_type}
2222 @sa bt_ctf_field_type_sequence_get_length_field_path(): Returns the
2223 length's CTF IR field path of a given sequence field type.
2225 extern const char *bt_ctf_field_type_sequence_get_length_field_name(
2226 struct bt_ctf_field_type
*sequence_field_type
);
2229 @brief Returns the length's CTF IR field path of the @seqft
2230 \p sequence_field_type.
2232 The length's field path of a sequence field type is set when automatic
2233 resolving is performed (see \ref ctfirfieldtypes).
2235 @param[in] sequence_field_type Sequence field type of which to get the
2236 length's field path.
2237 @returns Length's field path of
2238 \p sequence_field_type, or
2239 \c NULL if the length's field path is
2240 not set yet is not set or on error.
2242 @prenotnull{sequence_field_type}
2243 @preisseqft{sequence_field_type}
2244 @postsuccessrefcountretinc
2246 @sa bt_ctf_field_type_sequence_get_length_field_name(): Returns the
2247 length's name of a given sequence field type.
2249 extern struct bt_ctf_field_path
*bt_ctf_field_type_sequence_get_length_field_path(
2250 struct bt_ctf_field_type
*sequence_field_type
);
2255 @defgroup ctfirvarfieldtype CTF IR variant field type
2256 @ingroup ctfirfieldtypes
2257 @brief CTF IR variant field type.
2260 #include <babeltrace/ctf-ir/field-types.h>
2263 A CTF IR <strong><em>variant field type</em></strong> is
2264 a field type that you can use to create concrete @varfields.
2266 You can create a variant field type with
2267 bt_ctf_field_type_variant_create(). This function expects you to pass
2268 both the tag's @enumft and the tag name of the variant field type to
2269 create. The tag's field type is optional, as the Babeltrace system can
2270 automatically resolve it using the tag name. You can leave the tag name
2271 to \c NULL initially, and set it later with
2272 bt_ctf_field_type_variant_set_tag_name(). The tag name must be set when
2273 the variant field type is frozen. See \ref ctfirfieldtypes to learn more
2274 about the automatic resolving and the conditions under which a field
2277 You can add a field to a variant field type with
2278 bt_ctf_field_type_variant_add_field(). All the field names of a
2279 variant field type \em must exist as mapping names in its tag's @enumft.
2281 The effective alignment of the @varfields described by a
2282 variant field type is always 1, but the individual fields of a
2283 @varfield can have custom alignments.
2285 You can set the byte order of <em>all the contained fields</em>,
2286 recursively, of a variant field type with the common
2287 bt_ctf_field_type_set_byte_order() function.
2292 @addtogroup ctfirvarfieldtype
2297 @brief Creates a default, empty @varft with the tag's @enumft
2298 \p tag_field_type and the tag name \p tag_name.
2300 \p tag_field_type can be \c NULL; the tag's field type can be
2301 automatically resolved from the variant field type's tag name (see
2302 \ref ctfirfieldtypes). If \p tag_name is \c NULL, it \em must be set
2303 with bt_ctf_field_type_variant_set_tag_name() \em before the variant
2304 field type is frozen.
2306 \p tag_name can be an absolute or relative reference. See
2307 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2309 @param[in] tag_field_type Tag's enumeration field type
2311 @param[in] tag_name Tag name (copied on success,
2313 @returns Created variant field type, or
2316 @pre \p tag_field_type is an enumeration field type or \c NULL.
2317 @post <strong>On success, if \p tag_field_type is not \c NULL</strong>,
2318 its reference count is incremented.
2319 @postsuccessrefcountret1
2321 extern struct bt_ctf_field_type
*bt_ctf_field_type_variant_create(
2322 struct bt_ctf_field_type
*tag_field_type
,
2323 const char *tag_name
);
2326 @brief Returns the tag's @enumft of the @varft \p variant_field_type.
2328 @param[in] variant_field_type Variant field type of which to get
2329 the tag's enumeration field type.
2330 @returns Tag's enumeration field type of
2331 \p variant_field_type, or \c NULL if the
2332 tag's field type is not set or on
2335 @prenotnull{variant_field_type}
2336 @preisvarft{variant_field_type}
2337 @postrefcountsame{variant_field_type}
2338 @postsuccessrefcountretinc
2340 extern struct bt_ctf_field_type
*bt_ctf_field_type_variant_get_tag_type(
2341 struct bt_ctf_field_type
*variant_field_type
);
2344 @brief Returns the tag name of the @varft \p variant_field_type.
2346 On success, \p variant_field_type remains the sole owner of
2347 the returned string.
2349 @param[in] variant_field_type Variant field type of which to get the
2351 @returns Tag name of \p variant_field_type, or
2352 \c NULL if the tag name is not set or
2355 @prenotnull{variant_field_type}
2356 @preisvarft{variant_field_type}
2358 @sa bt_ctf_field_type_variant_set_tag_name(): Sets the tag name of
2359 a given variant field type.
2360 @sa bt_ctf_field_type_variant_get_tag_field_path(): Returns the tag's
2361 CTF IR field path of a given variant field type.
2363 extern const char *bt_ctf_field_type_variant_get_tag_name(
2364 struct bt_ctf_field_type
*variant_field_type
);
2367 @brief Sets the tag name of the @varft \p variant_field_type.
2369 \p tag_name can be an absolute or relative reference. See
2370 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2372 @param[in] variant_field_type Variant field type of which to set
2374 @param[in] tag_name Tag name of \p variant_field_type
2375 (copied on success).
2376 @returns 0 on success, or a negative value on error.
2378 @prenotnull{variant_field_type}
2380 @prehot{variant_field_type}
2381 @postrefcountsame{variant_field_type}
2383 @sa bt_ctf_field_type_variant_get_tag_name(): Returns the tag name of
2384 a given variant field type.
2386 extern int bt_ctf_field_type_variant_set_tag_name(
2387 struct bt_ctf_field_type
*variant_field_type
,
2388 const char *tag_name
);
2391 @brief Returns the tag's CTF IR field path of the @varft
2392 \p variant_field_type.
2394 The tag's field path of a variant field type is set when automatic
2395 resolving is performed (see \ref ctfirfieldtypes).
2397 @param[in] variant_field_type Variant field type of which to get the
2399 @returns Tag's field path of
2400 \p variant_field_type, or
2401 \c NULL if the tag's field path is not
2402 set yet is not set or on error.
2404 @prenotnull{variant_field_type}
2405 @preisvarft{variant_field_type}
2406 @postsuccessrefcountretinc
2408 @sa bt_ctf_field_type_variant_get_tag_name(): Returns the tag's
2409 name of a given variant field type.
2411 extern struct bt_ctf_field_path
*bt_ctf_field_type_variant_get_tag_field_path(
2412 struct bt_ctf_field_type
*variant_field_type
);
2415 @brief Returns the number of fields (choices) contained in the @varft
2416 \p variant_field_type.
2418 @param[in] variant_field_type Variant field type of which to get
2419 the number of contained fields.
2420 @returns Number of fields contained in
2421 \p variant_field_type, or a negative
2424 @prenotnull{variant_field_type}
2425 @preisvarft{variant_field_type}
2426 @postrefcountsame{variant_field_type}
2428 extern int64_t bt_ctf_field_type_variant_get_field_count(
2429 struct bt_ctf_field_type
*variant_field_type
);
2432 @brief Returns the field (choice) of the @varft \p variant_field_type
2435 On success, the field's type is placed in \p *field_type if
2436 \p field_type is not \c NULL. The field's name is placed in
2437 \p *field_name if \p field_name is not \c NULL.
2438 \p variant_field_type remains the sole owner of \p *field_name.
2440 @param[in] variant_field_type Variant field type of which to get
2441 the field at index \p index.
2442 @param[out] field_name Returned name of the field at index
2443 \p index (can be \c NULL).
2444 @param[out] field_type Returned field type of the field
2445 at index \p index (can be \c NULL).
2446 @param[in] index Index of the field to get from
2447 \p variant_field_type.
2448 @returns 0 on success, or a negative value on error.
2450 @prenotnull{variant_field_type}
2451 @preisvarft{variant_field_type}
2452 @pre \p index is lesser than the number of fields contained in the
2453 variant field type \p variant_field_type (see
2454 bt_ctf_field_type_variant_get_field_count()).
2455 @postrefcountsame{variant_field_type}
2456 @post <strong>On success</strong>, the returned field's type is placed
2457 in \p *field_type and its reference count is incremented.
2459 @sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant
2460 field type's field by name.
2461 @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant
2462 field type's field by current tag value.
2464 extern int bt_ctf_field_type_variant_get_field_by_index(
2465 struct bt_ctf_field_type
*variant_field_type
,
2466 const char **field_name
,
2467 struct bt_ctf_field_type
**field_type
, uint64_t index
);
2469 /* Pre-2.0 CTF writer compatibility */
2470 #define bt_ctf_field_type_variant_get_field bt_ctf_field_type_variant_get_field_by_index
2473 @brief Returns the type of the field (choice) named \p field_name
2474 found in the @varft \p variant_field_type.
2476 @param[in] variant_field_type Variant field type of which to get
2478 @param[in] field_name Name of the field to find.
2479 @returns Type of the field named \p field_name in
2480 \p variant_field_type, or
2483 @prenotnull{variant_field_type}
2484 @prenotnull{field_name}
2485 @preisvarft{variant_field_type}
2486 @postrefcountsame{variant_field_type}
2487 @postsuccessrefcountretinc
2489 @sa bt_ctf_field_type_variant_get_field_by_index(): Finds a variant field type's
2491 @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant
2492 field type's field by current tag value.
2495 struct bt_ctf_field_type
*bt_ctf_field_type_variant_get_field_type_by_name(
2496 struct bt_ctf_field_type
*variant_field_type
,
2497 const char *field_name
);
2500 @brief Returns the type of the field (choice) selected by the value of
2501 the @enumfield \p tag_field in the @varft \p variant_field_type.
2503 \p tag_field is the current tag value.
2505 The field type of \p tag_field, as returned by bt_ctf_field_get_type(),
2506 \em must be equivalent to the field type returned by
2507 bt_ctf_field_type_variant_get_tag_type() for \p variant_field_type.
2509 @param[in] variant_field_type Variant field type of which to get
2511 @param[in] tag_field Current tag value (variant field type's
2513 @returns Type of the field selected by
2514 \p tag_field in \p variant_field_type,
2515 or \c NULL on error.
2517 @prenotnull{variant_field_type}
2518 @prenotnull{tag_field}
2519 @preisvarft{variant_field_type}
2520 @preisenumfield{tag_field}
2521 @postrefcountsame{variant_field_type}
2522 @postrefcountsame{tag_field}
2523 @postsuccessrefcountretinc
2525 @sa bt_ctf_field_type_variant_get_field_by_index(): Finds a variant field type's
2527 @sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant
2528 field type's field by name.
2531 struct bt_ctf_field_type
*bt_ctf_field_type_variant_get_field_type_from_tag(
2532 struct bt_ctf_field_type
*variant_field_type
,
2533 struct bt_ctf_field
*tag_field
);
2536 @brief Adds a field (a choice) named \p field_name with the @ft
2537 \p field_type to the @varft \p variant_field_type.
2539 On success, \p field_type becomes the child of \p variant_field_type.
2541 You \em cannot add a field named \p field_name if there's already a
2542 field named \p field_name in \p variant_field_type.
2544 \p field_name \em must name an existing mapping in the tag's
2545 enumeration field type of \p variant_field_type.
2547 @param[in] variant_field_type Variant field type to which to add
2549 @param[in] field_type Field type of the field to add to
2550 \p variant_field_type.
2551 @param[in] field_name Name of the field to add to
2552 \p variant_field_type
2553 (copied on success).
2554 @returns 0 on success, or a negative value on error.
2556 @prenotnull{variant_field_type}
2557 @prenotnull{field_type}
2558 @prenotnull{field_name}
2559 @preisvarft{variant_field_type}
2560 @pre \p field_type is not and does not contain \p variant_field_type,
2561 recursively, as a field's type.
2562 @prehot{variant_field_type}
2563 @postrefcountsame{variant_field_type}
2564 @postsuccessrefcountinc{field_type}
2566 extern int bt_ctf_field_type_variant_add_field(
2567 struct bt_ctf_field_type
*variant_field_type
,
2568 struct bt_ctf_field_type
*field_type
,
2569 const char *field_name
);
2577 #endif /* BABELTRACE_CTF_IR_FIELD_TYPES_H */