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 #ifndef __BT_IN_BABELTRACE_H
11 # error "Please include <babeltrace2/babeltrace.h> instead."
17 #include <babeltrace2/types.h>
24 @defgroup api-tir-fc Field classes
28 Classes of \bt_p_field.
30 <strong><em>Field classes</em></strong> are the classes of \bt_p_field:
32 @image html field-class-zoom.png
34 Field classes are \ref api-tir "trace IR" metadata objects.
36 There are many types of field classes. They can be divided into two main
42 Classes of fields which contain a simple value.
44 The scalar field classes are:
46 - \ref api-tir-fc-bool "Boolean"
47 - \ref api-tir-fc-ba "Bit array"
48 - \ref api-tir-fc-int "Integer" (unsigned and signed)
49 - \ref api-tir-fc-enum "Enumeration" (unsigned and signed)
50 - \ref api-tir-fc-real "Real" (single-precision and double-precision)
51 - \ref api-tir-fc-string "String"
56 Classes of fields which contain other fields.
58 The container field classes are:
60 - \ref api-tir-fc-array "Array" (static and dynamic)
61 - \ref api-tir-fc-struct "Structure"
62 - \ref api-tir-fc-opt "Option"
63 - \ref api-tir-fc-var "Variant"
67 @image html fc-to-field.png "Fields (green) are instances of field classes (orange)."
69 Some field classes conceptually inherit other field classes, eventually
70 making an inheritance hierarchy. For example, a \bt_sarray_fc
71 \em is an array field class. Therefore, a static array field class has
72 any property that an array field class has.
74 The complete field class inheritance hierarchy is:
76 @image html all-field-classes.png
78 In the illustration above:
80 - You can create any field class with a dark background with
81 a dedicated <code>bt_field_class_*_create()</code> function.
83 - A field class with a pale background is an \em abstract field class:
84 you cannot create it, but it has properties, therefore there are
85 functions which apply to it.
87 For example, bt_field_class_integer_set_preferred_display_base()
88 applies to any \bt_int_fc.
90 Field classes are \ref api-fund-shared-object "shared objects": get a
91 new reference with bt_field_class_get_ref() and put an existing
92 reference with bt_field_class_put_ref().
94 Some library functions \ref api-fund-freezing "freeze" field classes on
95 success. The documentation of those functions indicate this
98 All the field class types share the same C type, #bt_field_class.
100 Get the type enumerator of a field class with bt_field_class_get_type().
101 Get whether or not a field class type conceptually \em is a given type
102 with the inline bt_field_class_type_is() function.
104 The following table shows the available type enumerators and creation
105 functions for each type of \em concrete (non-abstract) field class:
111 <th>Creation function
113 <td><em>\ref api-tir-fc-bool "Boolean"</em>
114 <td>#BT_FIELD_CLASS_TYPE_BOOL
115 <td>bt_field_class_bool_create()
117 <td><em>\ref api-tir-fc-ba "Bit array"</em>
118 <td>#BT_FIELD_CLASS_TYPE_BIT_ARRAY
119 <td>bt_field_class_bit_array_create()
121 <td><em>Unsigned \ref api-tir-fc-int "integer"</em>
122 <td>#BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER
123 <td>bt_field_class_integer_unsigned_create()
125 <td><em>Signed \ref api-tir-fc-int "integer"</em>
126 <td>#BT_FIELD_CLASS_TYPE_SIGNED_INTEGER
127 <td>bt_field_class_integer_signed_create()
129 <td><em>Unsigned \ref api-tir-fc-enum "enumeration"</em>
130 <td>#BT_FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION
131 <td>bt_field_class_enumeration_unsigned_create()
133 <td><em>Signed \ref api-tir-fc-enum "enumeration"</em>
134 <td>#BT_FIELD_CLASS_TYPE_SIGNED_ENUMERATION
135 <td>bt_field_class_enumeration_signed_create()
137 <td><em>Single-precision \ref api-tir-fc-real "real"</em>
138 <td>#BT_FIELD_CLASS_TYPE_SINGLE_PRECISION_REAL
139 <td>bt_field_class_real_single_precision_create()
141 <td><em>Double-precision \ref api-tir-fc-real "real"</em>
142 <td>#BT_FIELD_CLASS_TYPE_DOUBLE_PRECISION_REAL
143 <td>bt_field_class_real_double_precision_create()
145 <td><em>\ref api-tir-fc-string "String"</em>
146 <td>#BT_FIELD_CLASS_TYPE_STRING
147 <td>bt_field_class_string_create()
149 <td><em>Static \ref api-tir-fc-array "array"</em>
150 <td>#BT_FIELD_CLASS_TYPE_STATIC_ARRAY
151 <td>bt_field_class_array_static_create()
153 <td><em>Dynamic \ref api-tir-fc-array "array" (no length field)</em>
154 <td>#BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD
155 <td>bt_field_class_array_dynamic_create()
157 <td><em>Dynamic \ref api-tir-fc-array "array" (with length field)</em>
158 <td>#BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD
159 <td>bt_field_class_array_dynamic_create()
161 <td><em>\ref api-tir-fc-struct "Structure"</em>
162 <td>#BT_FIELD_CLASS_TYPE_STRUCTURE
163 <td>bt_field_class_structure_create()
165 <td><em>\ref api-tir-fc-opt "Option" (no selector field)</em>
166 <td>#BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD
167 <td>bt_field_class_option_without_selector_create()
169 <td><em>\ref api-tir-fc-opt "Option" (boolean selector field)</em>
170 <td>#BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD
171 <td>bt_field_class_option_with_selector_field_bool_create()
173 <td><em>\ref api-tir-fc-opt "Option" (unsigned integer selector field)</em>
174 <td>#BT_FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
175 <td>bt_field_class_option_with_selector_field_integer_unsigned_create()
177 <td><em>\ref api-tir-fc-opt "Option" (signed integer selector field)</em>
178 <td>#BT_FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD
179 <td>bt_field_class_option_with_selector_field_integer_signed_create()
181 <td><em>\ref api-tir-fc-var "Variant" (no selector field)</em>
182 <td>#BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD
183 <td>bt_field_class_variant_create()
185 <td><em>\ref api-tir-fc-var "Variant" (unsigned integer selector field)</em>
186 <td>#BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
187 <td>bt_field_class_variant_create()
189 <td><em>\ref api-tir-fc-var "Variant" (signed integer selector field)</em>
190 <td>#BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD
191 <td>bt_field_class_variant_create()
194 You need a \bt_trace_cls to create a field class: create one from a
195 \bt_self_comp with bt_trace_class_create().
197 Outside the field class API, you can use field classes at four
198 locations, called <em>scopes</em>, within the trace IR API:
200 - To set the packet context field class of a \bt_stream_cls with
201 bt_stream_class_set_packet_context_field_class().
203 - To set the event common context field class of a stream class with
204 bt_stream_class_set_event_common_context_field_class().
206 - To set the specific context field class of an \bt_ev_cls with
207 bt_event_class_set_specific_context_field_class().
209 - To set the payload field class of an event class with
210 bt_event_class_set_payload_field_class().
212 When you call one of the four functions above:
214 - The passed field class must be a \bt_struct_fc.
216 - You must \em not have already called any of the four functions above
217 with the passed field class or with any of its contained field
220 - If any of the field classes recursively contained in the passed
221 field class has a \ref api-tir-fc-link "link to another field class",
222 it must honor the field class link rules.
224 Once you have called one of the four functions above, the passed field
225 class becomes \ref api-fund-freezing "frozen".
227 <h1>Common field class property</h1>
229 A field class has the following common property:
233 \anchor api-tir-fc-prop-user-attrs
234 \bt_dt_opt User attributes
237 User attributes of the field class.
239 User attributes are custom attributes attached to a field class.
241 Use bt_field_class_set_user_attributes(),
242 bt_field_class_borrow_user_attributes(), and
243 bt_field_class_borrow_user_attributes_const().
247 <h1>\anchor api-tir-fc-bool Boolean field class</h1>
249 @image html fc-bool.png
251 A <strong><em>boolean field class</em></strong> is the class
254 A boolean field contains a boolean value (#BT_TRUE or #BT_FALSE).
256 Create a boolean field class with bt_field_class_bool_create().
258 A boolean field class has no specific properties.
260 <h1>\anchor api-tir-fc-ba Bit array field class</h1>
262 @image html fc-ba.png
264 A <strong><em>bit array field class</em></strong> is the class
267 A bit array field contains a fixed-length array of bits.
269 Create a bit array field class with bt_field_class_bit_array_create().
271 A bit array field class has the following property:
275 \anchor api-tir-fc-ba-prop-len
279 Number of bits contained in the instances (bit array fields) of
280 the bit array field class.
282 As of \bt_name_version_min_maj, the maximum length of a bit array
285 You cannot change the length once the bit array field class is
288 Get a bit array field class's length with
289 bt_field_class_bit_array_get_length().
293 <h1>\anchor api-tir-fc-int Integer field classes</h1>
295 @image html fc-int.png
297 <strong><em>Integer field classes</em></strong> are classes
300 Integer fields contain integral values.
302 An integer field class is an \em abstract field class: you cannot create
303 one. The concrete integer field classes are:
306 <dt>Unsigned integer field class</dt>
308 Its instances (unsigned integer fields) contain an unsigned integral
311 Create with bt_field_class_integer_unsigned_create().
314 <dt>Signed integer field class</dt>
316 Its instances (signed integer fields) contain a signed integral
319 Create with bt_field_class_integer_signed_create().
323 Integer field classes have the following common properties:
327 \anchor api-tir-fc-int-prop-size
331 Expected range of values that the instances (integer fields)
332 of the integer field class can contain.
334 For example, if the field value range of an unsigned integer
335 field class is [0, 16383], then its unsigned integer fields
336 can only contain the values from 0 to 16383.
338 \bt_cp_sink_comp can benefit from this property to make some space
339 optimizations when writing trace data.
341 Use bt_field_class_integer_set_field_value_range() and
342 bt_field_class_integer_get_field_value_range().
346 \anchor api-tir-fc-int-prop-base
347 Preferred display base
350 Preferred base (2, 8, 10, or 16) to use when displaying the
351 instances (integer fields) of the integer field class.
353 Use bt_field_class_integer_set_preferred_display_base() and
354 bt_field_class_integer_get_preferred_display_base().
358 <h2>\anchor api-tir-fc-enum Enumeration field classes</h2>
360 @image html fc-enum.png
362 <strong><em>Enumeration field classes</em></strong> are classes
365 Enumeration field classes \em are \bt_p_int_fc: they have the integer
366 field classes properties.
368 Enumeration fields \em are integer fields: they contain integral values.
370 Enumeration field classes associate labels (strings) to specific
371 ranges of integral values. This association is called an enumeration
372 field class <em>mapping</em>.
374 For example, if an enumeration field class maps the label \c SUGAR to
375 the integer ranges [1, 19] and [25, 31], then an instance
376 (enumeration field) of this field class with the value 15 or 28 has the
377 label <code>SUGAR</code>.
379 An enumeration field class is an \em abstract field class: you cannot
380 create one. The concrete enumeration field classes are:
383 <dt>Unsigned enumeration field class</dt>
385 Its instances (unsigned enumeration fields) contain an unsigned
388 Create with bt_field_class_enumeration_unsigned_create().
391 <dt>Signed enumeration field class</dt>
393 Its instances (signed enumeration fields) contain a signed value
396 Create with bt_field_class_enumeration_signed_create().
400 Enumeration field classes have the following common property:
404 \anchor api-tir-fc-enum-prop-mappings
408 Set of mappings of the enumeration field class.
410 An enumeration field class mapping is a label (string) and an
413 The integer ranges of a given mapping or of multiple mappings of
414 the same enumeration field class can overlap. For example,
415 an enumeration field class can have those two mappings:
417 - <code>CALORIES</code>: [1, 11], [15, 37]
418 - <code>SODIUM</code>: [7, 13]
420 In that case, the values 2 and 30 correpond to the label
421 <code>CALORIES</code>, the value 12 to the label
422 <code>SODIUM</code>, and the value 10 to the labels
423 \c CALORIES \em and <code>SODIUM</code>.
425 Two mappings of the same enumeration field class cannot have the
428 Add a mapping to an enumeration field class with
429 bt_field_class_enumeration_unsigned_add_mapping() or
430 bt_field_class_enumeration_signed_add_mapping().
432 Get the number of mappings in an enumeration field class with
433 bt_field_class_enumeration_get_mapping_count().
435 Borrow a mapping from an enumeration field class with
436 bt_field_class_enumeration_unsigned_borrow_mapping_by_index_const(),
437 bt_field_class_enumeration_signed_borrow_mapping_by_index_const(),
438 bt_field_class_enumeration_unsigned_borrow_mapping_by_label_const(),
440 bt_field_class_enumeration_signed_borrow_mapping_by_label_const().
442 An enumeration field class mapping is a
443 \ref api-fund-unique-object "unique object": it
444 belongs to the enumeration field class which contains it.
446 There are two enumeration field class mapping types, depending on
447 the field class's type:
448 #bt_field_class_enumeration_unsigned_mapping and
449 #bt_field_class_enumeration_signed_mapping.
451 There is also the #bt_field_class_enumeration_mapping type for
452 common properties and operations (for example,
453 bt_field_class_enumeration_mapping_get_label()).
454 \ref api-fund-c-typing "Upcast" a specific enumeration field class
455 mapping to the #bt_field_class_enumeration_mapping type with
456 bt_field_class_enumeration_unsigned_mapping_as_mapping_const() or
457 bt_field_class_enumeration_signed_mapping_as_mapping_const().
459 Get all the enumeration field class labels mapped to a given integer
461 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value()
463 bt_field_class_enumeration_signed_get_mapping_labels_for_value().
467 <h1>\anchor api-tir-fc-real Real field classes</h1>
469 @image html fc-real.png
471 <strong><em>Real field classes</em></strong> are classes
475 <a href="https://en.wikipedia.org/wiki/Real_number">real</a>
476 values (\c float or \c double types).
478 A real field class is an \em abstract field class: you cannot create
479 one. The concrete real field classes are:
482 <dt>Single-precision real field class</dt>
484 Its instances (single-precision real fields) contain a \c float
487 Create with bt_field_class_real_single_precision_create().
490 <dt>Double-precision real field class</dt>
492 Its instances (double-precision real fields) contain a \c double
495 Create with bt_field_class_real_double_precision_create().
499 Real field classes have no specific properties.
501 <h1>\anchor api-tir-fc-string String field class</h1>
503 @image html fc-string.png
505 A <strong><em>string field class</em></strong> is the class
506 of \bt_p_string_field.
508 A string field contains an UTF-8 string value.
510 Create a string field class with bt_field_class_string_create().
512 A string field class has no specific properties.
514 <h1>\anchor api-tir-fc-array Array field classes</h1>
516 @image html fc-array.png
518 <strong><em>Array field classes</em></strong> are classes
519 of \bt_p_array_field.
521 Array fields contain zero or more fields which have the same class.
523 An array field class is an \em abstract field class: you cannot create
524 one. The concrete array field classes are:
527 <dt>Static array field class</dt>
529 Its instances (static array fields) contain a fixed number of
532 Create with bt_field_class_array_static_create().
534 A static array field class has the following specific property:
538 \anchor api-tir-fc-sarray-prop-len
542 Number of fields contained in the instances (static array
543 fields) of the static array field class.
545 You cannot change the length once the static array field class
548 Get a static array field class's length with
549 bt_field_class_array_static_get_length().
554 <dt>Dynamic array field class</dt>
556 Its instances (dynamic array fields) contain a variable number array
559 There are two types of dynamic array field classes: without or
560 with a length field. See
561 \ref api-tir-fc-link "Field classes with links to other field classes"
564 @image html darray-link.png "Dynamic array field class with a length field."
566 Create with bt_field_class_array_dynamic_create().
568 A dynamic array field class with a length field has the
573 \anchor api-tir-fc-darray-prop-len-fp
577 Field path of the linked length field class.
579 Get a dynamic array field class's length field path with
580 bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const().
586 Array field classes have the following common property:
590 \anchor api-tir-fc-array-prop-elem-fc
594 Class of the fields contained in the instances (array fields) of the
597 You cannot change the element field class once the array field class
600 Borrow an array field class's element field class with
601 Use bt_field_class_array_borrow_element_field_class() and
602 bt_field_class_array_borrow_element_field_class_const().
606 <h1>\anchor api-tir-fc-struct Structure field class</h1>
608 @image html fc-struct.png
610 A <strong><em>structure field class</em></strong> is the class
611 of a \bt_struct_field.
613 A structure field contains an ordered list of zero or more members. Each
614 structure field member is the instance of a structure field class
615 member. A structure field class member has a name, a field class,
618 Create a structure field class with bt_field_class_structure_create().
620 A structure field class has the following specific property:
624 \anchor api-tir-fc-struct-prop-members
628 Ordered list of members (zero or more) of the structure field class.
632 - A name, unique amongst all the member names of the same
633 structure field class.
637 The instances (structure fields) of a structure field class have
638 members which are instances of the corresponding structure field
641 Append a member to a structure field class with
642 bt_field_class_structure_append_member().
644 Borrow a member from a structure field class with
645 bt_field_class_structure_borrow_member_by_index(),
646 bt_field_class_structure_borrow_member_by_name(),
647 bt_field_class_structure_borrow_member_by_index_const(), and
648 bt_field_class_structure_borrow_member_by_name_const().
650 A structure field class member is a
651 \ref api-fund-unique-object "unique object": it
652 belongs to the structure field class which contains it.
654 The type of a structure field class member is
655 #bt_field_class_structure_member.
657 Get a structure field class member's name with
658 bt_field_class_structure_member_get_name().
660 Borrow a structure field class member's field class with
661 bt_field_class_structure_member_borrow_field_class() and
662 bt_field_class_structure_member_borrow_field_class_const().
664 Set a structure field class member's user attributes with
665 bt_field_class_structure_member_set_user_attributes().
667 Borrow a structure field class member's user attributes with
668 bt_field_class_structure_member_borrow_user_attributes() and
669 bt_field_class_structure_member_borrow_user_attributes_const().
673 <h1>\anchor api-tir-fc-opt Option field classes</h1>
675 @image html fc-opt.png
677 <strong><em>Option field classes</em></strong> are classes
680 An option field either does or doesn't contain a field, called its
683 An option field class is an \em abstract field class: you cannot create
684 one. An option field class either has a selector field (it's linked to a
685 selector field class; see
686 \ref api-tir-fc-link "Field classes with links to other field classes")
687 or none. Therefore, the concrete option field classes are:
690 <dt>Option field class without a selector field</dt>
692 Create with bt_field_class_option_without_selector_create().
694 An option field class without a selector field has no specific
698 <dt>Option field class with a boolean selector field</dt>
700 The linked selector field of an option field class's instance
701 (an option field) is a \bt_bool_field.
703 Consequently, the option field class's selector field class is
706 @image html opt-link.png "Option field class with a boolean selector field."
708 Create with bt_field_class_option_with_selector_field_bool_create().
710 An option field class with a boolean selector field has the
711 following specific property:
715 \anchor api-tir-fc-opt-prop-sel-rev
716 Selector is reversed?
719 Whether or not the linked boolean selector field makes the
720 option field class's instance (an option field) contain a field
721 when it's #BT_TRUE or when it's #BT_FALSE.
723 If this property is #BT_TRUE, then if the linked selector field
724 has the value #BT_FALSE, the option field contains a field.
727 bt_field_class_option_with_selector_field_bool_set_selector_is_reversed()
729 bt_field_class_option_with_selector_field_bool_selector_is_reversed().
734 <dt>Option field class with an unsigned selector field</dt>
736 The linked selector field of an option field class's instance
737 (an option field) is an \bt_uint_field.
739 Consequently, the option field class's selector field class is
743 bt_field_class_option_with_selector_field_integer_unsigned_create().
745 Pass an \bt_uint_rs on creation to set which values of the selector
746 field can make the option field contain a field.
748 An option field class with an unsigned integer selector field has
749 the following specific property:
753 \anchor api-tir-fc-opt-prop-uint-rs
754 Selector's unsigned integer ranges
757 If the linked unsigned integer selector field of an option
758 field class's instance (an option field) has a value which
759 intersects with the selector's unsigned integer ranges, then
760 the option field contains a field.
762 You cannot change the selector's unsigned integer ranges once
763 the option field class is created.
765 Borrow the selector's unsigned integer ranges from an
766 option field class with an unsigned integer selector field with
767 bt_field_class_option_with_selector_field_integer_unsigned_borrow_selector_ranges_const().
772 <dt>Option field class with a signed selector field</dt>
774 The linked selector field of an option field class's instance
775 (an option field) is a \bt_sint_field.
777 Consequently, the option field class's selector field class is
781 bt_field_class_option_with_selector_field_integer_signed_create().
783 Pass a \bt_sint_rs on creation to set which values of the selector
784 field can make the option field contain a field.
786 An option field class with a signed integer selector field has
787 the following specific property:
791 \anchor api-tir-fc-opt-prop-sint-rs
792 Selector's signed integer ranges
795 If the linked signed integer selector field of an option
796 field class's instance (an option field) has a value which
797 intersects with the selector's signed integer ranges, then
798 the option field contains a field.
800 You cannot change the selector's signed integer ranges once
801 the option field class is created.
803 Borrow the selector's signed integer ranges from an
804 option field class with a signed integer selector field with
805 bt_field_class_option_with_selector_field_integer_signed_borrow_selector_ranges_const().
811 Option field classes with a selector have the following common
816 \anchor api-tir-fc-opt-prop-sel-fp
820 Field path of the linked selector field class.
822 Borrow such an option field class's selector field path with
823 bt_field_class_option_with_selector_field_borrow_selector_field_path_const().
827 Option field classes have the following common property:
831 \anchor api-tir-fc-opt-prop-fc
835 Class of the optional field of an instance (option field) of the
838 You cannot change the optional field class once the option field
841 Borrow an option field class's optional field class with
842 Use bt_field_class_option_borrow_field_class() and
843 bt_field_class_option_borrow_field_class_const().
847 <h1>\anchor api-tir-fc-var Variant field classes</h1>
849 @image html fc-var.png
851 <strong><em>Variant field classes</em></strong> are classes
854 A variant field contains a field amongst one or more possible fields.
856 Variant field classes contain one or more options. Each variant field
857 class option has a name, a field class, user attributes, and integer
858 ranges, depending on the exact type.
860 A variant field class is an \em abstract field class: you cannot create
861 one. A variant field class either has a selector field (it's linked to a
862 selector field class; see
863 \ref api-tir-fc-link "Field classes with links to other field classes")
864 or none. Therefore, the concrete variant field classes are:
867 <dt>Variant field class without a selector field</dt>
869 Create with bt_field_class_variant_create(), passing \c NULL as
870 the selector field class.
872 Append an option to such a variant field class with
873 bt_field_class_variant_without_selector_append_option().
875 A variant field class without a selector field has no specific
879 <dt>Variant field class with an unsigned selector field</dt>
881 The linked selector field of a variant field class's instance
882 (a variant field) is an \bt_uint_field.
884 Consequently, the variant field class's selector field class is
887 @image html var-link.png "Variant field class with an unsigned integer selector field."
889 Create with bt_field_class_variant_create(), passing an
890 unsigned integer field class as the selector field class.
892 Append an option to such a variant field class with
893 bt_field_class_variant_with_selector_field_integer_unsigned_append_option().
895 Pass an \bt_uint_rs when you append an option to set which values of
896 the selector field can make the variant field have a given
899 Borrow such a variant field class's option with
900 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const()
902 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const().
905 <dt>Variant field class with a signed selector field</dt>
907 The linked selector field of a variant field class's instance
908 (a variant field) is a \bt_sint_field.
910 Consequently, the variant field class's selector field class is
913 Create with bt_field_class_variant_create(), passing a
914 signed integer field class as the selector field class.
916 Append an option to such a variant field class with
917 bt_field_class_variant_with_selector_field_integer_signed_append_option().
919 Pass a \bt_sint_rs when you append an option to set which values of
920 the selector field can make the variant field have a given
923 Borrow such a variant field class's option with
924 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const()
926 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const().
930 Variant field classes with a selector have the following common
935 \anchor api-tir-fc-var-prop-sel-fp
939 Field path of the linked selector field class.
941 Borrow such a variant field class's selector field path with
942 bt_field_class_variant_with_selector_field_borrow_selector_field_path_const().
946 Variant field classes have the following common property:
950 \anchor api-tir-fc-var-prop-opts
954 Options of the variant field class.
958 - A name, unique amongst all the option names of the same
963 If the variant field class is linked to a selector field class, then
964 each option also has an \bt_int_rs. In that case, the ranges of a
965 given option cannot overlap any range of any other option.
967 A variant field class must contain at least one option.
969 Depending on whether or not the variant field class has a selector
970 field class, append an option to a variant field class
971 with bt_field_class_variant_without_selector_append_option(),
972 bt_field_class_variant_with_selector_field_integer_unsigned_append_option(),
974 bt_field_class_variant_with_selector_field_integer_signed_append_option().
976 Get the number of options contained in a variant field class
977 with bt_field_class_variant_get_option_count().
979 A variant field class option is a
980 \ref api-fund-unique-object "unique object": it
981 belongs to the variant field class which contains it.
983 Borrow any variant field class's option with
984 bt_field_class_variant_borrow_option_by_index(),
985 bt_field_class_variant_borrow_option_by_name(),
986 bt_field_class_variant_borrow_option_by_index_const(), and
987 bt_field_class_variant_borrow_option_by_name_const().
989 Those functions return the common #bt_field_class_variant_option
990 type. Get the name of a variant field class option with
991 bt_field_class_variant_option_get_name(). Borrow a variant field
992 class option's field class with
993 bt_field_class_variant_option_borrow_field_class() and
994 bt_field_class_variant_option_borrow_field_class_const().
996 Borrow the option of a variant field classes with a selector field
998 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(),
999 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const(),
1000 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(), or
1001 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const(),
1002 depending on the selector field class's type.
1004 Those functions return the
1005 #bt_field_class_variant_with_selector_field_integer_unsigned_option or
1006 #bt_field_class_variant_with_selector_field_integer_signed_option type.
1007 \ref api-fund-c-typing "Upcast" those types to the
1008 #bt_field_class_variant_option type with
1009 bt_field_class_variant_with_selector_field_integer_unsigned_option_as_option_const()
1011 bt_field_class_variant_with_selector_field_integer_signed_option_as_option_const().
1013 Borrow the option's ranges from a variant field class with a
1014 selector field class with
1015 bt_field_class_variant_with_selector_field_integer_unsigned_option_borrow_ranges_const()
1017 bt_field_class_variant_with_selector_field_integer_signed_option_borrow_ranges_const().
1019 Set a variant field class option's user attributes with
1020 bt_field_class_variant_option_set_user_attributes().
1022 Borrow a variant field class option's user attributes with
1023 bt_field_class_variant_option_borrow_user_attributes() and
1024 bt_field_class_variant_option_borrow_user_attributes_const().
1028 <h1>\anchor api-tir-fc-link Field classes with links to other field classes</h1>
1030 \bt_cp_darray_fc, \bt_p_opt_fc, and \bt_p_var_fc \em can have links to
1031 other, preceding field classes.
1033 When a field class A has a link to another field class B, then
1034 an instance (\bt_field) of A has a link to an instance of B.
1036 This feature exists so that the linked field can contain the value of a
1037 dynamic property of the field. Those properties are:
1040 <dt>\bt_c_darray_field</dt>
1042 The linked field, a \bt_uint_field, contains the \b length of the
1043 dynamic array field.
1046 <dt>\bt_c_opt_field</dt>
1048 The linked field, either a \bt_bool_field or an \bt_int_field,
1049 indicates whether or not the option field has a field.
1052 <dt>\bt_c_var_field</dt>
1054 The linked field, an \bt_int_field, indicates the variant field's
1055 current selected field.
1059 Having a linked field class is <em>optional</em>: you always set the
1060 field properties with a dedicated function anyway. For example, even if
1061 a dynamic array field is linked to a preceding length field, you must
1062 still set its length with bt_field_array_dynamic_set_length(). In that
1063 case, the value of the length field must match what you pass to
1064 bt_field_array_dynamic_set_length().
1066 The purpose of this feature is to eventually save space when a
1067 \bt_sink_comp writes trace files: if the trace format can convey that
1068 a preceding, existing field represents the length of a dynamic array
1069 field, then the sink component doesn't need to write the dynamic array
1070 field's length twice. This is the case of the
1071 <a href="https://diamon.org/ctf/">Common Trace Format</a>, for
1074 @image html darray-link.png "A dynamic array field class linked to an unsigned integer field class."
1076 To link a field class A to a preceding field class B, pass
1077 field class B when you create field class A. For example, pass
1078 the \bt_uint_fc to bt_field_class_array_dynamic_create() to create a
1079 \bt_darray_fc with a length field.
1081 When you call bt_stream_class_set_packet_context_field_class(),
1082 bt_stream_class_set_event_common_context_field_class(),
1083 bt_event_class_set_specific_context_field_class(), or
1084 bt_event_class_set_payload_field_class() with a field class containing
1085 a field class A with a linked field class B, the path to
1086 B becomes available in A. The functions to borrow this field path are:
1088 - bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const()
1089 - bt_field_class_option_with_selector_field_borrow_selector_field_path_const()
1090 - bt_field_class_variant_with_selector_field_borrow_selector_field_path_const()
1092 A field path indicates how to reach a linked field from a given
1093 root <em>scope</em>. The available scopes are:
1096 <dt>#BT_FIELD_PATH_SCOPE_PACKET_CONTEXT</dt>
1098 Packet context field.
1100 See bt_packet_borrow_context_field_const().
1103 <dt>#BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT</dt>
1105 Event common context field.
1107 See bt_event_borrow_common_context_field_const().
1110 <dt>#BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT</dt>
1112 Event specific context field.
1114 See bt_event_borrow_specific_context_field_const().
1117 <dt>#BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD</dt>
1119 Event payload field.
1121 See bt_event_borrow_payload_field_const().
1125 The rules regarding field class A vs. field class B (linked
1128 - If A is within a packet context field class, B must also be in the
1129 same packet context field class.
1131 See bt_stream_class_set_packet_context_field_class().
1133 - If A is within a event common context field class, B must be in one
1136 - The same event common context field class.
1137 - The packet context field class of the same \bt_stream_cls.
1139 See bt_stream_class_set_event_common_context_field_class().
1141 - If A is within an event specific context field class, B must be in
1144 - The same event specific context field class.
1145 - The event common context field class of the same stream class.
1146 - The packet context field class of the same stream class.
1148 See bt_event_class_set_specific_context_field_class().
1150 - If A is within an event payload field class, B must be in one of:
1152 - The same event payload field class.
1153 - The event specific context field class of the same \bt_ev_cls.
1154 - The event common context field class of the same stream class.
1155 - The packet context field class of the same stream class.
1157 See bt_event_class_set_payload_field_class().
1159 - If both A and B are in the same scope, then:
1161 - The lowest common ancestor field class of A and B must be a
1166 Considering that the members of a structure field class are ordered,
1167 then B must be part of a member that's before the member which
1168 contains A in their lowest common ancestor structure field class.
1170 - The path from the lowest common ancestor structure field class of A
1171 and B to A and to B must only contain structure field classes.
1173 - If A is in a different scope than B, the path from the root scope of B
1174 to B must only contain structure field classes.
1183 @typedef struct bt_field_class bt_field_class;
1198 Field class type enumerators.
1200 typedef enum bt_field_class_type
{
1205 BT_FIELD_CLASS_TYPE_BOOL
= 1ULL << 0,
1211 BT_FIELD_CLASS_TYPE_BIT_ARRAY
= 1ULL << 1,
1217 No field class has this type: use it with
1218 bt_field_class_type_is().
1220 BT_FIELD_CLASS_TYPE_INTEGER
= 1ULL << 2,
1226 This type conceptually inherits #BT_FIELD_CLASS_TYPE_INTEGER.
1228 BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER
= (1ULL << 3) | BT_FIELD_CLASS_TYPE_INTEGER
,
1234 This type conceptually inherits #BT_FIELD_CLASS_TYPE_INTEGER.
1236 BT_FIELD_CLASS_TYPE_SIGNED_INTEGER
= (1ULL << 4) | BT_FIELD_CLASS_TYPE_INTEGER
,
1242 This type conceptually inherits #BT_FIELD_CLASS_TYPE_INTEGER.
1244 No field class has this type: use it with
1245 bt_field_class_type_is().
1247 BT_FIELD_CLASS_TYPE_ENUMERATION
= 1ULL << 5,
1253 This type conceptually inherits #BT_FIELD_CLASS_TYPE_ENUMERATION
1254 and #BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER.
1256 BT_FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION
= BT_FIELD_CLASS_TYPE_ENUMERATION
| BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER
,
1262 This type conceptually inherits #BT_FIELD_CLASS_TYPE_ENUMERATION
1263 and #BT_FIELD_CLASS_TYPE_SIGNED_INTEGER.
1265 BT_FIELD_CLASS_TYPE_SIGNED_ENUMERATION
= BT_FIELD_CLASS_TYPE_ENUMERATION
| BT_FIELD_CLASS_TYPE_SIGNED_INTEGER
,
1271 No field class has this type: use it with
1272 bt_field_class_type_is().
1274 BT_FIELD_CLASS_TYPE_REAL
= 1ULL << 6,
1278 Single-precision \bt_real_fc.
1280 This type conceptually inherits #BT_FIELD_CLASS_TYPE_REAL.
1282 BT_FIELD_CLASS_TYPE_SINGLE_PRECISION_REAL
= (1ULL << 7) | BT_FIELD_CLASS_TYPE_REAL
,
1286 Double-precision \bt_real_fc.
1288 This type conceptually inherits #BT_FIELD_CLASS_TYPE_REAL.
1290 BT_FIELD_CLASS_TYPE_DOUBLE_PRECISION_REAL
= (1ULL << 8) | BT_FIELD_CLASS_TYPE_REAL
,
1296 BT_FIELD_CLASS_TYPE_STRING
= 1ULL << 9,
1302 BT_FIELD_CLASS_TYPE_STRUCTURE
= 1ULL << 10,
1308 No field class has this type: use it with
1309 bt_field_class_type_is().
1311 BT_FIELD_CLASS_TYPE_ARRAY
= 1ULL << 11,
1317 This type conceptually inherits #BT_FIELD_CLASS_TYPE_ARRAY.
1319 BT_FIELD_CLASS_TYPE_STATIC_ARRAY
= (1ULL << 12) | BT_FIELD_CLASS_TYPE_ARRAY
,
1325 This type conceptually inherits #BT_FIELD_CLASS_TYPE_ARRAY.
1327 No field class has this type: use it with
1328 bt_field_class_type_is().
1330 BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY
= (1ULL << 13) | BT_FIELD_CLASS_TYPE_ARRAY
,
1334 \bt_c_darray_fc (without a length field).
1336 This type conceptually inherits
1337 #BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY.
1339 BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD
= (1ULL << 14) | BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY
,
1343 \bt_c_darray_fc (with a length field).
1345 This type conceptually inherits
1346 #BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY.
1348 BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD
= (1ULL << 15) | BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY
,
1354 No field class has this type: use it with
1355 bt_field_class_type_is().
1357 BT_FIELD_CLASS_TYPE_OPTION
= 1ULL << 16,
1361 \bt_c_opt_fc (without a selector field).
1363 BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD
= (1ULL << 17) | BT_FIELD_CLASS_TYPE_OPTION
,
1367 \bt_c_opt_fc (with a selector field).
1369 This type conceptually inherits #BT_FIELD_CLASS_TYPE_OPTION.
1371 No field class has this type: use it with
1372 bt_field_class_type_is().
1374 BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD
= (1ULL << 18) | BT_FIELD_CLASS_TYPE_OPTION
,
1378 \bt_c_opt_fc (with a boolean selector field).
1380 This type conceptually inherits
1381 #BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD.
1383 BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD
= (1ULL << 19) | BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD
,
1387 \bt_c_opt_fc (with an integer selector field).
1389 This type conceptually inherits
1390 #BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD.
1392 No field class has this type: use it with
1393 bt_field_class_type_is().
1395 BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD
= (1ULL << 20) | BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD
,
1399 \bt_c_opt_fc (with an unsigned integer selector field).
1401 This type conceptually inherits
1402 #BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD.
1404 BT_FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
= (1ULL << 21) | BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD
,
1408 \bt_c_opt_fc (with a signed integer selector field).
1410 This type conceptually inherits
1411 #BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD.
1413 BT_FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD
= (1ULL << 22) | BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD
,
1419 No field class has this type: use it with
1420 bt_field_class_type_is().
1422 BT_FIELD_CLASS_TYPE_VARIANT
= 1ULL << 23,
1426 \bt_c_var_fc (without a selector field).
1428 BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD
= (1ULL << 24) | BT_FIELD_CLASS_TYPE_VARIANT
,
1432 \bt_c_var_fc (with a selector field).
1434 This type conceptually inherits
1435 #BT_FIELD_CLASS_TYPE_VARIANT.
1437 No field class has this type: use it with
1438 bt_field_class_type_is().
1440 BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD
= (1ULL << 25) | BT_FIELD_CLASS_TYPE_VARIANT
,
1444 \bt_c_var_fc (with an integer selector field).
1446 This type conceptually inherits
1447 #BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD.
1449 No field class has this type: use it with
1450 bt_field_class_type_is().
1452 BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD
= (1ULL << 26) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD
,
1456 \bt_c_opt_fc (with an unsigned integer selector field).
1458 This type conceptually inherits
1459 #BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD.
1461 BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
= (1ULL << 27) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD
,
1465 \bt_c_opt_fc (with a signed integer selector field).
1467 This type conceptually inherits
1468 #BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD.
1470 BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD
= (1ULL << 28) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD
,
1473 * Make sure the enumeration type is a 64-bit integer in case
1474 * the project needs field class types in the future.
1476 * This is not part of the API.
1478 __BT_FIELD_CLASS_TYPE_BIG_VALUE
= 1ULL << 62,
1479 } bt_field_class_type
;
1483 Returns the type enumerator of the field class \bt_p{field_class}.
1485 @param[in] field_class
1486 Field class of which to get the type enumerator
1489 Type enumerator of \bt_p{field_class}.
1491 @bt_pre_not_null{field_class}
1493 @sa bt_field_class_type_is() —
1494 Returns whether or not the type of a field class conceptually is a
1497 extern bt_field_class_type
bt_field_class_get_type(
1498 const bt_field_class
*field_class
);
1502 Returns whether or not the field class type \bt_p{type} conceptually
1503 \em is the field class type \bt_p{other_type}.
1505 For example, an \bt_uint_fc conceptually \em is an integer field class,
1509 bt_field_class_type_is(BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER, BT_FIELD_CLASS_TYPE_INTEGER)
1515 Field class type to check against \bt_p{other_type}.
1516 @param[in] other_type
1517 Field class type against which to check \bt_p{type}.
1520 #BT_TRUE if \bt_p{type} conceptually \em is \bt_p{other_type}.
1522 @sa bt_field_class_get_type() —
1523 Returns the type enumerator of a field class.
1526 bt_bool
bt_field_class_type_is(const bt_field_class_type type
,
1527 const bt_field_class_type other_type
)
1529 return (type
& other_type
) == other_type
;
1535 @name Common property
1541 Sets the user attributes of the field class \bt_p{field_class} to
1542 \bt_p{user_attributes}.
1544 See the \ref api-tir-fc-prop-user-attrs "user attributes" property.
1547 When you create a field class with one of the
1548 <code>bt_field_class_*_create()</code> functions, the field class's
1549 initial user attributes is an empty \bt_map_val. Therefore you can
1550 borrow it with bt_field_class_borrow_user_attributes() and fill it
1551 directly instead of setting a new one with this function.
1553 @param[in] field_class
1554 Field class of which to set the user attributes to
1555 \bt_p{user_attributes}.
1556 @param[in] user_attributes
1557 New user attributes of \bt_p{field_class}.
1559 @bt_pre_not_null{field_class}
1560 @bt_pre_hot{field_class}
1561 @bt_pre_not_null{user_attributes}
1562 @bt_pre_is_map_val{user_attributes}
1564 @sa bt_field_class_borrow_user_attributes() —
1565 Borrows the user attributes of a field class.
1567 extern void bt_field_class_set_user_attributes(
1568 bt_field_class
*field_class
, const bt_value
*user_attributes
);
1572 Borrows the user attributes of the field class \bt_p{field_class}.
1574 See the \ref api-tir-fc-prop-user-attrs "user attributes" property.
1577 When you create a field class with one of the
1578 <code>bt_field_class_*_create()</code> functions, the field class's
1579 initial user attributes is an empty \bt_map_val.
1581 @param[in] field_class
1582 Field class from which to borrow the user attributes.
1585 User attributes of \bt_p{field_class} (a \bt_map_val).
1587 @bt_pre_not_null{field_class}
1589 @sa bt_field_class_set_user_attributes() —
1590 Sets the user attributes of a field class.
1591 @sa bt_field_class_borrow_user_attributes_const() —
1592 \c const version of this function.
1594 extern bt_value
*bt_field_class_borrow_user_attributes(
1595 bt_field_class
*field_class
);
1599 Borrows the user attributes of the field class \bt_p{field_class}
1602 See bt_field_class_borrow_user_attributes().
1604 extern const bt_value
*bt_field_class_borrow_user_attributes_const(
1605 const bt_field_class
*field_class
);
1610 @name Boolean field class
1616 Creates a \bt_bool_fc from the trace class \bt_p{trace_class}.
1618 On success, the returned boolean field class has the following
1626 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
1627 <td>Empty \bt_map_val
1630 @param[in] trace_class
1631 Trace class from which to create a boolean field class.
1634 New boolean field class reference, or \c NULL on memory error.
1636 @bt_pre_not_null{trace_class}
1638 extern bt_field_class
*bt_field_class_bool_create(
1639 bt_trace_class
*trace_class
);
1646 @name Bit array field class
1652 Creates a \bt_ba_fc with the length \bt_p{length} from the trace
1653 class \bt_p{trace_class}.
1655 On success, the returned bit array field class has the following
1663 <td>\ref api-tir-fc-ba-prop-len "Length"
1666 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
1667 <td>Empty \bt_map_val
1670 @param[in] trace_class
1671 Trace class from which to create a bit array field class.
1673 Length (number of bits) of the instances of the bit array field
1677 New bit array field class reference, or \c NULL on memory error.
1679 @bt_pre_not_null{trace_class}
1681 0 < \bt_p{length} ≤ 64.
1683 extern bt_field_class
*bt_field_class_bit_array_create(
1684 bt_trace_class
*trace_class
, uint64_t length
);
1688 Returns the length of the \bt_ba_fc \bt_p{field_class}.
1690 See the \ref api-tir-fc-ba-prop-len "length" property.
1692 @param[in] field_class
1693 Bit array field class of which to get the length.
1696 Length of \bt_p{field_class}.
1698 @bt_pre_not_null{field_class}
1699 @bt_pre_is_ba_fc{field_class}
1701 extern uint64_t bt_field_class_bit_array_get_length(
1702 const bt_field_class
*field_class
);
1709 @name Integer field class
1715 Sets the field value range of the \bt_int_fc \bt_p{field_class}
1718 See the \ref api-tir-fc-int-prop-size "field value range" property.
1720 @param[in] field_class
1721 Integer field class of which to set the field value range to
1728 <dt>Unsigned integer field class</dt>
1729 <dd>[0, 2<sup><em>N</em></sup> − 1]</dd>
1731 <dt>Signed integer field class</dt>
1732 <dd>[−2<sup><em>N</em> − 1</sup>, 2<sup><em>N</em> − 1</sup> − 1]</dd>
1736 @bt_pre_not_null{field_class}
1737 @bt_pre_hot{field_class}
1738 @bt_pre_is_int_fc{field_class}
1742 @sa bt_field_class_integer_get_field_value_range() —
1743 Returns the field value range of an integer field class.
1745 extern void bt_field_class_integer_set_field_value_range(
1746 bt_field_class
*field_class
, uint64_t n
);
1750 Returns the field value range of the \bt_int_fc \bt_p{field_class}.
1752 See the \ref api-tir-fc-int-prop-size "field value range" property.
1754 @param[in] field_class
1755 Integer field class of which to get the field value range.
1759 Field value range of \bt_p{field_class}, that is, \em N in:
1762 <dt>Unsigned integer field class</dt>
1763 <dd>[0, 2<sup><em>N</em></sup> − 1]</dd>
1765 <dt>Signed integer field class</dt>
1766 <dd>[−2<sup><em>N</em></sup>, 2<sup><em>N</em></sup> − 1]</dd>
1770 @bt_pre_not_null{field_class}
1771 @bt_pre_is_int_fc{field_class}
1773 @sa bt_field_class_integer_set_field_value_range() —
1774 Sets the field value range of an integer field class.
1776 extern uint64_t bt_field_class_integer_get_field_value_range(
1777 const bt_field_class
*field_class
);
1781 Integer field class preferred display bases.
1783 typedef enum bt_field_class_integer_preferred_display_base
{
1788 BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_BINARY
= 2,
1794 BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_OCTAL
= 8,
1800 BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
= 10,
1806 BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_HEXADECIMAL
= 16,
1807 } bt_field_class_integer_preferred_display_base
;
1811 Sets the preferred display base of the \bt_int_fc \bt_p{field_class}
1812 to \bt_p{preferred_display_base}.
1814 See the \ref api-tir-fc-int-prop-base "preferred display base" property.
1816 @param[in] field_class
1817 Integer field class of which to set the preferred display base to
1818 \bt_p{preferred_display_base}.
1819 @param[in] preferred_display_base
1820 New preferred display base of \bt_p{field_class}.
1822 @bt_pre_not_null{field_class}
1823 @bt_pre_hot{field_class}
1824 @bt_pre_is_int_fc{field_class}
1826 @sa bt_field_class_integer_get_preferred_display_base() —
1827 Returns the preferred display base of an integer field class.
1829 extern void bt_field_class_integer_set_preferred_display_base(
1830 bt_field_class
*field_class
,
1831 bt_field_class_integer_preferred_display_base preferred_display_base
);
1835 Returns the preferred display base of the \bt_int_fc
1838 See the \ref api-tir-fc-int-prop-base "preferred display base" property.
1840 @param[in] field_class
1841 Integer field class of which to get the preferred display base.
1843 @retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_BINARY
1845 @retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_OCTAL
1847 @retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
1849 @retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_HEXADECIMAL
1852 @bt_pre_not_null{field_class}
1853 @bt_pre_is_int_fc{field_class}
1855 @sa bt_field_class_integer_set_preferred_display_base() —
1856 Sets the preferred display base of an integer field class.
1858 extern bt_field_class_integer_preferred_display_base
1859 bt_field_class_integer_get_preferred_display_base(
1860 const bt_field_class
*field_class
);
1865 @name Unsigned integer field class
1871 Creates an \bt_uint_fc from the trace class \bt_p{trace_class}.
1873 On success, the returned unsigned integer field class has the following
1881 <td>\ref api-tir-fc-int-prop-size "Field value range"
1882 <td>[0, 2<sup>64</sup> − 1]
1884 <td>\ref api-tir-fc-int-prop-base "Preferred display base"
1885 <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
1887 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
1888 <td>Empty \bt_map_val
1891 @param[in] trace_class
1892 Trace class from which to create an unsigned integer field class.
1895 New unsigned integer field class reference, or \c NULL on memory error.
1897 @bt_pre_not_null{trace_class}
1899 extern bt_field_class
*bt_field_class_integer_unsigned_create(
1900 bt_trace_class
*trace_class
);
1905 @name Signed integer field class
1911 Creates an \bt_sint_fc from the trace class \bt_p{trace_class}.
1913 On success, the returned signed integer field class has the following
1921 <td>\ref api-tir-fc-int-prop-size "Field value range"
1922 <td>[−2<sup>63</sup>, 2<sup>63</sup> − 1]
1924 <td>\ref api-tir-fc-int-prop-base "Preferred display base"
1925 <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
1927 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
1928 <td>Empty \bt_map_val
1931 @param[in] trace_class
1932 Trace class from which to create a signed integer field class.
1935 New signed integer field class reference, or \c NULL on memory error.
1937 @bt_pre_not_null{trace_class}
1939 extern bt_field_class
*bt_field_class_integer_signed_create(
1940 bt_trace_class
*trace_class
);
1945 @name Single-precision real field class
1951 Creates a single-precision \bt_real_fc from the trace class
1954 On success, the returned single-precision real field class has the
1955 following property value:
1962 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
1963 <td>Empty \bt_map_val
1966 @param[in] trace_class
1967 Trace class from which to create a single-preicision real
1971 New single-precision real field class reference, or \c NULL on
1974 @bt_pre_not_null{trace_class}
1976 extern bt_field_class
*bt_field_class_real_single_precision_create(
1977 bt_trace_class
*trace_class
);
1982 @name Double-precision real field class
1988 Creates a double-precision \bt_real_fc from the trace class
1991 On success, the returned double-precision real field class has the
1992 following property value:
1999 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2000 <td>Empty \bt_map_val
2003 @param[in] trace_class
2004 Trace class from which to create a double-preicision real
2008 New double-precision real field class reference, or \c NULL on
2011 @bt_pre_not_null{trace_class}
2013 extern bt_field_class
*bt_field_class_real_double_precision_create(
2014 bt_trace_class
*trace_class
);
2019 @name Enumeration field class
2025 Array of \c const \bt_enum_fc labels.
2027 Returned by bt_field_class_enumeration_unsigned_get_mapping_labels_for_value()
2028 and bt_field_class_enumeration_signed_get_mapping_labels_for_value().
2030 typedef char const * const *bt_field_class_enumeration_mapping_label_array
;
2035 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value()
2037 bt_field_class_enumeration_signed_get_mapping_labels_for_value().
2039 typedef enum bt_field_class_enumeration_get_mapping_labels_for_value_status
{
2044 BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2050 BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2051 } bt_field_class_enumeration_get_mapping_labels_for_value_status
;
2055 Status codes for bt_field_class_enumeration_unsigned_add_mapping()
2056 and bt_field_class_enumeration_signed_add_mapping().
2058 typedef enum bt_field_class_enumeration_add_mapping_status
{
2063 BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2069 BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2070 } bt_field_class_enumeration_add_mapping_status
;
2075 @name Enumeration field class mapping
2080 @typedef struct bt_field_class_enumeration_mapping bt_field_class_enumeration_mapping;
2083 Enumeration field class mapping.
2088 Returns the number of mappings contained in the \bt_enum_fc
2091 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2093 @param[in] field_class
2094 Enumeration field class of which to get the number of contained
2098 Number of contained mappings in \bt_p{field_class}.
2100 @bt_pre_not_null{field_class}
2101 @bt_pre_is_enum_fc{field_class}
2103 extern uint64_t bt_field_class_enumeration_get_mapping_count(
2104 const bt_field_class
*field_class
);
2108 Returns the label of the \bt_enum_fc mapping \bt_p{mapping}.
2110 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2113 Enumeration field class mapping of which to get the label.
2117 Label of \bt_p{mapping}.
2119 The returned pointer remains valid as long as \bt_p{mapping} exists.
2122 @bt_pre_not_null{mapping}
2124 extern const char *bt_field_class_enumeration_mapping_get_label(
2125 const bt_field_class_enumeration_mapping
*mapping
);
2130 @name Unsigned enumeration field class
2136 Creates an \bt_uenum_fc from the trace class \bt_p{trace_class}.
2138 On success, the returned unsigned enumeration field class has the
2139 following property values:
2146 <td>\ref api-tir-fc-int-prop-size "Field value range"
2147 <td>[0, 2<sup>64</sup> − 1]
2149 <td>\ref api-tir-fc-int-prop-base "Preferred display base"
2150 <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
2152 <td>\ref api-tir-fc-enum-prop-mappings "Mappings"
2155 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2156 <td>Empty \bt_map_val
2159 @param[in] trace_class
2160 Trace class from which to create an unsigned enumeration field
2164 New unsigned enumeration field class reference, or \c NULL on memory
2167 @bt_pre_not_null{trace_class}
2169 extern bt_field_class
*bt_field_class_enumeration_unsigned_create(
2170 bt_trace_class
*trace_class
);
2174 Adds a mapping to the \bt_uenum_fc \bt_p{field_class} having the
2175 label \bt_p{label} and the unsigned integer ranges \bt_p{ranges}.
2177 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2179 @param[in] field_class
2180 Unsigned enumeration field class to which to add a mapping having
2181 the label \bt_p{label} and the integer ranges \bt_p{ranges}.
2183 Label of the mapping to add to \bt_p{field_class} (copied).
2185 Unsigned integer ranges of the mapping to add to
2188 @retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK
2190 @retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR
2193 @bt_pre_not_null{field_class}
2194 @bt_pre_hot{field_class}
2195 @bt_pre_is_uenum_fc{field_class}
2196 @bt_pre_not_null{label}
2198 \bt_p{field_class} has no mapping with the label \bt_p{label}.
2199 @bt_pre_not_null{ranges}
2201 \bt_p{ranges} contains one or more unsigned integer ranges.
2203 extern bt_field_class_enumeration_add_mapping_status
2204 bt_field_class_enumeration_unsigned_add_mapping(
2205 bt_field_class
*field_class
, const char *label
,
2206 const bt_integer_range_set_unsigned
*ranges
);
2210 Borrows the mapping at index \bt_p{index} from the
2211 \bt_uenum_fc \bt_p{field_class}.
2213 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2215 @param[in] field_class
2216 Unsigned enumeration field class from which to borrow the mapping at
2219 Index of the mapping to borrow from \bt_p{field_class}.
2223 \em Borrowed reference of the mapping of
2224 \bt_p{field_class} at index \bt_p{index}.
2226 The returned pointer remains valid as long as \bt_p{field_class}
2230 @bt_pre_not_null{field_class}
2231 @bt_pre_is_uenum_fc{field_class}
2233 \bt_p{index} is less than the number of mappings in
2234 \bt_p{field_class} (as returned by
2235 bt_field_class_enumeration_get_mapping_count()).
2237 @sa bt_field_class_enumeration_get_mapping_count() —
2238 Returns the number of mappings contained in an
2239 enumeration field class.
2241 extern const bt_field_class_enumeration_unsigned_mapping
*
2242 bt_field_class_enumeration_unsigned_borrow_mapping_by_index_const(
2243 const bt_field_class
*field_class
, uint64_t index
);
2247 Borrows the mapping having the label \bt_p{label} from the
2248 \bt_uenum_fc \bt_p{field_class}.
2250 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2252 If there's no mapping having the label \bt_p{label} in
2253 \bt_p{field_class}, this function returns \c NULL.
2255 @param[in] field_class
2256 Unsigned enumeration field class from which to borrow the mapping
2257 having the label \bt_p{label}.
2259 Label of the mapping to borrow from \bt_p{field_class}.
2263 \em Borrowed reference of the mapping of
2264 \bt_p{field_class} having the label \bt_p{label}, or \c NULL
2267 The returned pointer remains valid as long as \bt_p{field_class}
2271 @bt_pre_not_null{field_class}
2272 @bt_pre_is_uenum_fc{field_class}
2273 @bt_pre_not_null{label}
2275 extern const bt_field_class_enumeration_unsigned_mapping
*
2276 bt_field_class_enumeration_unsigned_borrow_mapping_by_label_const(
2277 const bt_field_class
*field_class
, const char *label
);
2281 Returns an array of all the labels of the mappings of the
2282 \bt_uenum_fc \bt_p{field_class} of which the \bt_p_uint_rg contain
2283 the integral value \bt_p{value}.
2285 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2287 This function sets \bt_p{*labels} to the resulting array and
2288 \bt_p{*count} to the number of labels in \bt_p{*labels}.
2290 On success, if there's no mapping ranges containing the value
2291 \bt_p{value}, \bt_p{*count} is 0.
2293 @param[in] field_class
2294 Unsigned enumeration field class from which to get the labels of the
2295 mappings of which the ranges contain \bt_p{value}.
2297 Value for which to get the mapped labels in \bt_p{field_class}.
2300 <strong>On success</strong>, \bt_p{*labels}
2301 is an array of labels of the mappings of \bt_p{field_class}
2302 containing \bt_p{value}.
2304 The number of labels in \bt_p{*labels} is \bt_p{*count}.
2306 The array is owned by \bt_p{field_class} and remains valid as long
2309 - \bt_p{field_class} is not modified.
2310 - You don't call this function again with \bt_p{field_class}.
2313 <strong>On success</strong>, \bt_p{*count} is the number of labels
2314 in \bt_p{*labels} (can be 0).
2316 @retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK
2318 @retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR
2321 @bt_pre_not_null{field_class}
2322 @bt_pre_is_uenum_fc{field_class}
2323 @bt_pre_not_null{labels}
2324 @bt_pre_not_null{count}
2326 extern bt_field_class_enumeration_get_mapping_labels_for_value_status
2327 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value(
2328 const bt_field_class
*field_class
, uint64_t value
,
2329 bt_field_class_enumeration_mapping_label_array
*labels
,
2335 @name Unsigned enumeration field class mapping
2340 @typedef struct bt_field_class_enumeration_unsigned_mapping bt_field_class_enumeration_unsigned_mapping;
2343 Unsigned enumeration field class mapping.
2348 Borrows the \bt_p_uint_rg from the \bt_uenum_fc mapping
2351 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2354 Unsigned enumeration field class mapping from which to borrow the
2355 unsigned integer ranges.
2358 Unsigned integer ranges of \bt_p{mapping}.
2360 @bt_pre_not_null{mapping}
2362 extern const bt_integer_range_set_unsigned
*
2363 bt_field_class_enumeration_unsigned_mapping_borrow_ranges_const(
2364 const bt_field_class_enumeration_unsigned_mapping
*mapping
);
2368 \ref api-fund-c-typing "Upcasts" the \bt_uenum_fc mapping
2369 \bt_p{mapping} to the common #bt_field_class_enumeration_mapping
2372 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2376 Unsigned enumeration field class mapping to upcast.
2382 \bt_p{mapping} as a common enumeration field class mapping.
2385 const bt_field_class_enumeration_mapping
*
2386 bt_field_class_enumeration_unsigned_mapping_as_mapping_const(
2387 const bt_field_class_enumeration_unsigned_mapping
*mapping
)
2389 return __BT_UPCAST_CONST(bt_field_class_enumeration_mapping
, mapping
);
2395 @name Signed enumeration field class
2401 Creates a \bt_senum_fc from the trace class \bt_p{trace_class}.
2403 On success, the returned signed enumeration field class has the
2404 following property values:
2411 <td>\ref api-tir-fc-int-prop-size "Field value range"
2412 <td>[−2<sup>63</sup>, 2<sup>63</sup> − 1]
2414 <td>\ref api-tir-fc-int-prop-base "Preferred display base"
2415 <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
2417 <td>\ref api-tir-fc-enum-prop-mappings "Mappings"
2420 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2421 <td>Empty \bt_map_val
2424 @param[in] trace_class
2425 Trace class from which to create a signed enumeration field
2429 New signed enumeration field class reference, or \c NULL on memory
2432 @bt_pre_not_null{trace_class}
2434 extern bt_field_class
*bt_field_class_enumeration_signed_create(
2435 bt_trace_class
*trace_class
);
2439 Adds a mapping to the \bt_senum_fc \bt_p{field_class} having the
2440 label \bt_p{label} and the \bt_p_sint_rg \bt_p{ranges}.
2442 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2444 @param[in] field_class
2445 Signed enumeration field class to which to add a mapping having
2446 the label \bt_p{label} and the integer ranges \bt_p{ranges}.
2448 Label of the mapping to add to \bt_p{field_class} (copied).
2450 Signed integer ranges of the mapping to add to
2453 @retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK
2455 @retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR
2458 @bt_pre_not_null{field_class}
2459 @bt_pre_hot{field_class}
2460 @bt_pre_is_senum_fc{field_class}
2461 @bt_pre_not_null{label}
2463 \bt_p{field_class} has no mapping with the label \bt_p{label}.
2464 @bt_pre_not_null{ranges}
2466 \bt_p{ranges} contains one or more signed integer ranges.
2468 extern bt_field_class_enumeration_add_mapping_status
2469 bt_field_class_enumeration_signed_add_mapping(
2470 bt_field_class
*field_class
, const char *label
,
2471 const bt_integer_range_set_signed
*ranges
);
2475 Borrows the mapping at index \bt_p{index} from the
2476 \bt_senum_fc \bt_p{field_class}.
2478 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2480 @param[in] field_class
2481 Signed enumeration field class from which to borrow the mapping at
2484 Index of the mapping to borrow from \bt_p{field_class}.
2488 \em Borrowed reference of the mapping of
2489 \bt_p{field_class} at index \bt_p{index}.
2491 The returned pointer remains valid as long as \bt_p{field_class}
2495 @bt_pre_not_null{field_class}
2496 @bt_pre_is_senum_fc{field_class}
2498 \bt_p{index} is less than the number of mappings in
2499 \bt_p{field_class} (as returned by
2500 bt_field_class_enumeration_get_mapping_count()).
2502 @sa bt_field_class_enumeration_get_mapping_count() —
2503 Returns the number of mappings contained in an
2504 enumeration field class.
2506 extern const bt_field_class_enumeration_signed_mapping
*
2507 bt_field_class_enumeration_signed_borrow_mapping_by_index_const(
2508 const bt_field_class
*field_class
, uint64_t index
);
2512 Borrows the mapping having the label \bt_p{label} from the
2513 \bt_senum_fc \bt_p{field_class}.
2515 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2517 If there's no mapping having the label \bt_p{label} in
2518 \bt_p{field_class}, this function returns \c NULL.
2520 @param[in] field_class
2521 Signed enumeration field class from which to borrow the mapping
2522 having the label \bt_p{label}.
2524 Label of the mapping to borrow from \bt_p{field_class}.
2528 \em Borrowed reference of the mapping of
2529 \bt_p{field_class} having the label \bt_p{label}, or \c NULL
2532 The returned pointer remains valid as long as \bt_p{field_class}
2536 @bt_pre_not_null{field_class}
2537 @bt_pre_is_senum_fc{field_class}
2538 @bt_pre_not_null{label}
2540 extern const bt_field_class_enumeration_signed_mapping
*
2541 bt_field_class_enumeration_signed_borrow_mapping_by_label_const(
2542 const bt_field_class
*field_class
, const char *label
);
2546 Returns an array of all the labels of the mappings of the
2547 \bt_senum_fc \bt_p{field_class} of which the \bt_p_sint_rg contain
2548 the integral value \bt_p{value}.
2550 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2552 This function sets \bt_p{*labels} to the resulting array and
2553 \bt_p{*count} to the number of labels in \bt_p{*labels}.
2555 On success, if there's no mapping ranges containing the value
2556 \bt_p{value}, \bt_p{*count} is 0.
2558 @param[in] field_class
2559 Signed enumeration field class from which to get the labels of the
2560 mappings of which the ranges contain \bt_p{value}.
2562 Value for which to get the mapped labels in \bt_p{field_class}.
2565 <strong>On success</strong>, \bt_p{*labels}
2566 is an array of labels of the mappings of \bt_p{field_class}
2567 containing \bt_p{value}.
2569 The number of labels in \bt_p{*labels} is \bt_p{*count}.
2571 The array is owned by \bt_p{field_class} and remains valid as long
2574 - \bt_p{field_class} is not modified.
2575 - You don't call this function again with \bt_p{field_class}.
2578 <strong>On success</strong>, \bt_p{*count} is the number of labels
2579 in \bt_p{*labels} (can be 0).
2581 @retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK
2583 @retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR
2586 @bt_pre_not_null{field_class}
2587 @bt_pre_is_senum_fc{field_class}
2588 @bt_pre_not_null{labels}
2589 @bt_pre_not_null{count}
2591 extern bt_field_class_enumeration_get_mapping_labels_for_value_status
2592 bt_field_class_enumeration_signed_get_mapping_labels_for_value(
2593 const bt_field_class
*field_class
, int64_t value
,
2594 bt_field_class_enumeration_mapping_label_array
*labels
,
2600 @name Signed enumeration field class mapping
2605 @typedef struct bt_field_class_enumeration_signed_mapping bt_field_class_enumeration_signed_mapping;
2608 Signed enumeration field class mapping.
2613 Borrows the \bt_p_sint_rg from the \bt_senum_fc mapping
2616 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2619 Signed enumeration field class mapping from which to borrow the
2620 signed integer ranges.
2623 Signed integer ranges of \bt_p{mapping}.
2625 @bt_pre_not_null{mapping}
2627 extern const bt_integer_range_set_signed
*
2628 bt_field_class_enumeration_signed_mapping_borrow_ranges_const(
2629 const bt_field_class_enumeration_signed_mapping
*mapping
);
2633 \ref api-fund-c-typing "Upcasts" the \bt_senum_fc mapping
2634 \bt_p{mapping} to the common #bt_field_class_enumeration_mapping
2637 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2641 Signed enumeration field class mapping to upcast.
2647 \bt_p{mapping} as a common enumeration field class mapping.
2650 const bt_field_class_enumeration_mapping
*
2651 bt_field_class_enumeration_signed_mapping_as_mapping_const(
2652 const bt_field_class_enumeration_signed_mapping
*mapping
)
2654 return __BT_UPCAST_CONST(bt_field_class_enumeration_mapping
, mapping
);
2660 @name String field class
2666 Creates a \bt_string_fc from the trace class \bt_p{trace_class}.
2668 On success, the returned string field class has the following property
2676 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2677 <td>Empty \bt_map_val
2680 @param[in] trace_class
2681 Trace class from which to create a string field class.
2684 New string field class reference, or \c NULL on memory error.
2686 @bt_pre_not_null{trace_class}
2688 extern bt_field_class
*bt_field_class_string_create(
2689 bt_trace_class
*trace_class
);
2694 @name Array field class
2700 Borrows the element field class from the \bt_array_fc
2703 See the \ref api-tir-fc-array-prop-elem-fc "element field class"
2706 @param[in] field_class
2707 Array field class from which to borrow the element field class.
2710 Element field class of \bt_p{field_class}.
2712 @bt_pre_not_null{field_class}
2713 @bt_pre_is_array_fc{field_class}
2715 @sa bt_field_class_array_borrow_element_field_class_const() —
2716 \c const version of this function.
2718 extern bt_field_class
*bt_field_class_array_borrow_element_field_class(
2719 bt_field_class
*field_class
);
2723 Borrows the element field class from the \bt_array_fc
2724 \bt_p{field_class} (\c const version).
2726 See bt_field_class_array_borrow_element_field_class().
2728 extern const bt_field_class
*
2729 bt_field_class_array_borrow_element_field_class_const(
2730 const bt_field_class
*field_class
);
2735 @name Static array field class
2741 Creates a \bt_sarray_fc having the element field class
2742 \bt_p{element_field_class} and the length \bt_p{length} from the
2743 trace class \bt_p{trace_class}.
2745 On success, the returned static array field class has the following
2753 <td>\ref api-tir-fc-array-prop-elem-fc "Element field class"
2754 <td>\bt_p{element_field_class}
2756 <td>\ref api-tir-fc-sarray-prop-len "Length"
2759 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2760 <td>Empty \bt_map_val
2763 @param[in] trace_class
2764 Trace class from which to create a static array field class.
2765 @param[in] element_field_class
2766 Class of the element fields of the instances of the static array
2767 field class to create.
2769 Length of the instances of the static array field class to create.
2772 New static array field class reference, or \c NULL on memory error.
2774 @bt_pre_not_null{trace_class}
2775 @bt_pre_not_null{element_field_class}
2776 bt_pre_fc_not_in_tc{element_field_class}
2778 @bt_post_success_frozen{element_field_class}
2780 extern bt_field_class
*bt_field_class_array_static_create(
2781 bt_trace_class
*trace_class
,
2782 bt_field_class
*element_field_class
, uint64_t length
);
2786 Returns the length of the \bt_sarray_fc \bt_p{field_class}.
2788 See the \ref api-tir-fc-sarray-prop-len "length" property.
2790 @param[in] field_class
2791 Static array field class of which to get the length.
2794 Length of \bt_p{field_class}.
2796 @bt_pre_not_null{field_class}
2797 @bt_pre_is_sarray_fc{field_class}
2799 extern uint64_t bt_field_class_array_static_get_length(
2800 const bt_field_class
*field_class
);
2805 @name Dynamic array field class
2811 Creates a \bt_darray_fc having the element field class
2812 \bt_p{element_field_class} from the trace class \bt_p{trace_class}.
2814 If \bt_p{length_field_class} is not \c NULL, then the created dynamic
2815 array field class has a linked length field class.
2817 \ref api-tir-fc-link "Field classes with links to other field classes"
2820 On success, the returned dynamic array field class has the following
2828 <td>\ref api-tir-fc-array-prop-elem-fc "Element field class"
2829 <td>\bt_p{element_field_class}
2831 <td>\ref api-tir-fc-darray-prop-len-fp "Length field path"
2833 \em None (if \bt_p{length_field_class} is not \c NULL, this
2834 property becomes available when the returned field class becomes
2835 part of an \bt_ev_cls or of a \bt_stream_cls)
2837 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2838 <td>Empty \bt_map_val
2841 @param[in] trace_class
2842 Trace class from which to create a dynamic array field class.
2843 @param[in] element_field_class
2844 Class of the element fields of the instances of the dynamic array
2845 field class to create.
2846 @param[in] length_field_class
2848 Linked length field class of the dynamic array field class to
2855 New dynamic array field class reference, or \c NULL on memory error.
2857 @bt_pre_not_null{trace_class}
2858 @bt_pre_not_null{element_field_class}
2859 @bt_pre_fc_not_in_tc{element_field_class}
2861 <strong>If \bt_p{length_field_class} is not \c NULL</strong>,
2862 \bt_p{length_field_class} is an \bt_uint_fc.
2864 @bt_post_success_frozen{element_field_class}
2865 @bt_post_success_frozen{length_field_class}
2867 extern bt_field_class
*bt_field_class_array_dynamic_create(
2868 bt_trace_class
*trace_class
,
2869 bt_field_class
*element_field_class
,
2870 bt_field_class
*length_field_class
);
2875 @name Dynamic array field class with length field
2881 Borrows the length field path from the \bt_darray_fc (with a length
2882 field) \bt_p{field_class}.
2884 See the \ref api-tir-fc-darray-prop-len-fp "length field path" property.
2886 This property is only available when a \bt_struct_fc containing
2887 (recursively) \bt_p{field_class} is passed to one of:
2889 - bt_stream_class_set_packet_context_field_class()
2890 - bt_stream_class_set_event_common_context_field_class()
2891 - bt_event_class_set_specific_context_field_class()
2892 - bt_event_class_set_payload_field_class()
2894 In the meantime, this function returns \c NULL.
2896 @param[in] field_class
2897 Dynamic array field class from which to borrow the length
2901 Length field path of \bt_p{field_class}.
2903 @bt_pre_not_null{field_class}
2904 @bt_pre_is_darray_wl_fc{field_class}
2906 extern const bt_field_path
*
2907 bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const(
2908 const bt_field_class
*field_class
);
2913 @name Structure field class
2919 Creates a \bt_struct_fc from the trace class \bt_p{trace_class}.
2921 On success, the returned structure field class has the following
2929 <td>\ref api-tir-fc-struct-prop-members "Members"
2932 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2933 <td>Empty \bt_map_val
2936 @param[in] trace_class
2937 Trace class from which to create a structure field class.
2940 New structure field class reference, or \c NULL on memory error.
2942 @bt_pre_not_null{trace_class}
2944 extern bt_field_class
*bt_field_class_structure_create(
2945 bt_trace_class
*trace_class
);
2949 Status codes for bt_field_class_structure_append_member().
2951 typedef enum bt_field_class_structure_append_member_status
{
2956 BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2962 BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2963 } bt_field_class_structure_append_member_status
;
2967 Appends a member to the \bt_struct_fc \bt_p{field_class} having the
2968 name \bt_p{name} and the field class \bt_p{member_field_class}.
2970 See the \ref api-tir-fc-struct-prop-members "members" property.
2972 @param[in] field_class
2973 Structure field class to which to append a member having
2974 the name \bt_p{name} and the field class \bt_p{member_field_class}.
2976 Name of the member to append to \bt_p{field_class} (copied).
2977 @param[in] member_field_class
2978 Field class of the member to append to \bt_p{field_class}.
2980 @retval #BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_OK
2982 @retval #BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_MEMORY_ERROR
2985 @bt_pre_not_null{field_class}
2986 @bt_pre_hot{field_class}
2987 @bt_pre_is_struct_fc{field_class}
2989 \bt_p{field_class} has no member with the name \bt_p{name}.
2990 @bt_pre_not_null{name}
2991 @bt_pre_not_null{member_field_class}
2992 @bt_pre_fc_not_in_tc{member_field_class}
2994 @bt_post_success_frozen{member_field_class}
2996 extern bt_field_class_structure_append_member_status
2997 bt_field_class_structure_append_member(
2998 bt_field_class
*field_class
,
2999 const char *name
, bt_field_class
*member_field_class
);
3003 Returns the number of members contained in the \bt_struct_fc
3006 See the \ref api-tir-fc-struct-prop-members "members" property.
3008 @param[in] field_class
3009 Structure field class of which to get the number of contained
3013 Number of contained members in \bt_p{field_class}.
3015 @bt_pre_not_null{field_class}
3016 @bt_pre_is_struct_fc{field_class}
3018 extern uint64_t bt_field_class_structure_get_member_count(
3019 const bt_field_class
*field_class
);
3023 Borrows the member at index \bt_p{index} from the
3024 \bt_struct_fc \bt_p{field_class}.
3026 See the \ref api-tir-fc-struct-prop-members "members" property.
3028 @param[in] field_class
3029 Structure field class from which to borrow the member at
3032 Index of the member to borrow from \bt_p{field_class}.
3036 \em Borrowed reference of the member of
3037 \bt_p{field_class} at index \bt_p{index}.
3039 The returned pointer remains valid as long as \bt_p{field_class}
3043 @bt_pre_not_null{field_class}
3044 @bt_pre_is_struct_fc{field_class}
3046 \bt_p{index} is less than the number of members in
3047 \bt_p{field_class} (as returned by
3048 bt_field_class_structure_get_member_count()).
3050 @sa bt_field_class_structure_get_member_count() —
3051 Returns the number of members contained in a structure field class.
3052 @sa bt_field_class_structure_borrow_member_by_index_const() —
3053 \c const version of this function.
3055 extern bt_field_class_structure_member
*
3056 bt_field_class_structure_borrow_member_by_index(
3057 bt_field_class
*field_class
, uint64_t index
);
3061 Borrows the member at index \bt_p{index} from the
3062 \bt_struct_fc \bt_p{field_class} (\c const version).
3064 See bt_field_class_structure_borrow_member_by_index().
3066 extern const bt_field_class_structure_member
*
3067 bt_field_class_structure_borrow_member_by_index_const(
3068 const bt_field_class
*field_class
, uint64_t index
);
3072 Borrows the member having the name \bt_p{name} from the
3073 \bt_struct_fc \bt_p{field_class}.
3075 See the \ref api-tir-fc-struct-prop-members "members" property.
3077 If there's no member having the name \bt_p{name} in
3078 \bt_p{field_class}, this function returns \c NULL.
3080 @param[in] field_class
3081 Structure field class from which to borrow the member having the
3084 Name of the member to borrow from \bt_p{field_class}.
3088 \em Borrowed reference of the member of
3089 \bt_p{field_class} having the name \bt_p{name}, or \c NULL
3092 The returned pointer remains valid as long as \bt_p{field_class}
3096 @bt_pre_not_null{field_class}
3097 @bt_pre_is_struct_fc{field_class}
3098 @bt_pre_not_null{name}
3100 @sa bt_field_class_structure_borrow_member_by_name_const() —
3101 \c const version of this function.
3103 extern bt_field_class_structure_member
*
3104 bt_field_class_structure_borrow_member_by_name(
3105 bt_field_class
*field_class
, const char *name
);
3109 Borrows the member having the name \bt_p{name} from the
3110 \bt_struct_fc \bt_p{field_class} (\c const version).
3112 See bt_field_class_structure_borrow_member_by_name().
3114 extern const bt_field_class_structure_member
*
3115 bt_field_class_structure_borrow_member_by_name_const(
3116 const bt_field_class
*field_class
, const char *name
);
3121 @name Structure field class member
3126 @typedef struct bt_field_class_structure_member bt_field_class_structure_member;
3129 Structure field class member.
3134 Returns the name of the \bt_struct_fc member \bt_p{member}.
3136 See the \ref api-tir-fc-struct-prop-members "members" property.
3139 Structure field class member of which to get the name.
3143 Name of \bt_p{member}.
3145 The returned pointer remains valid as long as \bt_p{member} exists.
3148 @bt_pre_not_null{member}
3150 extern const char *bt_field_class_structure_member_get_name(
3151 const bt_field_class_structure_member
*member
);
3155 Borrows the field class from the \bt_struct_fc member
3158 See the \ref api-tir-fc-struct-prop-members "members" property.
3161 Structure field class member from which to borrow the field class.
3164 Field class of \bt_p{member}.
3166 @bt_pre_not_null{member}
3168 @sa bt_field_class_structure_member_borrow_field_class_const() —
3169 \c const version of this function.
3171 extern bt_field_class
*
3172 bt_field_class_structure_member_borrow_field_class(
3173 bt_field_class_structure_member
*member
);
3177 Borrows the field class from the \bt_struct_fc member
3178 \bt_p{member} (\c const version).
3180 See bt_field_class_structure_member_borrow_field_class().
3182 extern const bt_field_class
*
3183 bt_field_class_structure_member_borrow_field_class_const(
3184 const bt_field_class_structure_member
*member
);
3188 Sets the user attributes of the \bt_struct_fc member \bt_p{member}
3189 to \bt_p{user_attributes}.
3191 See the \ref api-tir-fc-struct-prop-members "members" property.
3194 When you append a member to a structure field class with
3195 bt_field_class_structure_append_member(), the member's
3196 initial user attributes is an empty \bt_map_val. Therefore you can
3198 bt_field_class_structure_member_borrow_user_attributes() and fill it
3199 directly instead of setting a new one with this function.
3202 Structure field class member of which to set the user attributes to
3203 \bt_p{user_attributes}.
3204 @param[in] user_attributes
3205 New user attributes of \bt_p{member}.
3207 @bt_pre_not_null{member}
3209 @bt_pre_not_null{user_attributes}
3210 @bt_pre_is_map_val{user_attributes}
3212 @sa bt_field_class_structure_member_borrow_user_attributes() —
3213 Borrows the user attributes of a structure field class member.
3215 extern void bt_field_class_structure_member_set_user_attributes(
3216 bt_field_class_structure_member
*member
,
3217 const bt_value
*user_attributes
);
3221 Borrows the user attributes of the \bt_struct_fc member
3224 See the \ref api-tir-fc-struct-prop-members "members" property.
3227 When you append a member to a structure field class with
3228 bt_field_class_structure_append_member(), the member's
3229 initial user attributes is an empty \bt_map_val.
3232 Structure field class member from which to borrow the user
3236 User attributes of \bt_p{member} (a \bt_map_val).
3238 @bt_pre_not_null{member}
3240 @sa bt_field_class_structure_member_set_user_attributes() —
3241 Sets the user attributes of a structure field class member.
3242 @sa bt_field_class_structure_member_borrow_user_attributes_const() —
3243 \c const version of this function.
3246 bt_field_class_structure_member_borrow_user_attributes(
3247 bt_field_class_structure_member
*member
);
3251 Borrows the user attributes of the \bt_struct_fc member
3252 \bt_p{member} (\c const version).
3254 See bt_field_class_structure_member_borrow_user_attributes().
3256 extern const bt_value
*
3257 bt_field_class_structure_member_borrow_user_attributes_const(
3258 const bt_field_class_structure_member
*member
);
3263 @name Option field class
3269 Borrows the optional field class from the \bt_opt_fc
3272 See the \ref api-tir-fc-opt-prop-fc "optional field class" property.
3274 @param[in] field_class
3275 Option field class from which to borrow the optional field class.
3278 Optional field class of \bt_p{field_class}.
3280 @bt_pre_not_null{field_class}
3281 @bt_pre_is_opt_fc{field_class}
3283 @sa bt_field_class_option_borrow_field_class_const() —
3284 \c const version of this function.
3286 extern bt_field_class
*bt_field_class_option_borrow_field_class(
3287 bt_field_class
*field_class
);
3291 Borrows the optional field class from the \bt_opt_fc
3292 \bt_p{field_class} (\c const version).
3294 See bt_field_class_option_borrow_field_class().
3296 extern const bt_field_class
*
3297 bt_field_class_option_borrow_field_class_const(
3298 const bt_field_class
*field_class
);
3303 @name Option field class without a selector field
3309 Creates an \bt_opt_fc (without a selector field) having the optional
3310 field class \bt_p{optional_field_class} from the trace class
3313 On success, the returned option field class has the following property
3321 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
3322 <td>\bt_p{optional_field_class}
3324 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3325 <td>Empty \bt_map_val
3328 @param[in] trace_class
3329 Trace class from which to create an option field class.
3330 @param[in] optional_field_class
3331 Class of the optional fields of the instances of the option field
3335 New option field class reference, or \c NULL on memory error.
3337 @bt_pre_not_null{trace_class}
3338 @bt_pre_not_null{optional_field_class}
3339 @bt_pre_fc_not_in_tc{optional_field_class}
3341 @bt_post_success_frozen{optional_field_class}
3343 extern bt_field_class
*bt_field_class_option_without_selector_create(
3344 bt_trace_class
*trace_class
,
3345 bt_field_class
*optional_field_class
);
3350 @name Option field class with a selector field
3356 Borrows the selector field path from the \bt_opt_fc (with a selector
3357 field) \bt_p{field_class}.
3359 See the \ref api-tir-fc-opt-prop-sel-fp "selector field path" property.
3361 This property is only available when a \bt_struct_fc containing
3362 (recursively) \bt_p{field_class} is passed to one of:
3364 - bt_stream_class_set_packet_context_field_class()
3365 - bt_stream_class_set_event_common_context_field_class()
3366 - bt_event_class_set_specific_context_field_class()
3367 - bt_event_class_set_payload_field_class()
3369 In the meantime, this function returns \c NULL.
3371 @param[in] field_class
3372 Option field class from which to borrow the selector field path.
3375 Selector field path of \bt_p{field_class}.
3377 @bt_pre_not_null{field_class}
3378 @bt_pre_is_opt_ws_fc{field_class}
3380 extern const bt_field_path
*
3381 bt_field_class_option_with_selector_field_borrow_selector_field_path_const(
3382 const bt_field_class
*field_class
);
3387 @name Option field class with a boolean selector field
3393 Creates an \bt_opt_fc (with a boolean selector field) having the
3394 optional field class \bt_p{optional_field_class} from the trace
3395 class \bt_p{trace_class}.
3397 On success, the returned option field class has the following property
3405 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
3406 <td>\bt_p{optional_field_class}
3408 <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
3410 \em None (this property becomes available when the returned field
3411 class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
3413 <td>\ref api-tir-fc-opt-prop-sel-rev "Selector is reversed?"
3416 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3417 <td>Empty \bt_map_val
3420 @param[in] trace_class
3421 Trace class from which to create an option field class.
3422 @param[in] optional_field_class
3423 Class of the optional fields of the instances of the option field
3425 @param[in] selector_field_class
3426 Linked selector field class of the option field class to create.
3429 New option field class reference, or \c NULL on memory error.
3431 @bt_pre_not_null{trace_class}
3432 @bt_pre_not_null{optional_field_class}
3433 @bt_pre_fc_not_in_tc{optional_field_class}
3434 @bt_pre_not_null{selector_field_class}
3436 \bt_p{selector_field_class} is a \bt_bool_fc.
3438 @bt_post_success_frozen{optional_field_class}
3439 @bt_post_success_frozen{selector_field_class}
3441 extern bt_field_class
*bt_field_class_option_with_selector_field_bool_create(
3442 bt_trace_class
*trace_class
,
3443 bt_field_class
*optional_field_class
,
3444 bt_field_class
*selector_field_class
);
3448 Sets whether or not the selector of the \bt_opt_fc (with a boolean
3449 selector field) \bt_p{field_class} is reversed.
3451 See the \ref api-tir-fc-opt-prop-sel-rev "selector is reversed?"
3454 @param[in] field_class
3455 Option field class of which to set whether or not its selector
3457 @param[in] selector_is_reversed
3458 #BT_TRUE to make \bt_p{field_class} have a reversed selector.
3460 @bt_pre_not_null{field_class}
3461 @bt_pre_hot{field_class}
3462 @bt_pre_is_opt_wbs_fc{field_class}
3464 @sa bt_field_class_option_with_selector_field_bool_selector_is_reversed() —
3465 Returns whether or not the selector of an option field class (with
3466 a boolean selector field) is reversed.
3469 bt_field_class_option_with_selector_field_bool_set_selector_is_reversed(
3470 bt_field_class
*field_class
, bt_bool selector_is_reversed
);
3474 Returns whether or not the selector of the
3475 \bt_opt_fc (with a boolean selector field) is reversed.
3477 See the \ref api-tir-fc-opt-prop-sel-rev "selector is reversed?"
3480 @param[in] field_class
3481 Option field class of which to get whether or not its selector is
3485 #BT_TRUE if the selector of \bt_p{field_class} is reversed.
3487 @bt_pre_not_null{field_class}
3488 @bt_pre_is_opt_wbs_fc{field_class}
3490 @sa bt_field_class_option_with_selector_field_bool_set_selector_is_reversed() —
3491 Sets whether or not the selector of an option field class (with
3492 a boolean selector field) is reversed.
3495 bt_field_class_option_with_selector_field_bool_selector_is_reversed(
3496 const bt_field_class
*field_class
);
3501 @name Option field class with an unsigned integer selector field
3507 Creates an \bt_opt_fc (with an unsigned integer selector field)
3508 having the optional field class \bt_p{optional_field_class} from the
3509 trace class \bt_p{trace_class}.
3511 On success, the returned option field class has the following property
3519 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
3520 <td>\bt_p{optional_field_class}
3522 <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
3524 \em None (this property becomes available when the returned field
3525 class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
3527 <td>\ref api-tir-fc-opt-prop-uint-rs "Selector's unsigned integer ranges"
3530 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3531 <td>Empty \bt_map_val
3534 @param[in] trace_class
3535 Trace class from which to create an option field class.
3536 @param[in] optional_field_class
3537 Class of the optional fields of the instances of the option field
3539 @param[in] selector_field_class
3540 Linked selector field class of the option field class to create.
3542 Selector's unsigned integer ranges of the option field class to
3546 New option field class reference, or \c NULL on memory error.
3548 @bt_pre_not_null{trace_class}
3549 @bt_pre_not_null{optional_field_class}
3550 @bt_pre_fc_not_in_tc{optional_field_class}
3551 @bt_pre_not_null{selector_field_class}
3553 \bt_p{selector_field_class} is a \bt_uint_fc.
3554 @bt_pre_not_null{ranges}
3556 \bt_p{ranges} contains one or more \bt_p_uint_rg.
3558 @bt_post_success_frozen{optional_field_class}
3559 @bt_post_success_frozen{selector_field_class}
3560 @bt_post_success_frozen{ranges}
3562 extern bt_field_class
*
3563 bt_field_class_option_with_selector_field_integer_unsigned_create(
3564 bt_trace_class
*trace_class
,
3565 bt_field_class
*optional_field_class
,
3566 bt_field_class
*selector_field_class
,
3567 const bt_integer_range_set_unsigned
*ranges
);
3571 Borrows the \bt_p_uint_rg from the \bt_opt_fc (with an unsigned
3572 integer selector field) \bt_p{field_class}.
3575 \ref api-tir-fc-opt-prop-uint-rs "selector's unsigned integer ranges"
3578 @param[in] field_class
3579 Option field class from which to borrow the unsigned integer ranges.
3582 Unsigned integer ranges of \bt_p{field_class}.
3584 @bt_pre_not_null{field_class}
3585 @bt_pre_is_opt_wuis_fc{field_class}
3587 extern const bt_integer_range_set_unsigned
*
3588 bt_field_class_option_with_selector_field_integer_unsigned_borrow_selector_ranges_const(
3589 const bt_field_class
*field_class
);
3594 @name Option field class with a signed integer selector field
3600 Creates an \bt_opt_fc (with a signed integer selector field)
3601 having the optional field class \bt_p{optional_field_class} from the
3602 trace class \bt_p{trace_class}.
3604 On success, the returned option field class has the following property
3612 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
3613 <td>\bt_p{optional_field_class}
3615 <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
3617 \em None (this property becomes available when the returned field
3618 class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
3620 <td>\ref api-tir-fc-opt-prop-sint-rs "Selector's signed integer ranges"
3623 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3624 <td>Empty \bt_map_val
3627 @param[in] trace_class
3628 Trace class from which to create an option field class.
3629 @param[in] optional_field_class
3630 Class of the optional fields of the instances of the option field
3632 @param[in] selector_field_class
3633 Linked selector field class of the option field class to create.
3635 Selector's signed integer ranges of the option field class to
3639 New option field class reference, or \c NULL on memory error.
3641 @bt_pre_not_null{trace_class}
3642 @bt_pre_not_null{optional_field_class}
3643 @bt_pre_fc_not_in_tc{optional_field_class}
3644 @bt_pre_not_null{selector_field_class}
3646 \bt_p{selector_field_class} is a \bt_uint_fc.
3647 @bt_pre_not_null{ranges}
3649 \bt_p{ranges} contains one or more \bt_p_uint_rg.
3651 @bt_post_success_frozen{optional_field_class}
3652 @bt_post_success_frozen{selector_field_class}
3653 @bt_post_success_frozen{ranges}
3655 extern bt_field_class
*
3656 bt_field_class_option_with_selector_field_integer_signed_create(
3657 bt_trace_class
*trace_class
,
3658 bt_field_class
*optional_field_class
,
3659 bt_field_class
*selector_field_class
,
3660 const bt_integer_range_set_signed
*ranges
);
3664 Borrows the \bt_p_sint_rg from the \bt_opt_fc (with a signed
3665 integer selector field) \bt_p{field_class}.
3668 \ref api-tir-fc-opt-prop-sint-rs "selector's signed integer ranges"
3671 @param[in] field_class
3672 Option field class from which to borrow the signed integer ranges.
3675 Signed integer ranges of \bt_p{field_class}.
3677 @bt_pre_not_null{field_class}
3678 @bt_pre_is_opt_wsis_fc{field_class}
3680 extern const bt_integer_range_set_signed
*
3681 bt_field_class_option_with_selector_field_integer_signed_borrow_selector_ranges_const(
3682 const bt_field_class
*field_class
);
3687 @name Variant field class
3693 Creates a \bt_var_fc from the trace class \bt_p{trace_class}.
3695 If \bt_p{selector_field_class} is not \c NULL, then the created variant
3696 field class has a linked selector field class.
3698 \ref api-tir-fc-link "Field classes with links to other field classes"
3701 On success, the returned variant field class has the following
3709 <td>\ref api-tir-fc-var-prop-sel-fp "Selector field path"
3711 \em None (if \bt_p{selector_field_class} is not \c NULL, this
3712 property becomes available when the returned field class becomes
3713 part of an \bt_ev_cls or of a \bt_stream_cls)
3715 <td>\ref api-tir-fc-var-prop-opts "Options"
3718 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3719 <td>Empty \bt_map_val
3722 @param[in] trace_class
3723 Trace class from which to create a variant field class.
3724 @param[in] selector_field_class
3726 Linked selector field class of the variant field class to create.
3732 New variant field class reference, or \c NULL on memory error.
3734 @bt_pre_not_null{trace_class}
3736 <strong>If \bt_p{selector_field_class} is not \c NULL</strong>,
3737 \bt_p{selector_field_class} is an \bt_int_fc.
3739 @bt_post_success_frozen{element_field_class}
3740 @bt_post_success_frozen{selector_field_class}
3742 extern bt_field_class
*bt_field_class_variant_create(
3743 bt_trace_class
*trace_class
,
3744 bt_field_class
*selector_field_class
);
3748 Returns the number of options contained in the \bt_var_fc
3751 See the \ref api-tir-fc-var-prop-opts "options" property.
3753 @param[in] field_class
3754 Variant field class of which to get the number of contained
3758 Number of contained options in \bt_p{field_class}.
3760 @bt_pre_not_null{field_class}
3761 @bt_pre_is_var_fc{field_class}
3763 extern uint64_t bt_field_class_variant_get_option_count(
3764 const bt_field_class
*field_class
);
3768 Borrows the option at index \bt_p{index} from the
3769 \bt_var_fc \bt_p{field_class}.
3771 See the \ref api-tir-fc-var-prop-opts "options" property.
3773 @param[in] field_class
3774 Variant field class from which to borrow the option at
3777 Index of the option to borrow from \bt_p{field_class}.
3781 \em Borrowed reference of the option of
3782 \bt_p{field_class} at index \bt_p{index}.
3784 The returned pointer remains valid as long as \bt_p{field_class}
3788 @bt_pre_not_null{field_class}
3789 @bt_pre_is_var_fc{field_class}
3791 \bt_p{index} is less than the number of options in
3792 \bt_p{field_class} (as returned by
3793 bt_field_class_variant_get_option_count()).
3795 @sa bt_field_class_variant_get_option_count() —
3796 Returns the number of options contained in a variant field class.
3797 @sa bt_field_class_variant_borrow_option_by_index_const() —
3798 \c const version of this function.
3800 extern bt_field_class_variant_option
*
3801 bt_field_class_variant_borrow_option_by_index(
3802 bt_field_class
*field_class
, uint64_t index
);
3806 Borrows the option at index \bt_p{index} from the
3807 \bt_var_fc \bt_p{field_class} (\c const version).
3809 See bt_field_class_variant_borrow_option_by_index().
3811 extern const bt_field_class_variant_option
*
3812 bt_field_class_variant_borrow_option_by_index_const(
3813 const bt_field_class
*field_class
, uint64_t index
);
3817 Borrows the option having the name \bt_p{name} from the
3818 \bt_var_fc \bt_p{field_class}.
3820 See the \ref api-tir-fc-var-prop-opts "options" property.
3822 If there's no option having the name \bt_p{name} in
3823 \bt_p{field_class}, this function returns \c NULL.
3825 @param[in] field_class
3826 Variant field class from which to borrow the option having the
3829 Name of the option to borrow from \bt_p{field_class}.
3833 \em Borrowed reference of the option of
3834 \bt_p{field_class} having the name \bt_p{name}, or \c NULL
3837 The returned pointer remains valid as long as \bt_p{field_class}
3841 @bt_pre_not_null{field_class}
3842 @bt_pre_is_var_fc{field_class}
3843 @bt_pre_not_null{name}
3845 @sa bt_field_class_variant_borrow_option_by_name_const() —
3846 \c const version of this function.
3848 extern bt_field_class_variant_option
*
3849 bt_field_class_variant_borrow_option_by_name(
3850 bt_field_class
*field_class
, const char *name
);
3854 Borrows the option having the name \bt_p{name} from the
3855 \bt_var_fc \bt_p{field_class} (\c const version).
3857 See bt_field_class_variant_borrow_option_by_name().
3859 extern const bt_field_class_variant_option
*
3860 bt_field_class_variant_borrow_option_by_name_const(
3861 const bt_field_class
*field_class
, const char *name
);
3866 @name Variant field class option
3871 @typedef struct bt_field_class_variant_option bt_field_class_variant_option;
3874 Variant field class option.
3879 Returns the name of the \bt_var_fc option \bt_p{option}.
3881 See the \ref api-tir-fc-var-prop-opts "options" property.
3884 Variant field class option of which to get the name.
3888 Name of \bt_p{option}.
3890 The returned pointer remains valid as long as \bt_p{option} exists.
3893 @bt_pre_not_null{option}
3895 extern const char *bt_field_class_variant_option_get_name(
3896 const bt_field_class_variant_option
*option
);
3900 Borrows the field class from the \bt_var_fc option
3903 See the \ref api-tir-fc-var-prop-opts "options" property.
3906 Variant field class option from which to borrow the field class.
3909 Field class of \bt_p{option}.
3911 @bt_pre_not_null{option}
3913 @sa bt_field_class_variant_option_borrow_field_class_const() —
3914 \c const version of this function.
3916 extern bt_field_class
*bt_field_class_variant_option_borrow_field_class(
3917 bt_field_class_variant_option
*option
);
3921 Borrows the field class from the \bt_var_fc option
3922 \bt_p{option} (\c const version).
3924 See bt_field_class_variant_option_borrow_field_class().
3926 extern const bt_field_class
*
3927 bt_field_class_variant_option_borrow_field_class_const(
3928 const bt_field_class_variant_option
*option
);
3932 Sets the user attributes of the \bt_var_fc option \bt_p{option}
3933 to \bt_p{user_attributes}.
3935 See the \ref api-tir-fc-var-prop-opts "options" property.
3938 When you append an option to a variant field class with
3939 bt_field_class_variant_without_selector_append_option(),
3940 bt_field_class_variant_with_selector_field_integer_unsigned_append_option(),
3942 bt_field_class_variant_with_selector_field_integer_signed_append_option(),
3943 the option's initial user attributes is an empty \bt_map_val.
3944 Therefore you can borrow it with
3945 bt_field_class_variant_option_borrow_user_attributes() and fill it
3946 directly instead of setting a new one with this function.
3949 Variant field class option of which to set the user attributes to
3950 \bt_p{user_attributes}.
3951 @param[in] user_attributes
3952 New user attributes of \bt_p{option}.
3954 @bt_pre_not_null{option}
3956 @bt_pre_not_null{user_attributes}
3957 @bt_pre_is_map_val{user_attributes}
3959 @sa bt_field_class_variant_option_borrow_user_attributes() —
3960 Borrows the user attributes of a variant field class option.
3962 extern void bt_field_class_variant_option_set_user_attributes(
3963 bt_field_class_variant_option
*option
,
3964 const bt_value
*user_attributes
);
3968 Borrows the user attributes of the \bt_var_fc option \bt_p{option}.
3970 See the \ref api-tir-fc-var-prop-opts "options" property.
3973 When you append an option to a variant field class with
3974 bt_field_class_variant_without_selector_append_option(),
3975 bt_field_class_variant_with_selector_field_integer_unsigned_append_option(),
3977 bt_field_class_variant_with_selector_field_integer_signed_append_option(),
3978 the option's initial user attributes is an empty \bt_map_val.
3981 Variant field class option from which to borrow the user
3985 User attributes of \bt_p{option} (a \bt_map_val).
3987 @bt_pre_not_null{option}
3989 @sa bt_field_class_variant_option_set_user_attributes() —
3990 Sets the user attributes of a variant field class option.
3991 @sa bt_field_class_variant_option_borrow_user_attributes_const() —
3992 \c const version of this function.
3994 extern bt_value
*bt_field_class_variant_option_borrow_user_attributes(
3995 bt_field_class_variant_option
*option
);
3999 Borrows the user attributes of the \bt_var_fc option \bt_p{option}
4002 See bt_field_class_variant_option_borrow_user_attributes().
4004 extern const bt_value
*bt_field_class_variant_option_borrow_user_attributes_const(
4005 const bt_field_class_variant_option
*option
);
4010 @name Variant field class without a selector field
4017 bt_field_class_variant_without_selector_append_option().
4019 typedef enum bt_field_class_variant_without_selector_append_option_status
{
4024 BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
4030 BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
4031 } bt_field_class_variant_without_selector_append_option_status
;
4035 Appends an option to the \bt_var_fc (without a selector field)
4036 \bt_p{field_class} having the name \bt_p{name} and the
4037 field class \bt_p{option_field_class}.
4039 See the \ref api-tir-fc-var-prop-opts "options" property.
4041 @param[in] field_class
4042 Variant field class to which to append an option having
4043 the name \bt_p{name} and the field class \bt_p{option_field_class}.
4045 Name of the option to append to \bt_p{field_class} (copied).
4046 @param[in] option_field_class
4047 Field class of the option to append to \bt_p{field_class}.
4049 @retval #BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
4051 @retval #BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
4054 @bt_pre_not_null{field_class}
4055 @bt_pre_hot{field_class}
4056 @bt_pre_is_var_wos_fc{field_class}
4058 \bt_p{field_class} has no option with the name \bt_p{name}.
4059 @bt_pre_not_null{name}
4060 @bt_pre_not_null{option_field_class}
4061 @bt_pre_fc_not_in_tc{option_field_class}
4063 @bt_post_success_frozen{option_field_class}
4065 extern bt_field_class_variant_without_selector_append_option_status
4066 bt_field_class_variant_without_selector_append_option(
4067 bt_field_class
*field_class
, const char *name
,
4068 bt_field_class
*option_field_class
);
4073 @name Variant field class with a selector field
4080 bt_field_class_variant_with_selector_field_integer_unsigned_append_option()
4082 bt_field_class_variant_with_selector_field_integer_signed_append_option().
4084 typedef enum bt_field_class_variant_with_selector_field_integer_append_option_status
{
4089 BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
4095 BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
4096 } bt_field_class_variant_with_selector_field_integer_append_option_status
;
4100 Borrows the selector field path from the \bt_var_fc (with a selector
4101 field) \bt_p{field_class}.
4103 See the \ref api-tir-fc-var-prop-sel-fp "selector field path" property.
4105 This property is only available when a \bt_struct_fc containing
4106 (recursively) \bt_p{field_class} is passed to one of:
4108 - bt_stream_class_set_packet_context_field_class()
4109 - bt_stream_class_set_event_common_context_field_class()
4110 - bt_event_class_set_specific_context_field_class()
4111 - bt_event_class_set_payload_field_class()
4113 In the meantime, this function returns \c NULL.
4115 @param[in] field_class
4116 Variant field class from which to borrow the selector field path.
4119 Selector field path of \bt_p{field_class}.
4121 @bt_pre_not_null{field_class}
4122 @bt_pre_is_var_ws_fc{field_class}
4124 extern const bt_field_path
*
4125 bt_field_class_variant_with_selector_field_borrow_selector_field_path_const(
4126 const bt_field_class
*field_class
);
4131 @name Variant field class with an unsigned integer selector field
4137 Appends an option to the \bt_var_fc (with an unsigned integer
4138 selector field) \bt_p{field_class} having the name \bt_p{name},
4139 the field class \bt_p{option_field_class}, and the
4140 \bt_p_uint_rg \bt_p{ranges}.
4142 See the \ref api-tir-fc-var-prop-opts "options" property.
4144 @param[in] field_class
4145 Variant field class to which to append an option having
4146 the name \bt_p{name}, the field class \bt_p{option_field_class},
4147 and the unsigned integer ranges \bt_p{ranges}.
4149 Name of the option to append to \bt_p{field_class} (copied).
4150 @param[in] option_field_class
4151 Field class of the option to append to \bt_p{field_class}.
4153 Unsigned integer ranges of the option to append to
4156 @retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
4158 @retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
4161 @bt_pre_not_null{field_class}
4162 @bt_pre_hot{field_class}
4163 @bt_pre_is_var_wuis_fc{field_class}
4165 \bt_p{field_class} has no option with the name \bt_p{name}.
4166 @bt_pre_not_null{name}
4167 @bt_pre_not_null{option_field_class}
4168 @bt_pre_fc_not_in_tc{option_field_class}
4169 @bt_pre_not_null{ŗanges}
4171 \bt_p{ranges} contains one or more unsigned integer ranges.
4173 The unsigned integer ranges in \bt_p{ranges} do not overlap
4174 any unsigned integer range of any existing option in
4177 @bt_post_success_frozen{option_field_class}
4179 extern bt_field_class_variant_with_selector_field_integer_append_option_status
4180 bt_field_class_variant_with_selector_field_integer_unsigned_append_option(
4181 bt_field_class
*field_class
, const char *name
,
4182 bt_field_class
*option_field_class
,
4183 const bt_integer_range_set_unsigned
*ranges
);
4187 Borrows the option at index \bt_p{index} from the
4188 \bt_var_fc (with an unsigned integer selector field)
4191 See the \ref api-tir-fc-var-prop-opts "options" property.
4193 @param[in] field_class
4194 Variant field class from which to borrow the option at
4197 Index of the option to borrow from \bt_p{field_class}.
4201 \em Borrowed reference of the option of
4202 \bt_p{field_class} at index \bt_p{index}.
4204 The returned pointer remains valid as long as \bt_p{field_class}
4208 @bt_pre_not_null{field_class}
4209 @bt_pre_is_var_wuis_fc{field_class}
4211 \bt_p{index} is less than the number of options in
4212 \bt_p{field_class} (as returned by
4213 bt_field_class_variant_get_option_count()).
4215 @sa bt_field_class_variant_get_option_count() —
4216 Returns the number of options contained in a variant field class.
4218 extern const bt_field_class_variant_with_selector_field_integer_unsigned_option
*
4219 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(
4220 const bt_field_class
*field_class
, uint64_t index
);
4224 Borrows the option having the name \bt_p{name} from the
4225 \bt_var_fc (with an unsigned integer selector field)
4228 See the \ref api-tir-fc-var-prop-opts "options" property.
4230 If there's no option having the name \bt_p{name} in
4231 \bt_p{field_class}, this function returns \c NULL.
4233 @param[in] field_class
4234 Variant field class from which to borrow the option having the
4237 Name of the option to borrow from \bt_p{field_class}.
4241 \em Borrowed reference of the option of
4242 \bt_p{field_class} having the name \bt_p{name}, or \c NULL
4245 The returned pointer remains valid as long as \bt_p{field_class}
4249 @bt_pre_not_null{field_class}
4250 @bt_pre_is_var_wuis_fc{field_class}
4251 @bt_pre_not_null{name}
4253 @sa bt_field_class_variant_borrow_option_by_name_const() —
4254 Borrows an option by name from a variant field class.
4256 extern const bt_field_class_variant_with_selector_field_integer_unsigned_option
*
4257 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const(
4258 const bt_field_class
*field_class
, const char *name
);
4263 @name Variant field class (with an unsigned integer selector field) option
4268 @typedef struct bt_field_class_variant_with_selector_field_integer_unsigned_option bt_field_class_variant_with_selector_field_integer_unsigned_option;
4271 Variant field class (with an unsigned integer selector field) option.
4276 Borrows the \bt_p_uint_rg from the \bt_var_fc (with an unsigned
4277 integer selector field) option \bt_p{option}.
4279 See the \ref api-tir-fc-var-prop-opts "options" property.
4282 Variant field class option from which to borrow the
4283 unsigned integer ranges.
4286 Unsigned integer ranges of \bt_p{option}.
4288 @bt_pre_not_null{option}
4290 extern const bt_integer_range_set_unsigned
*
4291 bt_field_class_variant_with_selector_field_integer_unsigned_option_borrow_ranges_const(
4292 const bt_field_class_variant_with_selector_field_integer_unsigned_option
*option
);
4296 \ref api-fund-c-typing "Upcasts" the \bt_var_fc (with an
4297 unsigned integer selector field) option \bt_p{option} to the
4298 common #bt_field_class_variant_option type.
4300 See the \ref api-tir-fc-var-prop-opts "options" property.
4304 Variant field class option to upcast.
4310 \bt_p{option} as a common variant field class option.
4313 const bt_field_class_variant_option
*
4314 bt_field_class_variant_with_selector_field_integer_unsigned_option_as_option_const(
4315 const bt_field_class_variant_with_selector_field_integer_unsigned_option
*option
)
4317 return __BT_UPCAST_CONST(bt_field_class_variant_option
, option
);
4323 @name Variant field class with a signed integer selector field
4329 Appends an option to the \bt_var_fc (with a signed integer
4330 selector field) \bt_p{field_class} having the name \bt_p{name},
4331 the field class \bt_p{option_field_class}, and the
4332 \bt_p_sint_rg \bt_p{ranges}.
4334 See the \ref api-tir-fc-var-prop-opts "options" property.
4336 @param[in] field_class
4337 Variant field class to which to append an option having
4338 the name \bt_p{name} and the field class \bt_p{option_field_class},
4339 and the signed integer ranges \bt_p{ranges}.
4341 Name of the option to append to \bt_p{field_class} (copied).
4342 @param[in] option_field_class
4343 Field class of the option to append to \bt_p{field_class}.
4345 Signed integer ranges of the option to append to
4348 @retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
4350 @retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
4353 @bt_pre_not_null{field_class}
4354 @bt_pre_hot{field_class}
4355 @bt_pre_is_var_wsis_fc{field_class}
4357 \bt_p{field_class} has no option with the name \bt_p{name}.
4358 @bt_pre_not_null{name}
4359 @bt_pre_not_null{option_field_class}
4360 @bt_pre_fc_not_in_tc{option_field_class}
4361 @bt_pre_not_null{ŗanges}
4363 \bt_p{ranges} contains one or more signed integer ranges.
4365 The signed integer ranges in \bt_p{ranges} do not overlap with
4366 any signed integer range of any existing option in
4369 @bt_post_success_frozen{option_field_class}
4371 extern bt_field_class_variant_with_selector_field_integer_append_option_status
4372 bt_field_class_variant_with_selector_field_integer_signed_append_option(
4373 bt_field_class
*field_class
, const char *name
,
4374 bt_field_class
*option_field_class
,
4375 const bt_integer_range_set_signed
*ranges
);
4379 Borrows the option at index \bt_p{index} from the
4380 \bt_var_fc (with a signed integer selector field)
4383 See the \ref api-tir-fc-var-prop-opts "options" property.
4385 @param[in] field_class
4386 Variant field class from which to borrow the option at
4389 Index of the option to borrow from \bt_p{field_class}.
4393 \em Borrowed reference of the option of
4394 \bt_p{field_class} at index \bt_p{index}.
4396 The returned pointer remains valid as long as \bt_p{field_class}
4400 @bt_pre_not_null{field_class}
4401 @bt_pre_is_var_wsis_fc{field_class}
4403 \bt_p{index} is less than the number of options in
4404 \bt_p{field_class} (as returned by
4405 bt_field_class_variant_get_option_count()).
4407 @sa bt_field_class_variant_get_option_count() —
4408 Returns the number of options contained in a variant field class.
4410 extern const bt_field_class_variant_with_selector_field_integer_signed_option
*
4411 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(
4412 const bt_field_class
*field_class
, uint64_t index
);
4416 Borrows the option having the name \bt_p{name} from the
4417 \bt_var_fc (with a signed integer selector field)
4420 See the \ref api-tir-fc-var-prop-opts "options" property.
4422 If there's no option having the name \bt_p{name} in
4423 \bt_p{field_class}, this function returns \c NULL.
4425 @param[in] field_class
4426 Variant field class from which to borrow the option having the
4429 Name of the option to borrow from \bt_p{field_class}.
4433 \em Borrowed reference of the option of
4434 \bt_p{field_class} having the name \bt_p{name}, or \c NULL
4437 The returned pointer remains valid as long as \bt_p{field_class}
4441 @bt_pre_not_null{field_class}
4442 @bt_pre_is_var_wsis_fc{field_class}
4443 @bt_pre_not_null{name}
4445 @sa bt_field_class_variant_borrow_option_by_name_const() —
4446 Borrows an option by name from a variant field class.
4448 extern const bt_field_class_variant_with_selector_field_integer_signed_option
*
4449 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const(
4450 const bt_field_class
*field_class
, const char *name
);
4455 @name Variant field class (with a signed integer selector field) option
4460 @typedef struct bt_field_class_variant_with_selector_field_integer_signed_option bt_field_class_variant_with_selector_field_integer_signed_option;
4463 Variant field class (with a signed integer selector field) option.
4468 Borrows the \bt_p_sint_rg from the \bt_var_fc (with a signed
4469 integer selector field) option \bt_p{option}.
4471 See the \ref api-tir-fc-var-prop-opts "options" property.
4474 Variant field class option from which to borrow the
4475 signed integer ranges.
4478 Signed integer ranges of \bt_p{option}.
4480 @bt_pre_not_null{option}
4482 extern const bt_integer_range_set_signed
*
4483 bt_field_class_variant_with_selector_field_integer_signed_option_borrow_ranges_const(
4484 const bt_field_class_variant_with_selector_field_integer_signed_option
*option
);
4488 \ref api-fund-c-typing "Upcasts" the \bt_var_fc (with a signed
4489 integer selector field) option \bt_p{option} to the
4490 common #bt_field_class_variant_option type.
4492 See the \ref api-tir-fc-var-prop-opts "options" property.
4496 Variant field class option to upcast.
4502 \bt_p{option} as a common variant field class option.
4505 const bt_field_class_variant_option
*
4506 bt_field_class_variant_with_selector_field_integer_signed_option_as_option_const(
4507 const bt_field_class_variant_with_selector_field_integer_signed_option
*option
)
4509 return __BT_UPCAST_CONST(bt_field_class_variant_option
, option
);
4515 @name Reference count
4521 Increments the \ref api-fund-shared-object "reference count" of
4522 the field class \bt_p{field_class}.
4524 @param[in] field_class
4526 Field class of which to increment the reference count.
4531 @sa bt_field_class_put_ref() —
4532 Decrements the reference count of a field class.
4534 extern void bt_field_class_get_ref(const bt_field_class
*field_class
);
4538 Decrements the \ref api-fund-shared-object "reference count" of
4539 the field class \bt_p{field_class}.
4541 @param[in] field_class
4543 Field class of which to decrement the reference count.
4548 @sa bt_field_class_get_ref() —
4549 Increments the reference count of a field class.
4551 extern void bt_field_class_put_ref(const bt_field_class
*field_class
);
4555 Decrements the reference count of the field class
4556 \bt_p{_field_class}, and then sets \bt_p{_field_class} to \c NULL.
4560 Field class of which to decrement the reference count.
4562 Can contain \c NULL.
4565 @bt_pre_assign_expr{_field_class}
4567 #define BT_FIELD_CLASS_PUT_REF_AND_RESET(_field_class) \
4569 bt_field_class_put_ref(_field_class); \
4570 (_field_class) = NULL; \
4575 Decrements the reference count of the field class \bt_p{_dst}, sets
4576 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
4578 This macro effectively moves a field class reference from the expression
4579 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
4580 \bt_p{_dst} reference.
4584 Destination expression.
4586 Can contain \c NULL.
4592 Can contain \c NULL.
4595 @bt_pre_assign_expr{_dst}
4596 @bt_pre_assign_expr{_src}
4598 #define BT_FIELD_CLASS_MOVE_REF(_dst, _src) \
4600 bt_field_class_put_ref(_dst); \
4613 #endif /* BABELTRACE2_TRACE_IR_FIELD_CLASS_H */