2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_TRACE_IR_FIELD_CLASS_H
8 #define BABELTRACE2_TRACE_IR_FIELD_CLASS_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
19 #include <babeltrace2/types.h>
26 @defgroup api-tir-fc Field classes
30 Classes of \bt_p_field.
32 <strong><em>Field classes</em></strong> are the classes of \bt_p_field:
34 @image html field-class-zoom.png
36 Field classes are \ref api-tir "trace IR" metadata objects.
38 There are many types of field classes. They can be divided into two main
44 Classes of fields which contain a simple value.
46 The scalar field classes are:
48 - \ref api-tir-fc-bool "Boolean"
49 - \ref api-tir-fc-ba "Bit array"
50 - \ref api-tir-fc-int "Integer" (unsigned and signed)
51 - \ref api-tir-fc-enum "Enumeration" (unsigned and signed)
52 - \ref api-tir-fc-real "Real" (single-precision and double-precision)
53 - \ref api-tir-fc-string "String"
58 Classes of fields which contain other fields.
60 The container field classes are:
62 - \ref api-tir-fc-array "Array" (static and dynamic)
63 - \ref api-tir-fc-struct "Structure"
64 - \ref api-tir-fc-opt "Option"
65 - \ref api-tir-fc-var "Variant"
69 @image html fc-to-field.png "Fields (green) are instances of field classes (orange)."
71 Some field classes conceptually inherit other field classes, eventually
72 making an inheritance hierarchy. For example, a \bt_sarray_fc
73 \em is an array field class. Therefore, a static array field class has
74 any property that an array field class has.
76 The complete field class inheritance hierarchy is:
78 @image html all-field-classes.png
80 In the illustration above:
82 - You can create any field class with a dark background with
83 a dedicated <code>bt_field_class_*_create()</code> function.
85 - A field class with a pale background is an \em abstract field class:
86 you cannot create it, but it has properties, therefore there are
87 functions which apply to it.
89 For example, bt_field_class_integer_set_preferred_display_base()
90 applies to any \bt_int_fc.
92 Field classes are \ref api-fund-shared-object "shared objects": get a
93 new reference with bt_field_class_get_ref() and put an existing
94 reference with bt_field_class_put_ref().
96 Some library functions \ref api-fund-freezing "freeze" field classes on
97 success. The documentation of those functions indicate this
100 All the field class types share the same C type, #bt_field_class.
102 Get the type enumerator of a field class with bt_field_class_get_type().
103 Get whether or not a field class type conceptually \em is a given type
104 with the inline bt_field_class_type_is() function.
106 The following table shows the available type enumerators and creation
107 functions for each type of \em concrete (non-abstract) field class:
113 <th>Creation function
115 <td><em>\ref api-tir-fc-bool "Boolean"</em>
116 <td>#BT_FIELD_CLASS_TYPE_BOOL
117 <td>bt_field_class_bool_create()
119 <td><em>\ref api-tir-fc-ba "Bit array"</em>
120 <td>#BT_FIELD_CLASS_TYPE_BIT_ARRAY
121 <td>bt_field_class_bit_array_create()
123 <td><em>Unsigned \ref api-tir-fc-int "integer"</em>
124 <td>#BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER
125 <td>bt_field_class_integer_unsigned_create()
127 <td><em>Signed \ref api-tir-fc-int "integer"</em>
128 <td>#BT_FIELD_CLASS_TYPE_SIGNED_INTEGER
129 <td>bt_field_class_integer_signed_create()
131 <td><em>Unsigned \ref api-tir-fc-enum "enumeration"</em>
132 <td>#BT_FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION
133 <td>bt_field_class_enumeration_unsigned_create()
135 <td><em>Signed \ref api-tir-fc-enum "enumeration"</em>
136 <td>#BT_FIELD_CLASS_TYPE_SIGNED_ENUMERATION
137 <td>bt_field_class_enumeration_signed_create()
139 <td><em>Single-precision \ref api-tir-fc-real "real"</em>
140 <td>#BT_FIELD_CLASS_TYPE_SINGLE_PRECISION_REAL
141 <td>bt_field_class_real_single_precision_create()
143 <td><em>Double-precision \ref api-tir-fc-real "real"</em>
144 <td>#BT_FIELD_CLASS_TYPE_DOUBLE_PRECISION_REAL
145 <td>bt_field_class_real_double_precision_create()
147 <td><em>\ref api-tir-fc-string "String"</em>
148 <td>#BT_FIELD_CLASS_TYPE_STRING
149 <td>bt_field_class_string_create()
151 <td><em>Static \ref api-tir-fc-array "array"</em>
152 <td>#BT_FIELD_CLASS_TYPE_STATIC_ARRAY
153 <td>bt_field_class_array_static_create()
155 <td><em>Dynamic \ref api-tir-fc-array "array" (no length field)</em>
156 <td>#BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD
157 <td>bt_field_class_array_dynamic_create()
159 <td><em>Dynamic \ref api-tir-fc-array "array" (with length field)</em>
160 <td>#BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD
161 <td>bt_field_class_array_dynamic_create()
163 <td><em>\ref api-tir-fc-struct "Structure"</em>
164 <td>#BT_FIELD_CLASS_TYPE_STRUCTURE
165 <td>bt_field_class_structure_create()
167 <td><em>\ref api-tir-fc-opt "Option" (no selector field)</em>
168 <td>#BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD
169 <td>bt_field_class_option_without_selector_create()
171 <td><em>\ref api-tir-fc-opt "Option" (boolean selector field)</em>
172 <td>#BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD
173 <td>bt_field_class_option_with_selector_field_bool_create()
175 <td><em>\ref api-tir-fc-opt "Option" (unsigned integer selector field)</em>
176 <td>#BT_FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
177 <td>bt_field_class_option_with_selector_field_integer_unsigned_create()
179 <td><em>\ref api-tir-fc-opt "Option" (signed integer selector field)</em>
180 <td>#BT_FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD
181 <td>bt_field_class_option_with_selector_field_integer_signed_create()
183 <td><em>\ref api-tir-fc-var "Variant" (no selector field)</em>
184 <td>#BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD
185 <td>bt_field_class_variant_create()
187 <td><em>\ref api-tir-fc-var "Variant" (unsigned integer selector field)</em>
188 <td>#BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
189 <td>bt_field_class_variant_create()
191 <td><em>\ref api-tir-fc-var "Variant" (signed integer selector field)</em>
192 <td>#BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD
193 <td>bt_field_class_variant_create()
196 You need a \bt_trace_cls to create a field class: create one from a
197 \bt_self_comp with bt_trace_class_create().
199 Outside the field class API, you can use field classes at four
200 locations, called <em>scopes</em>, within the trace IR API:
202 - To set the packet context field class of a \bt_stream_cls with
203 bt_stream_class_set_packet_context_field_class().
205 - To set the event common context field class of a stream class with
206 bt_stream_class_set_event_common_context_field_class().
208 - To set the specific context field class of an \bt_ev_cls with
209 bt_event_class_set_specific_context_field_class().
211 - To set the payload field class of an event class with
212 bt_event_class_set_payload_field_class().
214 When you call one of the four functions above:
216 - The passed field class must be a \bt_struct_fc.
218 - You must \em not have already called any of the four functions above
219 with the passed field class or with any of its contained field
222 - If any of the field classes recursively contained in the passed
223 field class has a \ref api-tir-fc-link "link to another field class",
224 it must honor the field class link rules.
226 Once you have called one of the four functions above, the passed field
227 class becomes \ref api-fund-freezing "frozen".
229 <h1>Common field class property</h1>
231 A field class has the following common property:
235 \anchor api-tir-fc-prop-user-attrs
236 \bt_dt_opt User attributes
239 User attributes of the field class.
241 User attributes are custom attributes attached to a field class.
243 Use bt_field_class_set_user_attributes(),
244 bt_field_class_borrow_user_attributes(), and
245 bt_field_class_borrow_user_attributes_const().
249 <h1>\anchor api-tir-fc-bool Boolean field class</h1>
251 @image html fc-bool.png
253 A <strong><em>boolean field class</em></strong> is the class
256 A boolean field contains a boolean value (#BT_TRUE or #BT_FALSE).
258 Create a boolean field class with bt_field_class_bool_create().
260 A boolean field class has no specific properties.
262 <h1>\anchor api-tir-fc-ba Bit array field class</h1>
264 @image html fc-ba.png
266 A <strong><em>bit array field class</em></strong> is the class
269 A bit array field contains a fixed-length array of bits.
271 Create a bit array field class with bt_field_class_bit_array_create().
273 A bit array field class has the following property:
277 \anchor api-tir-fc-ba-prop-len
281 Number of bits contained in the instances (bit array fields) of
282 the bit array field class.
284 As of \bt_name_version_min_maj, the maximum length of a bit array
287 You cannot change the length once the bit array field class is
290 Get a bit array field class's length with
291 bt_field_class_bit_array_get_length().
295 <h1>\anchor api-tir-fc-int Integer field classes</h1>
297 @image html fc-int.png
299 <strong><em>Integer field classes</em></strong> are classes
302 Integer fields contain integral values.
304 An integer field class is an \em abstract field class: you cannot create
305 one. The concrete integer field classes are:
308 <dt>Unsigned integer field class</dt>
310 Its instances (unsigned integer fields) contain an unsigned integral
313 Create with bt_field_class_integer_unsigned_create().
316 <dt>Signed integer field class</dt>
318 Its instances (signed integer fields) contain a signed integral
321 Create with bt_field_class_integer_signed_create().
325 Integer field classes have the following common properties:
329 \anchor api-tir-fc-int-prop-size
333 Expected range of values that the instances (integer fields)
334 of the integer field class can contain.
336 For example, if the field value range of an unsigned integer
337 field class is [0, 16383], then its unsigned integer fields
338 can only contain the values from 0 to 16383.
340 \bt_cp_sink_comp can benefit from this property to make some space
341 optimizations when writing trace data.
343 Use bt_field_class_integer_set_field_value_range() and
344 bt_field_class_integer_get_field_value_range().
348 \anchor api-tir-fc-int-prop-base
349 Preferred display base
352 Preferred base (2, 8, 10, or 16) to use when displaying the
353 instances (integer fields) of the integer field class.
355 Use bt_field_class_integer_set_preferred_display_base() and
356 bt_field_class_integer_get_preferred_display_base().
360 <h2>\anchor api-tir-fc-enum Enumeration field classes</h2>
362 @image html fc-enum.png
364 <strong><em>Enumeration field classes</em></strong> are classes
367 Enumeration field classes \em are \bt_p_int_fc: they have the integer
368 field classes properties.
370 Enumeration fields \em are integer fields: they contain integral values.
372 Enumeration field classes associate labels (strings) to specific
373 ranges of integral values. This association is called an enumeration
374 field class <em>mapping</em>.
376 For example, if an enumeration field class maps the label \c SUGAR to
377 the integer ranges [1, 19] and [25, 31], then an instance
378 (enumeration field) of this field class with the value 15 or 28 has the
379 label <code>SUGAR</code>.
381 An enumeration field class is an \em abstract field class: you cannot
382 create one. The concrete enumeration field classes are:
385 <dt>Unsigned enumeration field class</dt>
387 Its instances (unsigned enumeration fields) contain an unsigned
390 Create with bt_field_class_enumeration_unsigned_create().
393 <dt>Signed enumeration field class</dt>
395 Its instances (signed enumeration fields) contain a signed value
398 Create with bt_field_class_enumeration_signed_create().
402 Enumeration field classes have the following common property:
406 \anchor api-tir-fc-enum-prop-mappings
410 Set of mappings of the enumeration field class.
412 An enumeration field class mapping is a label (string) and an
415 The integer ranges of a given mapping or of multiple mappings of
416 the same enumeration field class can overlap. For example,
417 an enumeration field class can have those two mappings:
419 - <code>CALORIES</code>: [1, 11], [15, 37]
420 - <code>SODIUM</code>: [7, 13]
422 In that case, the values 2 and 30 correpond to the label
423 <code>CALORIES</code>, the value 12 to the label
424 <code>SODIUM</code>, and the value 10 to the labels
425 \c CALORIES \em and <code>SODIUM</code>.
427 Two mappings of the same enumeration field class cannot have the
430 Add a mapping to an enumeration field class with
431 bt_field_class_enumeration_unsigned_add_mapping() or
432 bt_field_class_enumeration_signed_add_mapping().
434 Get the number of mappings in an enumeration field class with
435 bt_field_class_enumeration_get_mapping_count().
437 Borrow a mapping from an enumeration field class with
438 bt_field_class_enumeration_unsigned_borrow_mapping_by_index_const(),
439 bt_field_class_enumeration_signed_borrow_mapping_by_index_const(),
440 bt_field_class_enumeration_unsigned_borrow_mapping_by_label_const(),
442 bt_field_class_enumeration_signed_borrow_mapping_by_label_const().
444 An enumeration field class mapping is a
445 \ref api-fund-unique-object "unique object": it
446 belongs to the enumeration field class which contains it.
448 There are two enumeration field class mapping types, depending on
449 the field class's type:
450 #bt_field_class_enumeration_unsigned_mapping and
451 #bt_field_class_enumeration_signed_mapping.
453 There is also the #bt_field_class_enumeration_mapping type for
454 common properties and operations (for example,
455 bt_field_class_enumeration_mapping_get_label()).
456 \ref api-fund-c-typing "Upcast" a specific enumeration field class
457 mapping to the #bt_field_class_enumeration_mapping type with
458 bt_field_class_enumeration_unsigned_mapping_as_mapping_const() or
459 bt_field_class_enumeration_signed_mapping_as_mapping_const().
461 Get all the enumeration field class labels mapped to a given integer
463 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value()
465 bt_field_class_enumeration_signed_get_mapping_labels_for_value().
469 <h1>\anchor api-tir-fc-real Real field classes</h1>
471 @image html fc-real.png
473 <strong><em>Real field classes</em></strong> are classes
477 <a href="https://en.wikipedia.org/wiki/Real_number">real</a>
478 values (\c float or \c double types).
480 A real field class is an \em abstract field class: you cannot create
481 one. The concrete real field classes are:
484 <dt>Single-precision real field class</dt>
486 Its instances (single-precision real fields) contain a \c float
489 Create with bt_field_class_real_single_precision_create().
492 <dt>Double-precision real field class</dt>
494 Its instances (double-precision real fields) contain a \c double
497 Create with bt_field_class_real_double_precision_create().
501 Real field classes have no specific properties.
503 <h1>\anchor api-tir-fc-string String field class</h1>
505 @image html fc-string.png
507 A <strong><em>string field class</em></strong> is the class
508 of \bt_p_string_field.
510 A string field contains an UTF-8 string value.
512 Create a string field class with bt_field_class_string_create().
514 A string field class has no specific properties.
516 <h1>\anchor api-tir-fc-array Array field classes</h1>
518 @image html fc-array.png
520 <strong><em>Array field classes</em></strong> are classes
521 of \bt_p_array_field.
523 Array fields contain zero or more fields which have the same class.
525 An array field class is an \em abstract field class: you cannot create
526 one. The concrete array field classes are:
529 <dt>Static array field class</dt>
531 Its instances (static array fields) contain a fixed number of
534 Create with bt_field_class_array_static_create().
536 A static array field class has the following specific property:
540 \anchor api-tir-fc-sarray-prop-len
544 Number of fields contained in the instances (static array
545 fields) of the static array field class.
547 You cannot change the length once the static array field class
550 Get a static array field class's length with
551 bt_field_class_array_static_get_length().
556 <dt>Dynamic array field class</dt>
558 Its instances (dynamic array fields) contain a variable number array
561 There are two types of dynamic array field classes: without or
562 with a length field. See
563 \ref api-tir-fc-link "Field classes with links to other field classes"
566 @image html darray-link.png "Dynamic array field class with a length field."
568 Create with bt_field_class_array_dynamic_create().
570 A dynamic array field class with a length field has the
575 \anchor api-tir-fc-darray-prop-len-fp
579 Field path of the linked length field class.
581 Get a dynamic array field class's length field path with
582 bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const().
588 Array field classes have the following common property:
592 \anchor api-tir-fc-array-prop-elem-fc
596 Class of the fields contained in the instances (array fields) of the
599 You cannot change the element field class once the array field class
602 Borrow an array field class's element field class with
603 Use bt_field_class_array_borrow_element_field_class() and
604 bt_field_class_array_borrow_element_field_class_const().
608 <h1>\anchor api-tir-fc-struct Structure field class</h1>
610 @image html fc-struct.png
612 A <strong><em>structure field class</em></strong> is the class
613 of a \bt_struct_field.
615 A structure field contains an ordered list of zero or more members. Each
616 structure field member is the instance of a structure field class
617 member. A structure field class member has a name, a field class,
620 Create a structure field class with bt_field_class_structure_create().
622 A structure field class has the following specific property:
626 \anchor api-tir-fc-struct-prop-members
630 Ordered list of members (zero or more) of the structure field class.
634 - A name, unique amongst all the member names of the same
635 structure field class.
639 The instances (structure fields) of a structure field class have
640 members which are instances of the corresponding structure field
643 Append a member to a structure field class with
644 bt_field_class_structure_append_member().
646 Borrow a member from a structure field class with
647 bt_field_class_structure_borrow_member_by_index(),
648 bt_field_class_structure_borrow_member_by_name(),
649 bt_field_class_structure_borrow_member_by_index_const(), and
650 bt_field_class_structure_borrow_member_by_name_const().
652 A structure field class member is a
653 \ref api-fund-unique-object "unique object": it
654 belongs to the structure field class which contains it.
656 The type of a structure field class member is
657 #bt_field_class_structure_member.
659 Get a structure field class member's name with
660 bt_field_class_structure_member_get_name().
662 Borrow a structure field class member's field class with
663 bt_field_class_structure_member_borrow_field_class() and
664 bt_field_class_structure_member_borrow_field_class_const().
666 Set a structure field class member's user attributes with
667 bt_field_class_structure_member_set_user_attributes().
669 Borrow a structure field class member's user attributes with
670 bt_field_class_structure_member_borrow_user_attributes() and
671 bt_field_class_structure_member_borrow_user_attributes_const().
675 <h1>\anchor api-tir-fc-opt Option field classes</h1>
677 @image html fc-opt.png
679 <strong><em>Option field classes</em></strong> are classes
682 An option field either does or doesn't contain a field, called its
685 An option field class is an \em abstract field class: you cannot create
686 one. An option field class either has a selector field (it's linked to a
687 selector field class; see
688 \ref api-tir-fc-link "Field classes with links to other field classes")
689 or none. Therefore, the concrete option field classes are:
692 <dt>Option field class without a selector field</dt>
694 Create with bt_field_class_option_without_selector_create().
696 An option field class without a selector field has no specific
700 <dt>Option field class with a boolean selector field</dt>
702 The linked selector field of an option field class's instance
703 (an option field) is a \bt_bool_field.
705 Consequently, the option field class's selector field class is
708 @image html opt-link.png "Option field class with a boolean selector field."
710 Create with bt_field_class_option_with_selector_field_bool_create().
712 An option field class with a boolean selector field has the
713 following specific property:
717 \anchor api-tir-fc-opt-prop-sel-rev
718 Selector is reversed?
721 Whether or not the linked boolean selector field makes the
722 option field class's instance (an option field) contain a field
723 when it's #BT_TRUE or when it's #BT_FALSE.
725 If this property is #BT_TRUE, then if the linked selector field
726 has the value #BT_FALSE, the option field contains a field.
729 bt_field_class_option_with_selector_field_bool_set_selector_is_reversed()
731 bt_field_class_option_with_selector_field_bool_selector_is_reversed().
736 <dt>Option field class with an unsigned selector field</dt>
738 The linked selector field of an option field class's instance
739 (an option field) is an \bt_uint_field.
741 Consequently, the option field class's selector field class is
745 bt_field_class_option_with_selector_field_integer_unsigned_create().
747 Pass an \bt_uint_rs on creation to set which values of the selector
748 field can make the option field contain a field.
750 An option field class with an unsigned integer selector field has
751 the following specific property:
755 \anchor api-tir-fc-opt-prop-uint-rs
756 Selector's unsigned integer ranges
759 If the linked unsigned integer selector field of an option
760 field class's instance (an option field) has a value which
761 intersects with the selector's unsigned integer ranges, then
762 the option field contains a field.
764 You cannot change the selector's unsigned integer ranges once
765 the option field class is created.
767 Borrow the selector's unsigned integer ranges from an
768 option field class with an unsigned integer selector field with
769 bt_field_class_option_with_selector_field_integer_unsigned_borrow_selector_ranges_const().
774 <dt>Option field class with a signed selector field</dt>
776 The linked selector field of an option field class's instance
777 (an option field) is a \bt_sint_field.
779 Consequently, the option field class's selector field class is
783 bt_field_class_option_with_selector_field_integer_signed_create().
785 Pass a \bt_sint_rs on creation to set which values of the selector
786 field can make the option field contain a field.
788 An option field class with a signed integer selector field has
789 the following specific property:
793 \anchor api-tir-fc-opt-prop-sint-rs
794 Selector's signed integer ranges
797 If the linked signed integer selector field of an option
798 field class's instance (an option field) has a value which
799 intersects with the selector's signed integer ranges, then
800 the option field contains a field.
802 You cannot change the selector's signed integer ranges once
803 the option field class is created.
805 Borrow the selector's signed integer ranges from an
806 option field class with a signed integer selector field with
807 bt_field_class_option_with_selector_field_integer_signed_borrow_selector_ranges_const().
813 Option field classes with a selector have the following common
818 \anchor api-tir-fc-opt-prop-sel-fp
822 Field path of the linked selector field class.
824 Borrow such an option field class's selector field path with
825 bt_field_class_option_with_selector_field_borrow_selector_field_path_const().
829 Option field classes have the following common property:
833 \anchor api-tir-fc-opt-prop-fc
837 Class of the optional field of an instance (option field) of the
840 You cannot change the optional field class once the option field
843 Borrow an option field class's optional field class with
844 Use bt_field_class_option_borrow_field_class() and
845 bt_field_class_option_borrow_field_class_const().
849 <h1>\anchor api-tir-fc-var Variant field classes</h1>
851 @image html fc-var.png
853 <strong><em>Variant field classes</em></strong> are classes
856 A variant field contains a field amongst one or more possible fields.
858 Variant field classes contain one or more options. Each variant field
859 class option has a name, a field class, user attributes, and integer
860 ranges, depending on the exact type.
862 A variant field class is an \em abstract field class: you cannot create
863 one. A variant field class either has a selector field (it's linked to a
864 selector field class; see
865 \ref api-tir-fc-link "Field classes with links to other field classes")
866 or none. Therefore, the concrete variant field classes are:
869 <dt>Variant field class without a selector field</dt>
871 Create with bt_field_class_variant_create(), passing \c NULL as
872 the selector field class.
874 Append an option to such a variant field class with
875 bt_field_class_variant_without_selector_append_option().
877 A variant field class without a selector field has no specific
881 <dt>Variant field class with an unsigned selector field</dt>
883 The linked selector field of a variant field class's instance
884 (a variant field) is an \bt_uint_field.
886 Consequently, the variant field class's selector field class is
889 @image html var-link.png "Variant field class with an unsigned integer selector field."
891 Create with bt_field_class_variant_create(), passing an
892 unsigned integer field class as the selector field class.
894 Append an option to such a variant field class with
895 bt_field_class_variant_with_selector_field_integer_unsigned_append_option().
897 Pass an \bt_uint_rs when you append an option to set which values of
898 the selector field can make the variant field have a given
901 Borrow such a variant field class's option with
902 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const()
904 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const().
907 <dt>Variant field class with a signed selector field</dt>
909 The linked selector field of a variant field class's instance
910 (a variant field) is a \bt_sint_field.
912 Consequently, the variant field class's selector field class is
915 Create with bt_field_class_variant_create(), passing a
916 signed integer field class as the selector field class.
918 Append an option to such a variant field class with
919 bt_field_class_variant_with_selector_field_integer_signed_append_option().
921 Pass a \bt_sint_rs when you append an option to set which values of
922 the selector field can make the variant field have a given
925 Borrow such a variant field class's option with
926 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const()
928 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const().
932 Variant field classes with a selector have the following common
937 \anchor api-tir-fc-var-prop-sel-fp
941 Field path of the linked selector field class.
943 Borrow such a variant field class's selector field path with
944 bt_field_class_variant_with_selector_field_borrow_selector_field_path_const().
948 Variant field classes have the following common property:
952 \anchor api-tir-fc-var-prop-opts
956 Options of the variant field class.
960 - A name, unique amongst all the option names of the same
965 If the variant field class is linked to a selector field class, then
966 each option also has an \bt_int_rs. In that case, the ranges of a
967 given option cannot overlap any range of any other option.
969 A variant field class must contain at least one option.
971 Depending on whether or not the variant field class has a selector
972 field class, append an option to a variant field class
973 with bt_field_class_variant_without_selector_append_option(),
974 bt_field_class_variant_with_selector_field_integer_unsigned_append_option(),
976 bt_field_class_variant_with_selector_field_integer_signed_append_option().
978 Get the number of options contained in a variant field class
979 with bt_field_class_variant_get_option_count().
981 A variant field class option is a
982 \ref api-fund-unique-object "unique object": it
983 belongs to the variant field class which contains it.
985 Borrow any variant field class's option with
986 bt_field_class_variant_borrow_option_by_index(),
987 bt_field_class_variant_borrow_option_by_name(),
988 bt_field_class_variant_borrow_option_by_index_const(), and
989 bt_field_class_variant_borrow_option_by_name_const().
991 Those functions return the common #bt_field_class_variant_option
992 type. Get the name of a variant field class option with
993 bt_field_class_variant_option_get_name(). Borrow a variant field
994 class option's field class with
995 bt_field_class_variant_option_borrow_field_class() and
996 bt_field_class_variant_option_borrow_field_class_const().
998 Borrow the option of a variant field classes with a selector field
1000 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(),
1001 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const(),
1002 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(), or
1003 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const(),
1004 depending on the selector field class's type.
1006 Those functions return the
1007 #bt_field_class_variant_with_selector_field_integer_unsigned_option or
1008 #bt_field_class_variant_with_selector_field_integer_signed_option type.
1009 \ref api-fund-c-typing "Upcast" those types to the
1010 #bt_field_class_variant_option type with
1011 bt_field_class_variant_with_selector_field_integer_unsigned_option_as_option_const()
1013 bt_field_class_variant_with_selector_field_integer_signed_option_as_option_const().
1015 Borrow the option's ranges from a variant field class with a
1016 selector field class with
1017 bt_field_class_variant_with_selector_field_integer_unsigned_option_borrow_ranges_const()
1019 bt_field_class_variant_with_selector_field_integer_signed_option_borrow_ranges_const().
1021 Set a variant field class option's user attributes with
1022 bt_field_class_variant_option_set_user_attributes().
1024 Borrow a variant field class option's user attributes with
1025 bt_field_class_variant_option_borrow_user_attributes() and
1026 bt_field_class_variant_option_borrow_user_attributes_const().
1030 <h1>\anchor api-tir-fc-link Field classes with links to other field classes</h1>
1032 \bt_cp_darray_fc, \bt_p_opt_fc, and \bt_p_var_fc \em can have links to
1033 other, preceding field classes.
1035 When a field class A has a link to another field class B, then
1036 an instance (\bt_field) of A has a link to an instance of B.
1038 This feature exists so that the linked field can contain the value of a
1039 dynamic property of the field. Those properties are:
1042 <dt>\bt_c_darray_field</dt>
1044 The linked field, a \bt_uint_field, contains the \b length of the
1045 dynamic array field.
1048 <dt>\bt_c_opt_field</dt>
1050 The linked field, either a \bt_bool_field or an \bt_int_field,
1051 indicates whether or not the option field has a field.
1054 <dt>\bt_c_var_field</dt>
1056 The linked field, an \bt_int_field, indicates the variant field's
1057 current selected field.
1061 Having a linked field class is <em>optional</em>: you always set the
1062 field properties with a dedicated function anyway. For example, even if
1063 a dynamic array field is linked to a preceding length field, you must
1064 still set its length with bt_field_array_dynamic_set_length(). In that
1065 case, the value of the length field must match what you pass to
1066 bt_field_array_dynamic_set_length().
1068 The purpose of this feature is to eventually save space when a
1069 \bt_sink_comp writes trace files: if the trace format can convey that
1070 a preceding, existing field represents the length of a dynamic array
1071 field, then the sink component doesn't need to write the dynamic array
1072 field's length twice. This is the case of the
1073 <a href="https://diamon.org/ctf/">Common Trace Format</a>, for
1076 @image html darray-link.png "A dynamic array field class linked to an unsigned integer field class."
1078 To link a field class A to a preceding field class B, pass
1079 field class B when you create field class A. For example, pass
1080 the \bt_uint_fc to bt_field_class_array_dynamic_create() to create a
1081 \bt_darray_fc with a length field.
1083 When you call bt_stream_class_set_packet_context_field_class(),
1084 bt_stream_class_set_event_common_context_field_class(),
1085 bt_event_class_set_specific_context_field_class(), or
1086 bt_event_class_set_payload_field_class() with a field class containing
1087 a field class A with a linked field class B, the path to
1088 B becomes available in A. The functions to borrow this field path are:
1090 - bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const()
1091 - bt_field_class_option_with_selector_field_borrow_selector_field_path_const()
1092 - bt_field_class_variant_with_selector_field_borrow_selector_field_path_const()
1094 A field path indicates how to reach a linked field from a given
1095 root <em>scope</em>. The available scopes are:
1098 <dt>#BT_FIELD_PATH_SCOPE_PACKET_CONTEXT</dt>
1100 Packet context field.
1102 See bt_packet_borrow_context_field_const().
1105 <dt>#BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT</dt>
1107 Event common context field.
1109 See bt_event_borrow_common_context_field_const().
1112 <dt>#BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT</dt>
1114 Event specific context field.
1116 See bt_event_borrow_specific_context_field_const().
1119 <dt>#BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD</dt>
1121 Event payload field.
1123 See bt_event_borrow_payload_field_const().
1127 The rules regarding field class A vs. field class B (linked
1130 - If A is within a packet context field class, B must also be in the
1131 same packet context field class.
1133 See bt_stream_class_set_packet_context_field_class().
1135 - If A is within a event common context field class, B must be in one
1138 - The same event common context field class.
1139 - The packet context field class of the same \bt_stream_cls.
1141 See bt_stream_class_set_event_common_context_field_class().
1143 - If A is within an event specific context field class, B must be in
1146 - The same event specific context field class.
1147 - The event common context field class of the same stream class.
1148 - The packet context field class of the same stream class.
1150 See bt_event_class_set_specific_context_field_class().
1152 - If A is within an event payload field class, B must be in one of:
1154 - The same event payload field class.
1155 - The event specific context field class of the same \bt_ev_cls.
1156 - The event common context field class of the same stream class.
1157 - The packet context field class of the same stream class.
1159 See bt_event_class_set_payload_field_class().
1161 - If both A and B are in the same scope, then:
1163 - The lowest common ancestor field class of A and B must be a
1168 Considering that the members of a structure field class are ordered,
1169 then B must be part of a member that's before the member which
1170 contains A in their lowest common ancestor structure field class.
1172 - The path from the lowest common ancestor structure field class of A
1173 and B to A and to B must only contain structure field classes.
1175 - If A is in a different scope than B, the path from the root scope of B
1176 to B must only contain structure field classes.
1185 @typedef struct bt_field_class bt_field_class;
1200 Field class type enumerators.
1202 typedef enum bt_field_class_type
{
1207 BT_FIELD_CLASS_TYPE_BOOL
= 1ULL << 0,
1213 BT_FIELD_CLASS_TYPE_BIT_ARRAY
= 1ULL << 1,
1219 No field class has this type: use it with
1220 bt_field_class_type_is().
1222 BT_FIELD_CLASS_TYPE_INTEGER
= 1ULL << 2,
1228 This type conceptually inherits #BT_FIELD_CLASS_TYPE_INTEGER.
1230 BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER
= (1ULL << 3) | BT_FIELD_CLASS_TYPE_INTEGER
,
1236 This type conceptually inherits #BT_FIELD_CLASS_TYPE_INTEGER.
1238 BT_FIELD_CLASS_TYPE_SIGNED_INTEGER
= (1ULL << 4) | BT_FIELD_CLASS_TYPE_INTEGER
,
1244 This type conceptually inherits #BT_FIELD_CLASS_TYPE_INTEGER.
1246 No field class has this type: use it with
1247 bt_field_class_type_is().
1249 BT_FIELD_CLASS_TYPE_ENUMERATION
= 1ULL << 5,
1255 This type conceptually inherits #BT_FIELD_CLASS_TYPE_ENUMERATION
1256 and #BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER.
1258 BT_FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION
= BT_FIELD_CLASS_TYPE_ENUMERATION
| BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER
,
1264 This type conceptually inherits #BT_FIELD_CLASS_TYPE_ENUMERATION
1265 and #BT_FIELD_CLASS_TYPE_SIGNED_INTEGER.
1267 BT_FIELD_CLASS_TYPE_SIGNED_ENUMERATION
= BT_FIELD_CLASS_TYPE_ENUMERATION
| BT_FIELD_CLASS_TYPE_SIGNED_INTEGER
,
1273 No field class has this type: use it with
1274 bt_field_class_type_is().
1276 BT_FIELD_CLASS_TYPE_REAL
= 1ULL << 6,
1280 Single-precision \bt_real_fc.
1282 This type conceptually inherits #BT_FIELD_CLASS_TYPE_REAL.
1284 BT_FIELD_CLASS_TYPE_SINGLE_PRECISION_REAL
= (1ULL << 7) | BT_FIELD_CLASS_TYPE_REAL
,
1288 Double-precision \bt_real_fc.
1290 This type conceptually inherits #BT_FIELD_CLASS_TYPE_REAL.
1292 BT_FIELD_CLASS_TYPE_DOUBLE_PRECISION_REAL
= (1ULL << 8) | BT_FIELD_CLASS_TYPE_REAL
,
1298 BT_FIELD_CLASS_TYPE_STRING
= 1ULL << 9,
1304 BT_FIELD_CLASS_TYPE_STRUCTURE
= 1ULL << 10,
1310 No field class has this type: use it with
1311 bt_field_class_type_is().
1313 BT_FIELD_CLASS_TYPE_ARRAY
= 1ULL << 11,
1319 This type conceptually inherits #BT_FIELD_CLASS_TYPE_ARRAY.
1321 BT_FIELD_CLASS_TYPE_STATIC_ARRAY
= (1ULL << 12) | BT_FIELD_CLASS_TYPE_ARRAY
,
1327 This type conceptually inherits #BT_FIELD_CLASS_TYPE_ARRAY.
1329 No field class has this type: use it with
1330 bt_field_class_type_is().
1332 BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY
= (1ULL << 13) | BT_FIELD_CLASS_TYPE_ARRAY
,
1336 \bt_c_darray_fc (without a length field).
1338 This type conceptually inherits
1339 #BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY.
1341 BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD
= (1ULL << 14) | BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY
,
1345 \bt_c_darray_fc (with a length field).
1347 This type conceptually inherits
1348 #BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY.
1350 BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD
= (1ULL << 15) | BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY
,
1356 No field class has this type: use it with
1357 bt_field_class_type_is().
1359 BT_FIELD_CLASS_TYPE_OPTION
= 1ULL << 16,
1363 \bt_c_opt_fc (without a selector field).
1365 BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD
= (1ULL << 17) | BT_FIELD_CLASS_TYPE_OPTION
,
1369 \bt_c_opt_fc (with a selector field).
1371 This type conceptually inherits #BT_FIELD_CLASS_TYPE_OPTION.
1373 No field class has this type: use it with
1374 bt_field_class_type_is().
1376 BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD
= (1ULL << 18) | BT_FIELD_CLASS_TYPE_OPTION
,
1380 \bt_c_opt_fc (with a boolean selector field).
1382 This type conceptually inherits
1383 #BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD.
1385 BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD
= (1ULL << 19) | BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD
,
1389 \bt_c_opt_fc (with an integer selector field).
1391 This type conceptually inherits
1392 #BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD.
1394 No field class has this type: use it with
1395 bt_field_class_type_is().
1397 BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD
= (1ULL << 20) | BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD
,
1401 \bt_c_opt_fc (with an unsigned integer selector field).
1403 This type conceptually inherits
1404 #BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD.
1406 BT_FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
= (1ULL << 21) | BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD
,
1410 \bt_c_opt_fc (with a signed integer selector field).
1412 This type conceptually inherits
1413 #BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD.
1415 BT_FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD
= (1ULL << 22) | BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD
,
1421 No field class has this type: use it with
1422 bt_field_class_type_is().
1424 BT_FIELD_CLASS_TYPE_VARIANT
= 1ULL << 23,
1428 \bt_c_var_fc (without a selector field).
1430 BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD
= (1ULL << 24) | BT_FIELD_CLASS_TYPE_VARIANT
,
1434 \bt_c_var_fc (with a selector field).
1436 This type conceptually inherits
1437 #BT_FIELD_CLASS_TYPE_VARIANT.
1439 No field class has this type: use it with
1440 bt_field_class_type_is().
1442 BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD
= (1ULL << 25) | BT_FIELD_CLASS_TYPE_VARIANT
,
1446 \bt_c_var_fc (with an integer selector field).
1448 This type conceptually inherits
1449 #BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD.
1451 No field class has this type: use it with
1452 bt_field_class_type_is().
1454 BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD
= (1ULL << 26) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD
,
1458 \bt_c_opt_fc (with an unsigned integer selector field).
1460 This type conceptually inherits
1461 #BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD.
1463 BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
= (1ULL << 27) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD
,
1467 \bt_c_opt_fc (with a signed integer selector field).
1469 This type conceptually inherits
1470 #BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD.
1472 BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD
= (1ULL << 28) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD
,
1475 * Make sure the enumeration type is a 64-bit integer in case
1476 * the project needs field class types in the future.
1478 * This is not part of the API.
1480 __BT_FIELD_CLASS_TYPE_BIG_VALUE
= 1ULL << 62,
1481 } bt_field_class_type
;
1485 Returns the type enumerator of the field class \bt_p{field_class}.
1487 @param[in] field_class
1488 Field class of which to get the type enumerator
1491 Type enumerator of \bt_p{field_class}.
1493 @bt_pre_not_null{field_class}
1495 @sa bt_field_class_type_is() —
1496 Returns whether or not the type of a field class conceptually is a
1499 extern bt_field_class_type
bt_field_class_get_type(
1500 const bt_field_class
*field_class
);
1504 Returns whether or not the field class type \bt_p{type} conceptually
1505 \em is the field class type \bt_p{other_type}.
1507 For example, an \bt_uint_fc conceptually \em is an integer field class,
1511 bt_field_class_type_is(BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER, BT_FIELD_CLASS_TYPE_INTEGER)
1517 Field class type to check against \bt_p{other_type}.
1518 @param[in] other_type
1519 Field class type against which to check \bt_p{type}.
1522 #BT_TRUE if \bt_p{type} conceptually \em is \bt_p{other_type}.
1524 @sa bt_field_class_get_type() —
1525 Returns the type enumerator of a field class.
1528 bt_bool
bt_field_class_type_is(const bt_field_class_type type
,
1529 const bt_field_class_type other_type
)
1531 return (type
& other_type
) == other_type
;
1537 @name Common property
1543 Sets the user attributes of the field class \bt_p{field_class} to
1544 \bt_p{user_attributes}.
1546 See the \ref api-tir-fc-prop-user-attrs "user attributes" property.
1549 When you create a field class with one of the
1550 <code>bt_field_class_*_create()</code> functions, the field class's
1551 initial user attributes is an empty \bt_map_val. Therefore you can
1552 borrow it with bt_field_class_borrow_user_attributes() and fill it
1553 directly instead of setting a new one with this function.
1555 @param[in] field_class
1556 Field class of which to set the user attributes to
1557 \bt_p{user_attributes}.
1558 @param[in] user_attributes
1559 New user attributes of \bt_p{field_class}.
1561 @bt_pre_not_null{field_class}
1562 @bt_pre_hot{field_class}
1563 @bt_pre_not_null{user_attributes}
1564 @bt_pre_is_map_val{user_attributes}
1566 @sa bt_field_class_borrow_user_attributes() —
1567 Borrows the user attributes of a field class.
1569 extern void bt_field_class_set_user_attributes(
1570 bt_field_class
*field_class
, const bt_value
*user_attributes
);
1574 Borrows the user attributes of the field class \bt_p{field_class}.
1576 See the \ref api-tir-fc-prop-user-attrs "user attributes" property.
1579 When you create a field class with one of the
1580 <code>bt_field_class_*_create()</code> functions, the field class's
1581 initial user attributes is an empty \bt_map_val.
1583 @param[in] field_class
1584 Field class from which to borrow the user attributes.
1587 User attributes of \bt_p{field_class} (a \bt_map_val).
1589 @bt_pre_not_null{field_class}
1591 @sa bt_field_class_set_user_attributes() —
1592 Sets the user attributes of a field class.
1593 @sa bt_field_class_borrow_user_attributes_const() —
1594 \c const version of this function.
1596 extern bt_value
*bt_field_class_borrow_user_attributes(
1597 bt_field_class
*field_class
);
1601 Borrows the user attributes of the field class \bt_p{field_class}
1604 See bt_field_class_borrow_user_attributes().
1606 extern const bt_value
*bt_field_class_borrow_user_attributes_const(
1607 const bt_field_class
*field_class
);
1612 @name Boolean field class
1618 Creates a \bt_bool_fc from the trace class \bt_p{trace_class}.
1620 On success, the returned boolean field class has the following
1628 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
1629 <td>Empty \bt_map_val
1632 @param[in] trace_class
1633 Trace class from which to create a boolean field class.
1636 New boolean field class reference, or \c NULL on memory error.
1638 @bt_pre_not_null{trace_class}
1640 extern bt_field_class
*bt_field_class_bool_create(
1641 bt_trace_class
*trace_class
);
1648 @name Bit array field class
1654 Creates a \bt_ba_fc with the length \bt_p{length} from the trace
1655 class \bt_p{trace_class}.
1657 On success, the returned bit array field class has the following
1665 <td>\ref api-tir-fc-ba-prop-len "Length"
1668 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
1669 <td>Empty \bt_map_val
1672 @param[in] trace_class
1673 Trace class from which to create a bit array field class.
1675 Length (number of bits) of the instances of the bit array field
1679 New bit array field class reference, or \c NULL on memory error.
1681 @bt_pre_not_null{trace_class}
1683 0 < \bt_p{length} ≤ 64.
1685 extern bt_field_class
*bt_field_class_bit_array_create(
1686 bt_trace_class
*trace_class
, uint64_t length
);
1690 Returns the length of the \bt_ba_fc \bt_p{field_class}.
1692 See the \ref api-tir-fc-ba-prop-len "length" property.
1694 @param[in] field_class
1695 Bit array field class of which to get the length.
1698 Length of \bt_p{field_class}.
1700 @bt_pre_not_null{field_class}
1701 @bt_pre_is_ba_fc{field_class}
1703 extern uint64_t bt_field_class_bit_array_get_length(
1704 const bt_field_class
*field_class
);
1711 @name Integer field class
1717 Sets the field value range of the \bt_int_fc \bt_p{field_class}
1720 See the \ref api-tir-fc-int-prop-size "field value range" property.
1722 @param[in] field_class
1723 Integer field class of which to set the field value range to
1730 <dt>Unsigned integer field class</dt>
1731 <dd>[0, 2<sup><em>N</em></sup> − 1]</dd>
1733 <dt>Signed integer field class</dt>
1734 <dd>[−2<sup><em>N</em> − 1</sup>, 2<sup><em>N</em> − 1</sup> − 1]</dd>
1738 @bt_pre_not_null{field_class}
1739 @bt_pre_hot{field_class}
1740 @bt_pre_is_int_fc{field_class}
1742 1 ⩽ \bt_p{n} ⩽ 64.
1744 @sa bt_field_class_integer_get_field_value_range() —
1745 Returns the field value range of an integer field class.
1747 extern void bt_field_class_integer_set_field_value_range(
1748 bt_field_class
*field_class
, uint64_t n
);
1752 Returns the field value range of the \bt_int_fc \bt_p{field_class}.
1754 See the \ref api-tir-fc-int-prop-size "field value range" property.
1756 @param[in] field_class
1757 Integer field class of which to get the field value range.
1761 Field value range of \bt_p{field_class}, that is, \em N in:
1764 <dt>Unsigned integer field class</dt>
1765 <dd>[0, 2<sup><em>N</em></sup> − 1]</dd>
1767 <dt>Signed integer field class</dt>
1768 <dd>[−2<sup><em>N</em></sup>, 2<sup><em>N</em></sup> − 1]</dd>
1772 @bt_pre_not_null{field_class}
1773 @bt_pre_is_int_fc{field_class}
1775 @sa bt_field_class_integer_set_field_value_range() —
1776 Sets the field value range of an integer field class.
1778 extern uint64_t bt_field_class_integer_get_field_value_range(
1779 const bt_field_class
*field_class
);
1783 Integer field class preferred display bases.
1785 typedef enum bt_field_class_integer_preferred_display_base
{
1790 BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_BINARY
= 2,
1796 BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_OCTAL
= 8,
1802 BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
= 10,
1808 BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_HEXADECIMAL
= 16,
1809 } bt_field_class_integer_preferred_display_base
;
1813 Sets the preferred display base of the \bt_int_fc \bt_p{field_class}
1814 to \bt_p{preferred_display_base}.
1816 See the \ref api-tir-fc-int-prop-base "preferred display base" property.
1818 @param[in] field_class
1819 Integer field class of which to set the preferred display base to
1820 \bt_p{preferred_display_base}.
1821 @param[in] preferred_display_base
1822 New preferred display base of \bt_p{field_class}.
1824 @bt_pre_not_null{field_class}
1825 @bt_pre_hot{field_class}
1826 @bt_pre_is_int_fc{field_class}
1828 @sa bt_field_class_integer_get_preferred_display_base() —
1829 Returns the preferred display base of an integer field class.
1831 extern void bt_field_class_integer_set_preferred_display_base(
1832 bt_field_class
*field_class
,
1833 bt_field_class_integer_preferred_display_base preferred_display_base
);
1837 Returns the preferred display base of the \bt_int_fc
1840 See the \ref api-tir-fc-int-prop-base "preferred display base" property.
1842 @param[in] field_class
1843 Integer field class of which to get the preferred display base.
1845 @retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_BINARY
1847 @retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_OCTAL
1849 @retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
1851 @retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_HEXADECIMAL
1854 @bt_pre_not_null{field_class}
1855 @bt_pre_is_int_fc{field_class}
1857 @sa bt_field_class_integer_set_preferred_display_base() —
1858 Sets the preferred display base of an integer field class.
1860 extern bt_field_class_integer_preferred_display_base
1861 bt_field_class_integer_get_preferred_display_base(
1862 const bt_field_class
*field_class
);
1867 @name Unsigned integer field class
1873 Creates an \bt_uint_fc from the trace class \bt_p{trace_class}.
1875 On success, the returned unsigned integer field class has the following
1883 <td>\ref api-tir-fc-int-prop-size "Field value range"
1884 <td>[0, 2<sup>64</sup> − 1]
1886 <td>\ref api-tir-fc-int-prop-base "Preferred display base"
1887 <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
1889 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
1890 <td>Empty \bt_map_val
1893 @param[in] trace_class
1894 Trace class from which to create an unsigned integer field class.
1897 New unsigned integer field class reference, or \c NULL on memory error.
1899 @bt_pre_not_null{trace_class}
1901 extern bt_field_class
*bt_field_class_integer_unsigned_create(
1902 bt_trace_class
*trace_class
);
1907 @name Signed integer field class
1913 Creates an \bt_sint_fc from the trace class \bt_p{trace_class}.
1915 On success, the returned signed integer field class has the following
1923 <td>\ref api-tir-fc-int-prop-size "Field value range"
1924 <td>[−2<sup>63</sup>, 2<sup>63</sup> − 1]
1926 <td>\ref api-tir-fc-int-prop-base "Preferred display base"
1927 <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
1929 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
1930 <td>Empty \bt_map_val
1933 @param[in] trace_class
1934 Trace class from which to create a signed integer field class.
1937 New signed integer field class reference, or \c NULL on memory error.
1939 @bt_pre_not_null{trace_class}
1941 extern bt_field_class
*bt_field_class_integer_signed_create(
1942 bt_trace_class
*trace_class
);
1947 @name Single-precision real field class
1953 Creates a single-precision \bt_real_fc from the trace class
1956 On success, the returned single-precision real field class has the
1957 following property value:
1964 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
1965 <td>Empty \bt_map_val
1968 @param[in] trace_class
1969 Trace class from which to create a single-preicision real
1973 New single-precision real field class reference, or \c NULL on
1976 @bt_pre_not_null{trace_class}
1978 extern bt_field_class
*bt_field_class_real_single_precision_create(
1979 bt_trace_class
*trace_class
);
1984 @name Double-precision real field class
1990 Creates a double-precision \bt_real_fc from the trace class
1993 On success, the returned double-precision real field class has the
1994 following property value:
2001 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2002 <td>Empty \bt_map_val
2005 @param[in] trace_class
2006 Trace class from which to create a double-preicision real
2010 New double-precision real field class reference, or \c NULL on
2013 @bt_pre_not_null{trace_class}
2015 extern bt_field_class
*bt_field_class_real_double_precision_create(
2016 bt_trace_class
*trace_class
);
2021 @name Enumeration field class
2027 Array of \c const \bt_enum_fc labels.
2029 Returned by bt_field_class_enumeration_unsigned_get_mapping_labels_for_value()
2030 and bt_field_class_enumeration_signed_get_mapping_labels_for_value().
2032 typedef char const * const *bt_field_class_enumeration_mapping_label_array
;
2037 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value()
2039 bt_field_class_enumeration_signed_get_mapping_labels_for_value().
2041 typedef enum bt_field_class_enumeration_get_mapping_labels_for_value_status
{
2046 BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2052 BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2053 } bt_field_class_enumeration_get_mapping_labels_for_value_status
;
2057 Status codes for bt_field_class_enumeration_unsigned_add_mapping()
2058 and bt_field_class_enumeration_signed_add_mapping().
2060 typedef enum bt_field_class_enumeration_add_mapping_status
{
2065 BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2071 BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2072 } bt_field_class_enumeration_add_mapping_status
;
2077 @name Enumeration field class mapping
2082 @typedef struct bt_field_class_enumeration_mapping bt_field_class_enumeration_mapping;
2085 Enumeration field class mapping.
2090 Returns the number of mappings contained in the \bt_enum_fc
2093 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2095 @param[in] field_class
2096 Enumeration field class of which to get the number of contained
2100 Number of contained mappings in \bt_p{field_class}.
2102 @bt_pre_not_null{field_class}
2103 @bt_pre_is_enum_fc{field_class}
2105 extern uint64_t bt_field_class_enumeration_get_mapping_count(
2106 const bt_field_class
*field_class
);
2110 Returns the label of the \bt_enum_fc mapping \bt_p{mapping}.
2112 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2115 Enumeration field class mapping of which to get the label.
2119 Label of \bt_p{mapping}.
2121 The returned pointer remains valid as long as \bt_p{mapping} exists.
2124 @bt_pre_not_null{mapping}
2126 extern const char *bt_field_class_enumeration_mapping_get_label(
2127 const bt_field_class_enumeration_mapping
*mapping
);
2132 @name Unsigned enumeration field class
2138 Creates an \bt_uenum_fc from the trace class \bt_p{trace_class}.
2140 On success, the returned unsigned enumeration field class has the
2141 following property values:
2148 <td>\ref api-tir-fc-int-prop-size "Field value range"
2149 <td>[0, 2<sup>64</sup> − 1]
2151 <td>\ref api-tir-fc-int-prop-base "Preferred display base"
2152 <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
2154 <td>\ref api-tir-fc-enum-prop-mappings "Mappings"
2157 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2158 <td>Empty \bt_map_val
2161 @param[in] trace_class
2162 Trace class from which to create an unsigned enumeration field
2166 New unsigned enumeration field class reference, or \c NULL on memory
2169 @bt_pre_not_null{trace_class}
2171 extern bt_field_class
*bt_field_class_enumeration_unsigned_create(
2172 bt_trace_class
*trace_class
);
2176 Adds a mapping to the \bt_uenum_fc \bt_p{field_class} having the
2177 label \bt_p{label} and the unsigned integer ranges \bt_p{ranges}.
2179 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2181 @param[in] field_class
2182 Unsigned enumeration field class to which to add a mapping having
2183 the label \bt_p{label} and the integer ranges \bt_p{ranges}.
2185 Label of the mapping to add to \bt_p{field_class} (copied).
2187 Unsigned integer ranges of the mapping to add to
2190 @retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK
2192 @retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR
2195 @bt_pre_not_null{field_class}
2196 @bt_pre_hot{field_class}
2197 @bt_pre_is_uenum_fc{field_class}
2198 @bt_pre_not_null{label}
2200 \bt_p{field_class} has no mapping with the label \bt_p{label}.
2201 @bt_pre_not_null{ranges}
2203 \bt_p{ranges} contains one or more unsigned integer ranges.
2205 extern bt_field_class_enumeration_add_mapping_status
2206 bt_field_class_enumeration_unsigned_add_mapping(
2207 bt_field_class
*field_class
, const char *label
,
2208 const bt_integer_range_set_unsigned
*ranges
);
2212 Borrows the mapping at index \bt_p{index} from the
2213 \bt_uenum_fc \bt_p{field_class}.
2215 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2217 @param[in] field_class
2218 Unsigned enumeration field class from which to borrow the mapping at
2221 Index of the mapping to borrow from \bt_p{field_class}.
2225 \em Borrowed reference of the mapping of
2226 \bt_p{field_class} at index \bt_p{index}.
2228 The returned pointer remains valid as long as \bt_p{field_class}
2232 @bt_pre_not_null{field_class}
2233 @bt_pre_is_uenum_fc{field_class}
2235 \bt_p{index} is less than the number of mappings in
2236 \bt_p{field_class} (as returned by
2237 bt_field_class_enumeration_get_mapping_count()).
2239 @sa bt_field_class_enumeration_get_mapping_count() —
2240 Returns the number of mappings contained in an
2241 enumeration field class.
2243 extern const bt_field_class_enumeration_unsigned_mapping
*
2244 bt_field_class_enumeration_unsigned_borrow_mapping_by_index_const(
2245 const bt_field_class
*field_class
, uint64_t index
);
2249 Borrows the mapping having the label \bt_p{label} from the
2250 \bt_uenum_fc \bt_p{field_class}.
2252 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2254 If there's no mapping having the label \bt_p{label} in
2255 \bt_p{field_class}, this function returns \c NULL.
2257 @param[in] field_class
2258 Unsigned enumeration field class from which to borrow the mapping
2259 having the label \bt_p{label}.
2261 Label of the mapping to borrow from \bt_p{field_class}.
2265 \em Borrowed reference of the mapping of
2266 \bt_p{field_class} having the label \bt_p{label}, or \c NULL
2269 The returned pointer remains valid as long as \bt_p{field_class}
2273 @bt_pre_not_null{field_class}
2274 @bt_pre_is_uenum_fc{field_class}
2275 @bt_pre_not_null{label}
2277 extern const bt_field_class_enumeration_unsigned_mapping
*
2278 bt_field_class_enumeration_unsigned_borrow_mapping_by_label_const(
2279 const bt_field_class
*field_class
, const char *label
);
2283 Returns an array of all the labels of the mappings of the
2284 \bt_uenum_fc \bt_p{field_class} of which the \bt_p_uint_rg contain
2285 the integral value \bt_p{value}.
2287 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2289 This function sets \bt_p{*labels} to the resulting array and
2290 \bt_p{*count} to the number of labels in \bt_p{*labels}.
2292 On success, if there's no mapping ranges containing the value
2293 \bt_p{value}, \bt_p{*count} is 0.
2295 @param[in] field_class
2296 Unsigned enumeration field class from which to get the labels of the
2297 mappings of which the ranges contain \bt_p{value}.
2299 Value for which to get the mapped labels in \bt_p{field_class}.
2302 <strong>On success</strong>, \bt_p{*labels}
2303 is an array of labels of the mappings of \bt_p{field_class}
2304 containing \bt_p{value}.
2306 The number of labels in \bt_p{*labels} is \bt_p{*count}.
2308 The array is owned by \bt_p{field_class} and remains valid as long
2311 - \bt_p{field_class} is not modified.
2312 - You don't call this function again with \bt_p{field_class}.
2315 <strong>On success</strong>, \bt_p{*count} is the number of labels
2316 in \bt_p{*labels} (can be 0).
2318 @retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK
2320 @retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR
2323 @bt_pre_not_null{field_class}
2324 @bt_pre_is_uenum_fc{field_class}
2325 @bt_pre_not_null{labels}
2326 @bt_pre_not_null{count}
2328 extern bt_field_class_enumeration_get_mapping_labels_for_value_status
2329 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value(
2330 const bt_field_class
*field_class
, uint64_t value
,
2331 bt_field_class_enumeration_mapping_label_array
*labels
,
2337 @name Unsigned enumeration field class mapping
2342 @typedef struct bt_field_class_enumeration_unsigned_mapping bt_field_class_enumeration_unsigned_mapping;
2345 Unsigned enumeration field class mapping.
2350 Borrows the \bt_p_uint_rg from the \bt_uenum_fc mapping
2353 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2356 Unsigned enumeration field class mapping from which to borrow the
2357 unsigned integer ranges.
2360 Unsigned integer ranges of \bt_p{mapping}.
2362 @bt_pre_not_null{mapping}
2364 extern const bt_integer_range_set_unsigned
*
2365 bt_field_class_enumeration_unsigned_mapping_borrow_ranges_const(
2366 const bt_field_class_enumeration_unsigned_mapping
*mapping
);
2370 \ref api-fund-c-typing "Upcasts" the \bt_uenum_fc mapping
2371 \bt_p{mapping} to the common #bt_field_class_enumeration_mapping
2374 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2378 Unsigned enumeration field class mapping to upcast.
2384 \bt_p{mapping} as a common enumeration field class mapping.
2387 const bt_field_class_enumeration_mapping
*
2388 bt_field_class_enumeration_unsigned_mapping_as_mapping_const(
2389 const bt_field_class_enumeration_unsigned_mapping
*mapping
)
2391 return __BT_UPCAST_CONST(bt_field_class_enumeration_mapping
, mapping
);
2397 @name Signed enumeration field class
2403 Creates a \bt_senum_fc from the trace class \bt_p{trace_class}.
2405 On success, the returned signed enumeration field class has the
2406 following property values:
2413 <td>\ref api-tir-fc-int-prop-size "Field value range"
2414 <td>[−2<sup>63</sup>, 2<sup>63</sup> − 1]
2416 <td>\ref api-tir-fc-int-prop-base "Preferred display base"
2417 <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
2419 <td>\ref api-tir-fc-enum-prop-mappings "Mappings"
2422 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2423 <td>Empty \bt_map_val
2426 @param[in] trace_class
2427 Trace class from which to create a signed enumeration field
2431 New signed enumeration field class reference, or \c NULL on memory
2434 @bt_pre_not_null{trace_class}
2436 extern bt_field_class
*bt_field_class_enumeration_signed_create(
2437 bt_trace_class
*trace_class
);
2441 Adds a mapping to the \bt_senum_fc \bt_p{field_class} having the
2442 label \bt_p{label} and the \bt_p_sint_rg \bt_p{ranges}.
2444 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2446 @param[in] field_class
2447 Signed enumeration field class to which to add a mapping having
2448 the label \bt_p{label} and the integer ranges \bt_p{ranges}.
2450 Label of the mapping to add to \bt_p{field_class} (copied).
2452 Signed integer ranges of the mapping to add to
2455 @retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK
2457 @retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR
2460 @bt_pre_not_null{field_class}
2461 @bt_pre_hot{field_class}
2462 @bt_pre_is_senum_fc{field_class}
2463 @bt_pre_not_null{label}
2465 \bt_p{field_class} has no mapping with the label \bt_p{label}.
2466 @bt_pre_not_null{ranges}
2468 \bt_p{ranges} contains one or more signed integer ranges.
2470 extern bt_field_class_enumeration_add_mapping_status
2471 bt_field_class_enumeration_signed_add_mapping(
2472 bt_field_class
*field_class
, const char *label
,
2473 const bt_integer_range_set_signed
*ranges
);
2477 Borrows the mapping at index \bt_p{index} from the
2478 \bt_senum_fc \bt_p{field_class}.
2480 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2482 @param[in] field_class
2483 Signed enumeration field class from which to borrow the mapping at
2486 Index of the mapping to borrow from \bt_p{field_class}.
2490 \em Borrowed reference of the mapping of
2491 \bt_p{field_class} at index \bt_p{index}.
2493 The returned pointer remains valid as long as \bt_p{field_class}
2497 @bt_pre_not_null{field_class}
2498 @bt_pre_is_senum_fc{field_class}
2500 \bt_p{index} is less than the number of mappings in
2501 \bt_p{field_class} (as returned by
2502 bt_field_class_enumeration_get_mapping_count()).
2504 @sa bt_field_class_enumeration_get_mapping_count() —
2505 Returns the number of mappings contained in an
2506 enumeration field class.
2508 extern const bt_field_class_enumeration_signed_mapping
*
2509 bt_field_class_enumeration_signed_borrow_mapping_by_index_const(
2510 const bt_field_class
*field_class
, uint64_t index
);
2514 Borrows the mapping having the label \bt_p{label} from the
2515 \bt_senum_fc \bt_p{field_class}.
2517 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2519 If there's no mapping having the label \bt_p{label} in
2520 \bt_p{field_class}, this function returns \c NULL.
2522 @param[in] field_class
2523 Signed enumeration field class from which to borrow the mapping
2524 having the label \bt_p{label}.
2526 Label of the mapping to borrow from \bt_p{field_class}.
2530 \em Borrowed reference of the mapping of
2531 \bt_p{field_class} having the label \bt_p{label}, or \c NULL
2534 The returned pointer remains valid as long as \bt_p{field_class}
2538 @bt_pre_not_null{field_class}
2539 @bt_pre_is_senum_fc{field_class}
2540 @bt_pre_not_null{label}
2542 extern const bt_field_class_enumeration_signed_mapping
*
2543 bt_field_class_enumeration_signed_borrow_mapping_by_label_const(
2544 const bt_field_class
*field_class
, const char *label
);
2548 Returns an array of all the labels of the mappings of the
2549 \bt_senum_fc \bt_p{field_class} of which the \bt_p_sint_rg contain
2550 the integral value \bt_p{value}.
2552 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2554 This function sets \bt_p{*labels} to the resulting array and
2555 \bt_p{*count} to the number of labels in \bt_p{*labels}.
2557 On success, if there's no mapping ranges containing the value
2558 \bt_p{value}, \bt_p{*count} is 0.
2560 @param[in] field_class
2561 Signed enumeration field class from which to get the labels of the
2562 mappings of which the ranges contain \bt_p{value}.
2564 Value for which to get the mapped labels in \bt_p{field_class}.
2567 <strong>On success</strong>, \bt_p{*labels}
2568 is an array of labels of the mappings of \bt_p{field_class}
2569 containing \bt_p{value}.
2571 The number of labels in \bt_p{*labels} is \bt_p{*count}.
2573 The array is owned by \bt_p{field_class} and remains valid as long
2576 - \bt_p{field_class} is not modified.
2577 - You don't call this function again with \bt_p{field_class}.
2580 <strong>On success</strong>, \bt_p{*count} is the number of labels
2581 in \bt_p{*labels} (can be 0).
2583 @retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK
2585 @retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR
2588 @bt_pre_not_null{field_class}
2589 @bt_pre_is_senum_fc{field_class}
2590 @bt_pre_not_null{labels}
2591 @bt_pre_not_null{count}
2593 extern bt_field_class_enumeration_get_mapping_labels_for_value_status
2594 bt_field_class_enumeration_signed_get_mapping_labels_for_value(
2595 const bt_field_class
*field_class
, int64_t value
,
2596 bt_field_class_enumeration_mapping_label_array
*labels
,
2602 @name Signed enumeration field class mapping
2607 @typedef struct bt_field_class_enumeration_signed_mapping bt_field_class_enumeration_signed_mapping;
2610 Signed enumeration field class mapping.
2615 Borrows the \bt_p_sint_rg from the \bt_senum_fc mapping
2618 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2621 Signed enumeration field class mapping from which to borrow the
2622 signed integer ranges.
2625 Signed integer ranges of \bt_p{mapping}.
2627 @bt_pre_not_null{mapping}
2629 extern const bt_integer_range_set_signed
*
2630 bt_field_class_enumeration_signed_mapping_borrow_ranges_const(
2631 const bt_field_class_enumeration_signed_mapping
*mapping
);
2635 \ref api-fund-c-typing "Upcasts" the \bt_senum_fc mapping
2636 \bt_p{mapping} to the common #bt_field_class_enumeration_mapping
2639 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2643 Signed enumeration field class mapping to upcast.
2649 \bt_p{mapping} as a common enumeration field class mapping.
2652 const bt_field_class_enumeration_mapping
*
2653 bt_field_class_enumeration_signed_mapping_as_mapping_const(
2654 const bt_field_class_enumeration_signed_mapping
*mapping
)
2656 return __BT_UPCAST_CONST(bt_field_class_enumeration_mapping
, mapping
);
2662 @name String field class
2668 Creates a \bt_string_fc from the trace class \bt_p{trace_class}.
2670 On success, the returned string field class has the following property
2678 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2679 <td>Empty \bt_map_val
2682 @param[in] trace_class
2683 Trace class from which to create a string field class.
2686 New string field class reference, or \c NULL on memory error.
2688 @bt_pre_not_null{trace_class}
2690 extern bt_field_class
*bt_field_class_string_create(
2691 bt_trace_class
*trace_class
);
2696 @name Array field class
2702 Borrows the element field class from the \bt_array_fc
2705 See the \ref api-tir-fc-array-prop-elem-fc "element field class"
2708 @param[in] field_class
2709 Array field class from which to borrow the element field class.
2712 Element field class of \bt_p{field_class}.
2714 @bt_pre_not_null{field_class}
2715 @bt_pre_is_array_fc{field_class}
2717 @sa bt_field_class_array_borrow_element_field_class_const() —
2718 \c const version of this function.
2720 extern bt_field_class
*bt_field_class_array_borrow_element_field_class(
2721 bt_field_class
*field_class
);
2725 Borrows the element field class from the \bt_array_fc
2726 \bt_p{field_class} (\c const version).
2728 See bt_field_class_array_borrow_element_field_class().
2730 extern const bt_field_class
*
2731 bt_field_class_array_borrow_element_field_class_const(
2732 const bt_field_class
*field_class
);
2737 @name Static array field class
2743 Creates a \bt_sarray_fc having the element field class
2744 \bt_p{element_field_class} and the length \bt_p{length} from the
2745 trace class \bt_p{trace_class}.
2747 On success, the returned static array field class has the following
2755 <td>\ref api-tir-fc-array-prop-elem-fc "Element field class"
2756 <td>\bt_p{element_field_class}
2758 <td>\ref api-tir-fc-sarray-prop-len "Length"
2761 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2762 <td>Empty \bt_map_val
2765 @param[in] trace_class
2766 Trace class from which to create a static array field class.
2767 @param[in] element_field_class
2768 Class of the element fields of the instances of the static array
2769 field class to create.
2771 Length of the instances of the static array field class to create.
2774 New static array field class reference, or \c NULL on memory error.
2776 @bt_pre_not_null{trace_class}
2777 @bt_pre_not_null{element_field_class}
2778 bt_pre_fc_not_in_tc{element_field_class}
2780 @bt_post_success_frozen{element_field_class}
2782 extern bt_field_class
*bt_field_class_array_static_create(
2783 bt_trace_class
*trace_class
,
2784 bt_field_class
*element_field_class
, uint64_t length
);
2788 Returns the length of the \bt_sarray_fc \bt_p{field_class}.
2790 See the \ref api-tir-fc-sarray-prop-len "length" property.
2792 @param[in] field_class
2793 Static array field class of which to get the length.
2796 Length of \bt_p{field_class}.
2798 @bt_pre_not_null{field_class}
2799 @bt_pre_is_sarray_fc{field_class}
2801 extern uint64_t bt_field_class_array_static_get_length(
2802 const bt_field_class
*field_class
);
2807 @name Dynamic array field class
2813 Creates a \bt_darray_fc having the element field class
2814 \bt_p{element_field_class} from the trace class \bt_p{trace_class}.
2816 If \bt_p{length_field_class} is not \c NULL, then the created dynamic
2817 array field class has a linked length field class.
2819 \ref api-tir-fc-link "Field classes with links to other field classes"
2822 On success, the returned dynamic array field class has the following
2830 <td>\ref api-tir-fc-array-prop-elem-fc "Element field class"
2831 <td>\bt_p{element_field_class}
2833 <td>\ref api-tir-fc-darray-prop-len-fp "Length field path"
2835 \em None (if \bt_p{length_field_class} is not \c NULL, this
2836 property becomes available when the returned field class becomes
2837 part of an \bt_ev_cls or of a \bt_stream_cls)
2839 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2840 <td>Empty \bt_map_val
2843 @param[in] trace_class
2844 Trace class from which to create a dynamic array field class.
2845 @param[in] element_field_class
2846 Class of the element fields of the instances of the dynamic array
2847 field class to create.
2848 @param[in] length_field_class
2850 Linked length field class of the dynamic array field class to
2857 New dynamic array field class reference, or \c NULL on memory error.
2859 @bt_pre_not_null{trace_class}
2860 @bt_pre_not_null{element_field_class}
2861 @bt_pre_fc_not_in_tc{element_field_class}
2863 <strong>If \bt_p{length_field_class} is not \c NULL</strong>,
2864 \bt_p{length_field_class} is an \bt_uint_fc.
2866 @bt_post_success_frozen{element_field_class}
2867 @bt_post_success_frozen{length_field_class}
2869 extern bt_field_class
*bt_field_class_array_dynamic_create(
2870 bt_trace_class
*trace_class
,
2871 bt_field_class
*element_field_class
,
2872 bt_field_class
*length_field_class
);
2877 @name Dynamic array field class with length field
2883 Borrows the length field path from the \bt_darray_fc (with a length
2884 field) \bt_p{field_class}.
2886 See the \ref api-tir-fc-darray-prop-len-fp "length field path" property.
2888 This property is only available when a \bt_struct_fc containing
2889 (recursively) \bt_p{field_class} is passed to one of:
2891 - bt_stream_class_set_packet_context_field_class()
2892 - bt_stream_class_set_event_common_context_field_class()
2893 - bt_event_class_set_specific_context_field_class()
2894 - bt_event_class_set_payload_field_class()
2896 In the meantime, this function returns \c NULL.
2898 @param[in] field_class
2899 Dynamic array field class from which to borrow the length
2903 Length field path of \bt_p{field_class}.
2905 @bt_pre_not_null{field_class}
2906 @bt_pre_is_darray_wl_fc{field_class}
2908 extern const bt_field_path
*
2909 bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const(
2910 const bt_field_class
*field_class
);
2915 @name Structure field class
2921 Creates a \bt_struct_fc from the trace class \bt_p{trace_class}.
2923 On success, the returned structure field class has the following
2931 <td>\ref api-tir-fc-struct-prop-members "Members"
2934 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2935 <td>Empty \bt_map_val
2938 @param[in] trace_class
2939 Trace class from which to create a structure field class.
2942 New structure field class reference, or \c NULL on memory error.
2944 @bt_pre_not_null{trace_class}
2946 extern bt_field_class
*bt_field_class_structure_create(
2947 bt_trace_class
*trace_class
);
2951 Status codes for bt_field_class_structure_append_member().
2953 typedef enum bt_field_class_structure_append_member_status
{
2958 BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2964 BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2965 } bt_field_class_structure_append_member_status
;
2969 Appends a member to the \bt_struct_fc \bt_p{field_class} having the
2970 name \bt_p{name} and the field class \bt_p{member_field_class}.
2972 See the \ref api-tir-fc-struct-prop-members "members" property.
2974 @param[in] field_class
2975 Structure field class to which to append a member having
2976 the name \bt_p{name} and the field class \bt_p{member_field_class}.
2978 Name of the member to append to \bt_p{field_class} (copied).
2979 @param[in] member_field_class
2980 Field class of the member to append to \bt_p{field_class}.
2982 @retval #BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_OK
2984 @retval #BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_MEMORY_ERROR
2987 @bt_pre_not_null{field_class}
2988 @bt_pre_hot{field_class}
2989 @bt_pre_is_struct_fc{field_class}
2991 \bt_p{field_class} has no member with the name \bt_p{name}.
2992 @bt_pre_not_null{name}
2993 @bt_pre_not_null{member_field_class}
2994 @bt_pre_fc_not_in_tc{member_field_class}
2996 @bt_post_success_frozen{member_field_class}
2998 extern bt_field_class_structure_append_member_status
2999 bt_field_class_structure_append_member(
3000 bt_field_class
*field_class
,
3001 const char *name
, bt_field_class
*member_field_class
);
3005 Returns the number of members contained in the \bt_struct_fc
3008 See the \ref api-tir-fc-struct-prop-members "members" property.
3010 @param[in] field_class
3011 Structure field class of which to get the number of contained
3015 Number of contained members in \bt_p{field_class}.
3017 @bt_pre_not_null{field_class}
3018 @bt_pre_is_struct_fc{field_class}
3020 extern uint64_t bt_field_class_structure_get_member_count(
3021 const bt_field_class
*field_class
);
3025 Borrows the member at index \bt_p{index} from the
3026 \bt_struct_fc \bt_p{field_class}.
3028 See the \ref api-tir-fc-struct-prop-members "members" property.
3030 @param[in] field_class
3031 Structure field class from which to borrow the member at
3034 Index of the member to borrow from \bt_p{field_class}.
3038 \em Borrowed reference of the member of
3039 \bt_p{field_class} at index \bt_p{index}.
3041 The returned pointer remains valid as long as \bt_p{field_class}
3045 @bt_pre_not_null{field_class}
3046 @bt_pre_is_struct_fc{field_class}
3048 \bt_p{index} is less than the number of members in
3049 \bt_p{field_class} (as returned by
3050 bt_field_class_structure_get_member_count()).
3052 @sa bt_field_class_structure_get_member_count() —
3053 Returns the number of members contained in a structure field class.
3054 @sa bt_field_class_structure_borrow_member_by_index_const() —
3055 \c const version of this function.
3057 extern bt_field_class_structure_member
*
3058 bt_field_class_structure_borrow_member_by_index(
3059 bt_field_class
*field_class
, uint64_t index
);
3063 Borrows the member at index \bt_p{index} from the
3064 \bt_struct_fc \bt_p{field_class} (\c const version).
3066 See bt_field_class_structure_borrow_member_by_index().
3068 extern const bt_field_class_structure_member
*
3069 bt_field_class_structure_borrow_member_by_index_const(
3070 const bt_field_class
*field_class
, uint64_t index
);
3074 Borrows the member having the name \bt_p{name} from the
3075 \bt_struct_fc \bt_p{field_class}.
3077 See the \ref api-tir-fc-struct-prop-members "members" property.
3079 If there's no member having the name \bt_p{name} in
3080 \bt_p{field_class}, this function returns \c NULL.
3082 @param[in] field_class
3083 Structure field class from which to borrow the member having the
3086 Name of the member to borrow from \bt_p{field_class}.
3090 \em Borrowed reference of the member of
3091 \bt_p{field_class} having the name \bt_p{name}, or \c NULL
3094 The returned pointer remains valid as long as \bt_p{field_class}
3098 @bt_pre_not_null{field_class}
3099 @bt_pre_is_struct_fc{field_class}
3100 @bt_pre_not_null{name}
3102 @sa bt_field_class_structure_borrow_member_by_name_const() —
3103 \c const version of this function.
3105 extern bt_field_class_structure_member
*
3106 bt_field_class_structure_borrow_member_by_name(
3107 bt_field_class
*field_class
, const char *name
);
3111 Borrows the member having the name \bt_p{name} from the
3112 \bt_struct_fc \bt_p{field_class} (\c const version).
3114 See bt_field_class_structure_borrow_member_by_name().
3116 extern const bt_field_class_structure_member
*
3117 bt_field_class_structure_borrow_member_by_name_const(
3118 const bt_field_class
*field_class
, const char *name
);
3123 @name Structure field class member
3128 @typedef struct bt_field_class_structure_member bt_field_class_structure_member;
3131 Structure field class member.
3136 Returns the name of the \bt_struct_fc member \bt_p{member}.
3138 See the \ref api-tir-fc-struct-prop-members "members" property.
3141 Structure field class member of which to get the name.
3145 Name of \bt_p{member}.
3147 The returned pointer remains valid as long as \bt_p{member} exists.
3150 @bt_pre_not_null{member}
3152 extern const char *bt_field_class_structure_member_get_name(
3153 const bt_field_class_structure_member
*member
);
3157 Borrows the field class from the \bt_struct_fc member
3160 See the \ref api-tir-fc-struct-prop-members "members" property.
3163 Structure field class member from which to borrow the field class.
3166 Field class of \bt_p{member}.
3168 @bt_pre_not_null{member}
3170 @sa bt_field_class_structure_member_borrow_field_class_const() —
3171 \c const version of this function.
3173 extern bt_field_class
*
3174 bt_field_class_structure_member_borrow_field_class(
3175 bt_field_class_structure_member
*member
);
3179 Borrows the field class from the \bt_struct_fc member
3180 \bt_p{member} (\c const version).
3182 See bt_field_class_structure_member_borrow_field_class().
3184 extern const bt_field_class
*
3185 bt_field_class_structure_member_borrow_field_class_const(
3186 const bt_field_class_structure_member
*member
);
3190 Sets the user attributes of the \bt_struct_fc member \bt_p{member}
3191 to \bt_p{user_attributes}.
3193 See the \ref api-tir-fc-struct-prop-members "members" property.
3196 When you append a member to a structure field class with
3197 bt_field_class_structure_append_member(), the member's
3198 initial user attributes is an empty \bt_map_val. Therefore you can
3200 bt_field_class_structure_member_borrow_user_attributes() and fill it
3201 directly instead of setting a new one with this function.
3204 Structure field class member of which to set the user attributes to
3205 \bt_p{user_attributes}.
3206 @param[in] user_attributes
3207 New user attributes of \bt_p{member}.
3209 @bt_pre_not_null{member}
3211 @bt_pre_not_null{user_attributes}
3212 @bt_pre_is_map_val{user_attributes}
3214 @sa bt_field_class_structure_member_borrow_user_attributes() —
3215 Borrows the user attributes of a structure field class member.
3217 extern void bt_field_class_structure_member_set_user_attributes(
3218 bt_field_class_structure_member
*member
,
3219 const bt_value
*user_attributes
);
3223 Borrows the user attributes of the \bt_struct_fc member
3226 See the \ref api-tir-fc-struct-prop-members "members" property.
3229 When you append a member to a structure field class with
3230 bt_field_class_structure_append_member(), the member's
3231 initial user attributes is an empty \bt_map_val.
3234 Structure field class member from which to borrow the user
3238 User attributes of \bt_p{member} (a \bt_map_val).
3240 @bt_pre_not_null{member}
3242 @sa bt_field_class_structure_member_set_user_attributes() —
3243 Sets the user attributes of a structure field class member.
3244 @sa bt_field_class_structure_member_borrow_user_attributes_const() —
3245 \c const version of this function.
3248 bt_field_class_structure_member_borrow_user_attributes(
3249 bt_field_class_structure_member
*member
);
3253 Borrows the user attributes of the \bt_struct_fc member
3254 \bt_p{member} (\c const version).
3256 See bt_field_class_structure_member_borrow_user_attributes().
3258 extern const bt_value
*
3259 bt_field_class_structure_member_borrow_user_attributes_const(
3260 const bt_field_class_structure_member
*member
);
3265 @name Option field class
3271 Borrows the optional field class from the \bt_opt_fc
3274 See the \ref api-tir-fc-opt-prop-fc "optional field class" property.
3276 @param[in] field_class
3277 Option field class from which to borrow the optional field class.
3280 Optional field class of \bt_p{field_class}.
3282 @bt_pre_not_null{field_class}
3283 @bt_pre_is_opt_fc{field_class}
3285 @sa bt_field_class_option_borrow_field_class_const() —
3286 \c const version of this function.
3288 extern bt_field_class
*bt_field_class_option_borrow_field_class(
3289 bt_field_class
*field_class
);
3293 Borrows the optional field class from the \bt_opt_fc
3294 \bt_p{field_class} (\c const version).
3296 See bt_field_class_option_borrow_field_class().
3298 extern const bt_field_class
*
3299 bt_field_class_option_borrow_field_class_const(
3300 const bt_field_class
*field_class
);
3305 @name Option field class without a selector field
3311 Creates an \bt_opt_fc (without a selector field) having the optional
3312 field class \bt_p{optional_field_class} from the trace class
3315 On success, the returned option field class has the following property
3323 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
3324 <td>\bt_p{optional_field_class}
3326 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3327 <td>Empty \bt_map_val
3330 @param[in] trace_class
3331 Trace class from which to create an option field class.
3332 @param[in] optional_field_class
3333 Class of the optional fields of the instances of the option field
3337 New option field class reference, or \c NULL on memory error.
3339 @bt_pre_not_null{trace_class}
3340 @bt_pre_not_null{optional_field_class}
3341 @bt_pre_fc_not_in_tc{optional_field_class}
3343 @bt_post_success_frozen{optional_field_class}
3345 extern bt_field_class
*bt_field_class_option_without_selector_create(
3346 bt_trace_class
*trace_class
,
3347 bt_field_class
*optional_field_class
);
3352 @name Option field class with a selector field
3358 Borrows the selector field path from the \bt_opt_fc (with a selector
3359 field) \bt_p{field_class}.
3361 See the \ref api-tir-fc-opt-prop-sel-fp "selector field path" property.
3363 This property is only available when a \bt_struct_fc containing
3364 (recursively) \bt_p{field_class} is passed to one of:
3366 - bt_stream_class_set_packet_context_field_class()
3367 - bt_stream_class_set_event_common_context_field_class()
3368 - bt_event_class_set_specific_context_field_class()
3369 - bt_event_class_set_payload_field_class()
3371 In the meantime, this function returns \c NULL.
3373 @param[in] field_class
3374 Option field class from which to borrow the selector field path.
3377 Selector field path of \bt_p{field_class}.
3379 @bt_pre_not_null{field_class}
3380 @bt_pre_is_opt_ws_fc{field_class}
3382 extern const bt_field_path
*
3383 bt_field_class_option_with_selector_field_borrow_selector_field_path_const(
3384 const bt_field_class
*field_class
);
3389 @name Option field class with a boolean selector field
3395 Creates an \bt_opt_fc (with a boolean selector field) having the
3396 optional field class \bt_p{optional_field_class} from the trace
3397 class \bt_p{trace_class}.
3399 On success, the returned option field class has the following property
3407 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
3408 <td>\bt_p{optional_field_class}
3410 <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
3412 \em None (this property becomes available when the returned field
3413 class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
3415 <td>\ref api-tir-fc-opt-prop-sel-rev "Selector is reversed?"
3418 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3419 <td>Empty \bt_map_val
3422 @param[in] trace_class
3423 Trace class from which to create an option field class.
3424 @param[in] optional_field_class
3425 Class of the optional fields of the instances of the option field
3427 @param[in] selector_field_class
3428 Linked selector field class of the option field class to create.
3431 New option field class reference, or \c NULL on memory error.
3433 @bt_pre_not_null{trace_class}
3434 @bt_pre_not_null{optional_field_class}
3435 @bt_pre_fc_not_in_tc{optional_field_class}
3436 @bt_pre_not_null{selector_field_class}
3438 \bt_p{selector_field_class} is a \bt_bool_fc.
3440 @bt_post_success_frozen{optional_field_class}
3441 @bt_post_success_frozen{selector_field_class}
3443 extern bt_field_class
*bt_field_class_option_with_selector_field_bool_create(
3444 bt_trace_class
*trace_class
,
3445 bt_field_class
*optional_field_class
,
3446 bt_field_class
*selector_field_class
);
3450 Sets whether or not the selector of the \bt_opt_fc (with a boolean
3451 selector field) \bt_p{field_class} is reversed.
3453 See the \ref api-tir-fc-opt-prop-sel-rev "selector is reversed?"
3456 @param[in] field_class
3457 Option field class of which to set whether or not its selector
3459 @param[in] selector_is_reversed
3460 #BT_TRUE to make \bt_p{field_class} have a reversed selector.
3462 @bt_pre_not_null{field_class}
3463 @bt_pre_hot{field_class}
3464 @bt_pre_is_opt_wbs_fc{field_class}
3466 @sa bt_field_class_option_with_selector_field_bool_selector_is_reversed() —
3467 Returns whether or not the selector of an option field class (with
3468 a boolean selector field) is reversed.
3471 bt_field_class_option_with_selector_field_bool_set_selector_is_reversed(
3472 bt_field_class
*field_class
, bt_bool selector_is_reversed
);
3476 Returns whether or not the selector of the
3477 \bt_opt_fc (with a boolean selector field) is reversed.
3479 See the \ref api-tir-fc-opt-prop-sel-rev "selector is reversed?"
3482 @param[in] field_class
3483 Option field class of which to get whether or not its selector is
3487 #BT_TRUE if the selector of \bt_p{field_class} is reversed.
3489 @bt_pre_not_null{field_class}
3490 @bt_pre_is_opt_wbs_fc{field_class}
3492 @sa bt_field_class_option_with_selector_field_bool_set_selector_is_reversed() —
3493 Sets whether or not the selector of an option field class (with
3494 a boolean selector field) is reversed.
3497 bt_field_class_option_with_selector_field_bool_selector_is_reversed(
3498 const bt_field_class
*field_class
);
3503 @name Option field class with an unsigned integer selector field
3509 Creates an \bt_opt_fc (with an unsigned integer selector field)
3510 having the optional field class \bt_p{optional_field_class} from the
3511 trace class \bt_p{trace_class}.
3513 On success, the returned option field class has the following property
3521 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
3522 <td>\bt_p{optional_field_class}
3524 <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
3526 \em None (this property becomes available when the returned field
3527 class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
3529 <td>\ref api-tir-fc-opt-prop-uint-rs "Selector's unsigned integer ranges"
3532 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3533 <td>Empty \bt_map_val
3536 @param[in] trace_class
3537 Trace class from which to create an option field class.
3538 @param[in] optional_field_class
3539 Class of the optional fields of the instances of the option field
3541 @param[in] selector_field_class
3542 Linked selector field class of the option field class to create.
3544 Selector's unsigned integer ranges of the option field class to
3548 New option field class reference, or \c NULL on memory error.
3550 @bt_pre_not_null{trace_class}
3551 @bt_pre_not_null{optional_field_class}
3552 @bt_pre_fc_not_in_tc{optional_field_class}
3553 @bt_pre_not_null{selector_field_class}
3555 \bt_p{selector_field_class} is a \bt_uint_fc.
3556 @bt_pre_not_null{ranges}
3558 \bt_p{ranges} contains one or more \bt_p_uint_rg.
3560 @bt_post_success_frozen{optional_field_class}
3561 @bt_post_success_frozen{selector_field_class}
3562 @bt_post_success_frozen{ranges}
3564 extern bt_field_class
*
3565 bt_field_class_option_with_selector_field_integer_unsigned_create(
3566 bt_trace_class
*trace_class
,
3567 bt_field_class
*optional_field_class
,
3568 bt_field_class
*selector_field_class
,
3569 const bt_integer_range_set_unsigned
*ranges
);
3573 Borrows the \bt_p_uint_rg from the \bt_opt_fc (with an unsigned
3574 integer selector field) \bt_p{field_class}.
3577 \ref api-tir-fc-opt-prop-uint-rs "selector's unsigned integer ranges"
3580 @param[in] field_class
3581 Option field class from which to borrow the unsigned integer ranges.
3584 Unsigned integer ranges of \bt_p{field_class}.
3586 @bt_pre_not_null{field_class}
3587 @bt_pre_is_opt_wuis_fc{field_class}
3589 extern const bt_integer_range_set_unsigned
*
3590 bt_field_class_option_with_selector_field_integer_unsigned_borrow_selector_ranges_const(
3591 const bt_field_class
*field_class
);
3596 @name Option field class with a signed integer selector field
3602 Creates an \bt_opt_fc (with a signed integer selector field)
3603 having the optional field class \bt_p{optional_field_class} from the
3604 trace class \bt_p{trace_class}.
3606 On success, the returned option field class has the following property
3614 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
3615 <td>\bt_p{optional_field_class}
3617 <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
3619 \em None (this property becomes available when the returned field
3620 class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
3622 <td>\ref api-tir-fc-opt-prop-sint-rs "Selector's signed integer ranges"
3625 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3626 <td>Empty \bt_map_val
3629 @param[in] trace_class
3630 Trace class from which to create an option field class.
3631 @param[in] optional_field_class
3632 Class of the optional fields of the instances of the option field
3634 @param[in] selector_field_class
3635 Linked selector field class of the option field class to create.
3637 Selector's signed integer ranges of the option field class to
3641 New option field class reference, or \c NULL on memory error.
3643 @bt_pre_not_null{trace_class}
3644 @bt_pre_not_null{optional_field_class}
3645 @bt_pre_fc_not_in_tc{optional_field_class}
3646 @bt_pre_not_null{selector_field_class}
3648 \bt_p{selector_field_class} is a \bt_uint_fc.
3649 @bt_pre_not_null{ranges}
3651 \bt_p{ranges} contains one or more \bt_p_uint_rg.
3653 @bt_post_success_frozen{optional_field_class}
3654 @bt_post_success_frozen{selector_field_class}
3655 @bt_post_success_frozen{ranges}
3657 extern bt_field_class
*
3658 bt_field_class_option_with_selector_field_integer_signed_create(
3659 bt_trace_class
*trace_class
,
3660 bt_field_class
*optional_field_class
,
3661 bt_field_class
*selector_field_class
,
3662 const bt_integer_range_set_signed
*ranges
);
3666 Borrows the \bt_p_sint_rg from the \bt_opt_fc (with a signed
3667 integer selector field) \bt_p{field_class}.
3670 \ref api-tir-fc-opt-prop-sint-rs "selector's signed integer ranges"
3673 @param[in] field_class
3674 Option field class from which to borrow the signed integer ranges.
3677 Signed integer ranges of \bt_p{field_class}.
3679 @bt_pre_not_null{field_class}
3680 @bt_pre_is_opt_wsis_fc{field_class}
3682 extern const bt_integer_range_set_signed
*
3683 bt_field_class_option_with_selector_field_integer_signed_borrow_selector_ranges_const(
3684 const bt_field_class
*field_class
);
3689 @name Variant field class
3695 Creates a \bt_var_fc from the trace class \bt_p{trace_class}.
3697 If \bt_p{selector_field_class} is not \c NULL, then the created variant
3698 field class has a linked selector field class.
3700 \ref api-tir-fc-link "Field classes with links to other field classes"
3703 On success, the returned variant field class has the following
3711 <td>\ref api-tir-fc-var-prop-sel-fp "Selector field path"
3713 \em None (if \bt_p{selector_field_class} is not \c NULL, this
3714 property becomes available when the returned field class becomes
3715 part of an \bt_ev_cls or of a \bt_stream_cls)
3717 <td>\ref api-tir-fc-var-prop-opts "Options"
3720 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3721 <td>Empty \bt_map_val
3724 @param[in] trace_class
3725 Trace class from which to create a variant field class.
3726 @param[in] selector_field_class
3728 Linked selector field class of the variant field class to create.
3734 New variant field class reference, or \c NULL on memory error.
3736 @bt_pre_not_null{trace_class}
3738 <strong>If \bt_p{selector_field_class} is not \c NULL</strong>,
3739 \bt_p{selector_field_class} is an \bt_int_fc.
3741 @bt_post_success_frozen{element_field_class}
3742 @bt_post_success_frozen{selector_field_class}
3744 extern bt_field_class
*bt_field_class_variant_create(
3745 bt_trace_class
*trace_class
,
3746 bt_field_class
*selector_field_class
);
3750 Returns the number of options contained in the \bt_var_fc
3753 See the \ref api-tir-fc-var-prop-opts "options" property.
3755 @param[in] field_class
3756 Variant field class of which to get the number of contained
3760 Number of contained options in \bt_p{field_class}.
3762 @bt_pre_not_null{field_class}
3763 @bt_pre_is_var_fc{field_class}
3765 extern uint64_t bt_field_class_variant_get_option_count(
3766 const bt_field_class
*field_class
);
3770 Borrows the option at index \bt_p{index} from the
3771 \bt_var_fc \bt_p{field_class}.
3773 See the \ref api-tir-fc-var-prop-opts "options" property.
3775 @param[in] field_class
3776 Variant field class from which to borrow the option at
3779 Index of the option to borrow from \bt_p{field_class}.
3783 \em Borrowed reference of the option of
3784 \bt_p{field_class} at index \bt_p{index}.
3786 The returned pointer remains valid as long as \bt_p{field_class}
3790 @bt_pre_not_null{field_class}
3791 @bt_pre_is_var_fc{field_class}
3793 \bt_p{index} is less than the number of options in
3794 \bt_p{field_class} (as returned by
3795 bt_field_class_variant_get_option_count()).
3797 @sa bt_field_class_variant_get_option_count() —
3798 Returns the number of options contained in a variant field class.
3799 @sa bt_field_class_variant_borrow_option_by_index_const() —
3800 \c const version of this function.
3802 extern bt_field_class_variant_option
*
3803 bt_field_class_variant_borrow_option_by_index(
3804 bt_field_class
*field_class
, uint64_t index
);
3808 Borrows the option at index \bt_p{index} from the
3809 \bt_var_fc \bt_p{field_class} (\c const version).
3811 See bt_field_class_variant_borrow_option_by_index().
3813 extern const bt_field_class_variant_option
*
3814 bt_field_class_variant_borrow_option_by_index_const(
3815 const bt_field_class
*field_class
, uint64_t index
);
3819 Borrows the option having the name \bt_p{name} from the
3820 \bt_var_fc \bt_p{field_class}.
3822 See the \ref api-tir-fc-var-prop-opts "options" property.
3824 If there's no option having the name \bt_p{name} in
3825 \bt_p{field_class}, this function returns \c NULL.
3827 @param[in] field_class
3828 Variant field class from which to borrow the option having the
3831 Name of the option to borrow from \bt_p{field_class}.
3835 \em Borrowed reference of the option of
3836 \bt_p{field_class} having the name \bt_p{name}, or \c NULL
3839 The returned pointer remains valid as long as \bt_p{field_class}
3843 @bt_pre_not_null{field_class}
3844 @bt_pre_is_var_fc{field_class}
3845 @bt_pre_not_null{name}
3847 @sa bt_field_class_variant_borrow_option_by_name_const() —
3848 \c const version of this function.
3850 extern bt_field_class_variant_option
*
3851 bt_field_class_variant_borrow_option_by_name(
3852 bt_field_class
*field_class
, const char *name
);
3856 Borrows the option having the name \bt_p{name} from the
3857 \bt_var_fc \bt_p{field_class} (\c const version).
3859 See bt_field_class_variant_borrow_option_by_name().
3861 extern const bt_field_class_variant_option
*
3862 bt_field_class_variant_borrow_option_by_name_const(
3863 const bt_field_class
*field_class
, const char *name
);
3868 @name Variant field class option
3873 @typedef struct bt_field_class_variant_option bt_field_class_variant_option;
3876 Variant field class option.
3881 Returns the name of the \bt_var_fc option \bt_p{option}.
3883 See the \ref api-tir-fc-var-prop-opts "options" property.
3886 Variant field class option of which to get the name.
3890 Name of \bt_p{option}.
3892 The returned pointer remains valid as long as \bt_p{option} exists.
3895 @bt_pre_not_null{option}
3897 extern const char *bt_field_class_variant_option_get_name(
3898 const bt_field_class_variant_option
*option
);
3902 Borrows the field class from the \bt_var_fc option
3905 See the \ref api-tir-fc-var-prop-opts "options" property.
3908 Variant field class option from which to borrow the field class.
3911 Field class of \bt_p{option}.
3913 @bt_pre_not_null{option}
3915 @sa bt_field_class_variant_option_borrow_field_class_const() —
3916 \c const version of this function.
3918 extern bt_field_class
*bt_field_class_variant_option_borrow_field_class(
3919 bt_field_class_variant_option
*option
);
3923 Borrows the field class from the \bt_var_fc option
3924 \bt_p{option} (\c const version).
3926 See bt_field_class_variant_option_borrow_field_class().
3928 extern const bt_field_class
*
3929 bt_field_class_variant_option_borrow_field_class_const(
3930 const bt_field_class_variant_option
*option
);
3934 Sets the user attributes of the \bt_var_fc option \bt_p{option}
3935 to \bt_p{user_attributes}.
3937 See the \ref api-tir-fc-var-prop-opts "options" property.
3940 When you append an option to a variant field class with
3941 bt_field_class_variant_without_selector_append_option(),
3942 bt_field_class_variant_with_selector_field_integer_unsigned_append_option(),
3944 bt_field_class_variant_with_selector_field_integer_signed_append_option(),
3945 the option's initial user attributes is an empty \bt_map_val.
3946 Therefore you can borrow it with
3947 bt_field_class_variant_option_borrow_user_attributes() and fill it
3948 directly instead of setting a new one with this function.
3951 Variant field class option of which to set the user attributes to
3952 \bt_p{user_attributes}.
3953 @param[in] user_attributes
3954 New user attributes of \bt_p{option}.
3956 @bt_pre_not_null{option}
3958 @bt_pre_not_null{user_attributes}
3959 @bt_pre_is_map_val{user_attributes}
3961 @sa bt_field_class_variant_option_borrow_user_attributes() —
3962 Borrows the user attributes of a variant field class option.
3964 extern void bt_field_class_variant_option_set_user_attributes(
3965 bt_field_class_variant_option
*option
,
3966 const bt_value
*user_attributes
);
3970 Borrows the user attributes of the \bt_var_fc option \bt_p{option}.
3972 See the \ref api-tir-fc-var-prop-opts "options" property.
3975 When you append an option to a variant field class with
3976 bt_field_class_variant_without_selector_append_option(),
3977 bt_field_class_variant_with_selector_field_integer_unsigned_append_option(),
3979 bt_field_class_variant_with_selector_field_integer_signed_append_option(),
3980 the option's initial user attributes is an empty \bt_map_val.
3983 Variant field class option from which to borrow the user
3987 User attributes of \bt_p{option} (a \bt_map_val).
3989 @bt_pre_not_null{option}
3991 @sa bt_field_class_variant_option_set_user_attributes() —
3992 Sets the user attributes of a variant field class option.
3993 @sa bt_field_class_variant_option_borrow_user_attributes_const() —
3994 \c const version of this function.
3996 extern bt_value
*bt_field_class_variant_option_borrow_user_attributes(
3997 bt_field_class_variant_option
*option
);
4001 Borrows the user attributes of the \bt_var_fc option \bt_p{option}
4004 See bt_field_class_variant_option_borrow_user_attributes().
4006 extern const bt_value
*bt_field_class_variant_option_borrow_user_attributes_const(
4007 const bt_field_class_variant_option
*option
);
4012 @name Variant field class without a selector field
4019 bt_field_class_variant_without_selector_append_option().
4021 typedef enum bt_field_class_variant_without_selector_append_option_status
{
4026 BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
4032 BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
4033 } bt_field_class_variant_without_selector_append_option_status
;
4037 Appends an option to the \bt_var_fc (without a selector field)
4038 \bt_p{field_class} having the name \bt_p{name} and the
4039 field class \bt_p{option_field_class}.
4041 See the \ref api-tir-fc-var-prop-opts "options" property.
4043 @param[in] field_class
4044 Variant field class to which to append an option having
4045 the name \bt_p{name} and the field class \bt_p{option_field_class}.
4047 Name of the option to append to \bt_p{field_class} (copied).
4048 @param[in] option_field_class
4049 Field class of the option to append to \bt_p{field_class}.
4051 @retval #BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
4053 @retval #BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
4056 @bt_pre_not_null{field_class}
4057 @bt_pre_hot{field_class}
4058 @bt_pre_is_var_wos_fc{field_class}
4060 \bt_p{field_class} has no option with the name \bt_p{name}.
4061 @bt_pre_not_null{name}
4062 @bt_pre_not_null{option_field_class}
4063 @bt_pre_fc_not_in_tc{option_field_class}
4065 @bt_post_success_frozen{option_field_class}
4067 extern bt_field_class_variant_without_selector_append_option_status
4068 bt_field_class_variant_without_selector_append_option(
4069 bt_field_class
*field_class
, const char *name
,
4070 bt_field_class
*option_field_class
);
4075 @name Variant field class with a selector field
4082 bt_field_class_variant_with_selector_field_integer_unsigned_append_option()
4084 bt_field_class_variant_with_selector_field_integer_signed_append_option().
4086 typedef enum bt_field_class_variant_with_selector_field_integer_append_option_status
{
4091 BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
4097 BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
4098 } bt_field_class_variant_with_selector_field_integer_append_option_status
;
4102 Borrows the selector field path from the \bt_var_fc (with a selector
4103 field) \bt_p{field_class}.
4105 See the \ref api-tir-fc-var-prop-sel-fp "selector field path" property.
4107 This property is only available when a \bt_struct_fc containing
4108 (recursively) \bt_p{field_class} is passed to one of:
4110 - bt_stream_class_set_packet_context_field_class()
4111 - bt_stream_class_set_event_common_context_field_class()
4112 - bt_event_class_set_specific_context_field_class()
4113 - bt_event_class_set_payload_field_class()
4115 In the meantime, this function returns \c NULL.
4117 @param[in] field_class
4118 Variant field class from which to borrow the selector field path.
4121 Selector field path of \bt_p{field_class}.
4123 @bt_pre_not_null{field_class}
4124 @bt_pre_is_var_ws_fc{field_class}
4126 extern const bt_field_path
*
4127 bt_field_class_variant_with_selector_field_borrow_selector_field_path_const(
4128 const bt_field_class
*field_class
);
4133 @name Variant field class with an unsigned integer selector field
4139 Appends an option to the \bt_var_fc (with an unsigned integer
4140 selector field) \bt_p{field_class} having the name \bt_p{name},
4141 the field class \bt_p{option_field_class}, and the
4142 \bt_p_uint_rg \bt_p{ranges}.
4144 See the \ref api-tir-fc-var-prop-opts "options" property.
4146 @param[in] field_class
4147 Variant field class to which to append an option having
4148 the name \bt_p{name}, the field class \bt_p{option_field_class},
4149 and the unsigned integer ranges \bt_p{ranges}.
4151 Name of the option to append to \bt_p{field_class} (copied).
4152 @param[in] option_field_class
4153 Field class of the option to append to \bt_p{field_class}.
4155 Unsigned integer ranges of the option to append to
4158 @retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
4160 @retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
4163 @bt_pre_not_null{field_class}
4164 @bt_pre_hot{field_class}
4165 @bt_pre_is_var_wuis_fc{field_class}
4167 \bt_p{field_class} has no option with the name \bt_p{name}.
4168 @bt_pre_not_null{name}
4169 @bt_pre_not_null{option_field_class}
4170 @bt_pre_fc_not_in_tc{option_field_class}
4171 @bt_pre_not_null{Å—anges}
4173 \bt_p{ranges} contains one or more unsigned integer ranges.
4175 The unsigned integer ranges in \bt_p{ranges} do not overlap
4176 any unsigned integer range of any existing option in
4179 @bt_post_success_frozen{option_field_class}
4181 extern bt_field_class_variant_with_selector_field_integer_append_option_status
4182 bt_field_class_variant_with_selector_field_integer_unsigned_append_option(
4183 bt_field_class
*field_class
, const char *name
,
4184 bt_field_class
*option_field_class
,
4185 const bt_integer_range_set_unsigned
*ranges
);
4189 Borrows the option at index \bt_p{index} from the
4190 \bt_var_fc (with an unsigned integer selector field)
4193 See the \ref api-tir-fc-var-prop-opts "options" property.
4195 @param[in] field_class
4196 Variant field class from which to borrow the option at
4199 Index of the option to borrow from \bt_p{field_class}.
4203 \em Borrowed reference of the option of
4204 \bt_p{field_class} at index \bt_p{index}.
4206 The returned pointer remains valid as long as \bt_p{field_class}
4210 @bt_pre_not_null{field_class}
4211 @bt_pre_is_var_wuis_fc{field_class}
4213 \bt_p{index} is less than the number of options in
4214 \bt_p{field_class} (as returned by
4215 bt_field_class_variant_get_option_count()).
4217 @sa bt_field_class_variant_get_option_count() —
4218 Returns the number of options contained in a variant field class.
4220 extern const bt_field_class_variant_with_selector_field_integer_unsigned_option
*
4221 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(
4222 const bt_field_class
*field_class
, uint64_t index
);
4226 Borrows the option having the name \bt_p{name} from the
4227 \bt_var_fc (with an unsigned integer selector field)
4230 See the \ref api-tir-fc-var-prop-opts "options" property.
4232 If there's no option having the name \bt_p{name} in
4233 \bt_p{field_class}, this function returns \c NULL.
4235 @param[in] field_class
4236 Variant field class from which to borrow the option having the
4239 Name of the option to borrow from \bt_p{field_class}.
4243 \em Borrowed reference of the option of
4244 \bt_p{field_class} having the name \bt_p{name}, or \c NULL
4247 The returned pointer remains valid as long as \bt_p{field_class}
4251 @bt_pre_not_null{field_class}
4252 @bt_pre_is_var_wuis_fc{field_class}
4253 @bt_pre_not_null{name}
4255 @sa bt_field_class_variant_borrow_option_by_name_const() —
4256 Borrows an option by name from a variant field class.
4258 extern const bt_field_class_variant_with_selector_field_integer_unsigned_option
*
4259 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const(
4260 const bt_field_class
*field_class
, const char *name
);
4265 @name Variant field class (with an unsigned integer selector field) option
4270 @typedef struct bt_field_class_variant_with_selector_field_integer_unsigned_option bt_field_class_variant_with_selector_field_integer_unsigned_option;
4273 Variant field class (with an unsigned integer selector field) option.
4278 Borrows the \bt_p_uint_rg from the \bt_var_fc (with an unsigned
4279 integer selector field) option \bt_p{option}.
4281 See the \ref api-tir-fc-var-prop-opts "options" property.
4284 Variant field class option from which to borrow the
4285 unsigned integer ranges.
4288 Unsigned integer ranges of \bt_p{option}.
4290 @bt_pre_not_null{option}
4292 extern const bt_integer_range_set_unsigned
*
4293 bt_field_class_variant_with_selector_field_integer_unsigned_option_borrow_ranges_const(
4294 const bt_field_class_variant_with_selector_field_integer_unsigned_option
*option
);
4298 \ref api-fund-c-typing "Upcasts" the \bt_var_fc (with an
4299 unsigned integer selector field) option \bt_p{option} to the
4300 common #bt_field_class_variant_option type.
4302 See the \ref api-tir-fc-var-prop-opts "options" property.
4306 Variant field class option to upcast.
4312 \bt_p{option} as a common variant field class option.
4315 const bt_field_class_variant_option
*
4316 bt_field_class_variant_with_selector_field_integer_unsigned_option_as_option_const(
4317 const bt_field_class_variant_with_selector_field_integer_unsigned_option
*option
)
4319 return __BT_UPCAST_CONST(bt_field_class_variant_option
, option
);
4325 @name Variant field class with a signed integer selector field
4331 Appends an option to the \bt_var_fc (with a signed integer
4332 selector field) \bt_p{field_class} having the name \bt_p{name},
4333 the field class \bt_p{option_field_class}, and the
4334 \bt_p_sint_rg \bt_p{ranges}.
4336 See the \ref api-tir-fc-var-prop-opts "options" property.
4338 @param[in] field_class
4339 Variant field class to which to append an option having
4340 the name \bt_p{name} and the field class \bt_p{option_field_class},
4341 and the signed integer ranges \bt_p{ranges}.
4343 Name of the option to append to \bt_p{field_class} (copied).
4344 @param[in] option_field_class
4345 Field class of the option to append to \bt_p{field_class}.
4347 Signed integer ranges of the option to append to
4350 @retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
4352 @retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
4355 @bt_pre_not_null{field_class}
4356 @bt_pre_hot{field_class}
4357 @bt_pre_is_var_wsis_fc{field_class}
4359 \bt_p{field_class} has no option with the name \bt_p{name}.
4360 @bt_pre_not_null{name}
4361 @bt_pre_not_null{option_field_class}
4362 @bt_pre_fc_not_in_tc{option_field_class}
4363 @bt_pre_not_null{Å—anges}
4365 \bt_p{ranges} contains one or more signed integer ranges.
4367 The signed integer ranges in \bt_p{ranges} do not overlap with
4368 any signed integer range of any existing option in
4371 @bt_post_success_frozen{option_field_class}
4373 extern bt_field_class_variant_with_selector_field_integer_append_option_status
4374 bt_field_class_variant_with_selector_field_integer_signed_append_option(
4375 bt_field_class
*field_class
, const char *name
,
4376 bt_field_class
*option_field_class
,
4377 const bt_integer_range_set_signed
*ranges
);
4381 Borrows the option at index \bt_p{index} from the
4382 \bt_var_fc (with a signed integer selector field)
4385 See the \ref api-tir-fc-var-prop-opts "options" property.
4387 @param[in] field_class
4388 Variant field class from which to borrow the option at
4391 Index of the option to borrow from \bt_p{field_class}.
4395 \em Borrowed reference of the option of
4396 \bt_p{field_class} at index \bt_p{index}.
4398 The returned pointer remains valid as long as \bt_p{field_class}
4402 @bt_pre_not_null{field_class}
4403 @bt_pre_is_var_wsis_fc{field_class}
4405 \bt_p{index} is less than the number of options in
4406 \bt_p{field_class} (as returned by
4407 bt_field_class_variant_get_option_count()).
4409 @sa bt_field_class_variant_get_option_count() —
4410 Returns the number of options contained in a variant field class.
4412 extern const bt_field_class_variant_with_selector_field_integer_signed_option
*
4413 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(
4414 const bt_field_class
*field_class
, uint64_t index
);
4418 Borrows the option having the name \bt_p{name} from the
4419 \bt_var_fc (with a signed integer selector field)
4422 See the \ref api-tir-fc-var-prop-opts "options" property.
4424 If there's no option having the name \bt_p{name} in
4425 \bt_p{field_class}, this function returns \c NULL.
4427 @param[in] field_class
4428 Variant field class from which to borrow the option having the
4431 Name of the option to borrow from \bt_p{field_class}.
4435 \em Borrowed reference of the option of
4436 \bt_p{field_class} having the name \bt_p{name}, or \c NULL
4439 The returned pointer remains valid as long as \bt_p{field_class}
4443 @bt_pre_not_null{field_class}
4444 @bt_pre_is_var_wsis_fc{field_class}
4445 @bt_pre_not_null{name}
4447 @sa bt_field_class_variant_borrow_option_by_name_const() —
4448 Borrows an option by name from a variant field class.
4450 extern const bt_field_class_variant_with_selector_field_integer_signed_option
*
4451 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const(
4452 const bt_field_class
*field_class
, const char *name
);
4457 @name Variant field class (with a signed integer selector field) option
4462 @typedef struct bt_field_class_variant_with_selector_field_integer_signed_option bt_field_class_variant_with_selector_field_integer_signed_option;
4465 Variant field class (with a signed integer selector field) option.
4470 Borrows the \bt_p_sint_rg from the \bt_var_fc (with a signed
4471 integer selector field) option \bt_p{option}.
4473 See the \ref api-tir-fc-var-prop-opts "options" property.
4476 Variant field class option from which to borrow the
4477 signed integer ranges.
4480 Signed integer ranges of \bt_p{option}.
4482 @bt_pre_not_null{option}
4484 extern const bt_integer_range_set_signed
*
4485 bt_field_class_variant_with_selector_field_integer_signed_option_borrow_ranges_const(
4486 const bt_field_class_variant_with_selector_field_integer_signed_option
*option
);
4490 \ref api-fund-c-typing "Upcasts" the \bt_var_fc (with a signed
4491 integer selector field) option \bt_p{option} to the
4492 common #bt_field_class_variant_option type.
4494 See the \ref api-tir-fc-var-prop-opts "options" property.
4498 Variant field class option to upcast.
4504 \bt_p{option} as a common variant field class option.
4507 const bt_field_class_variant_option
*
4508 bt_field_class_variant_with_selector_field_integer_signed_option_as_option_const(
4509 const bt_field_class_variant_with_selector_field_integer_signed_option
*option
)
4511 return __BT_UPCAST_CONST(bt_field_class_variant_option
, option
);
4517 @name Reference count
4523 Increments the \ref api-fund-shared-object "reference count" of
4524 the field class \bt_p{field_class}.
4526 @param[in] field_class
4528 Field class of which to increment the reference count.
4533 @sa bt_field_class_put_ref() —
4534 Decrements the reference count of a field class.
4536 extern void bt_field_class_get_ref(const bt_field_class
*field_class
);
4540 Decrements the \ref api-fund-shared-object "reference count" of
4541 the field class \bt_p{field_class}.
4543 @param[in] field_class
4545 Field class of which to decrement the reference count.
4550 @sa bt_field_class_get_ref() —
4551 Increments the reference count of a field class.
4553 extern void bt_field_class_put_ref(const bt_field_class
*field_class
);
4557 Decrements the reference count of the field class
4558 \bt_p{_field_class}, and then sets \bt_p{_field_class} to \c NULL.
4562 Field class of which to decrement the reference count.
4564 Can contain \c NULL.
4567 @bt_pre_assign_expr{_field_class}
4569 #define BT_FIELD_CLASS_PUT_REF_AND_RESET(_field_class) \
4571 bt_field_class_put_ref(_field_class); \
4572 (_field_class) = NULL; \
4577 Decrements the reference count of the field class \bt_p{_dst}, sets
4578 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
4580 This macro effectively moves a field class reference from the expression
4581 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
4582 \bt_p{_dst} reference.
4586 Destination expression.
4588 Can contain \c NULL.
4594 Can contain \c NULL.
4597 @bt_pre_assign_expr{_dst}
4598 @bt_pre_assign_expr{_src}
4600 #define BT_FIELD_CLASS_MOVE_REF(_dst, _src) \
4602 bt_field_class_put_ref(_dst); \
4615 #endif /* BABELTRACE2_TRACE_IR_FIELD_CLASS_H */