2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_TRACE_IR_FIELD_CLASS_H
8 #define BABELTRACE2_TRACE_IR_FIELD_CLASS_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
19 #include <babeltrace2/types.h>
26 @defgroup api-tir-fc Field classes
30 Classes of \bt_p_field.
32 <strong><em>Field classes</em></strong> are the classes of \bt_p_field:
34 @image html field-class-zoom.png
36 Field classes are \ref api-tir "trace IR" metadata objects.
38 There are many types of field classes. They can be divided into two main
44 Classes of fields which contain a simple value.
46 The scalar field classes are:
48 - \ref api-tir-fc-bool "Boolean"
49 - \ref api-tir-fc-ba "Bit array"
50 - \ref api-tir-fc-int "Integer" (unsigned and signed)
51 - \ref api-tir-fc-enum "Enumeration" (unsigned and signed)
52 - \ref api-tir-fc-real "Real" (single-precision and double-precision)
53 - \ref api-tir-fc-string "String"
58 Classes of fields which contain other fields.
60 The container field classes are:
62 - \ref api-tir-fc-array "Array" (static and dynamic)
63 - \ref api-tir-fc-struct "Structure"
64 - \ref api-tir-fc-opt "Option"
65 - \ref api-tir-fc-var "Variant"
69 @image html fc-to-field.png "Fields (green) are instances of field classes (orange)."
71 Some field classes conceptually inherit other field classes, eventually
72 making an inheritance hierarchy. For example, a \bt_sarray_fc
73 \em is an array field class. Therefore, a static array field class has
74 any property that an array field class has.
76 The complete field class inheritance hierarchy is:
78 @image html all-field-classes.png
80 In the illustration above:
82 - You can create any field class with a dark background with
83 a dedicated <code>bt_field_class_*_create()</code> function.
85 - A field class with a pale background is an \em abstract field class:
86 you cannot create it, but it has properties, therefore there are
87 functions which apply to it.
89 For example, bt_field_class_integer_set_preferred_display_base()
90 applies to any \bt_int_fc.
92 Field classes are \ref api-fund-shared-object "shared objects": get a
93 new reference with bt_field_class_get_ref() and put an existing
94 reference with bt_field_class_put_ref().
96 Some library functions \ref api-fund-freezing "freeze" field classes on
97 success. The documentation of those functions indicate this
100 All the field class types share the same C type, #bt_field_class.
102 Get the type enumerator of a field class with bt_field_class_get_type().
103 Get whether or not a field class type conceptually \em is a given type
104 with the inline bt_field_class_type_is() function.
106 The following table shows the available type enumerators and creation
107 functions for each type of \em concrete (non-abstract) field class:
113 <th>Creation function
115 <td><em>\ref api-tir-fc-bool "Boolean"</em>
116 <td>#BT_FIELD_CLASS_TYPE_BOOL
117 <td>bt_field_class_bool_create()
119 <td><em>\ref api-tir-fc-ba "Bit array"</em>
120 <td>#BT_FIELD_CLASS_TYPE_BIT_ARRAY
121 <td>bt_field_class_bit_array_create()
123 <td><em>Unsigned \ref api-tir-fc-int "integer"</em>
124 <td>#BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER
125 <td>bt_field_class_integer_unsigned_create()
127 <td><em>Signed \ref api-tir-fc-int "integer"</em>
128 <td>#BT_FIELD_CLASS_TYPE_SIGNED_INTEGER
129 <td>bt_field_class_integer_signed_create()
131 <td><em>Unsigned \ref api-tir-fc-enum "enumeration"</em>
132 <td>#BT_FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION
133 <td>bt_field_class_enumeration_unsigned_create()
135 <td><em>Signed \ref api-tir-fc-enum "enumeration"</em>
136 <td>#BT_FIELD_CLASS_TYPE_SIGNED_ENUMERATION
137 <td>bt_field_class_enumeration_signed_create()
139 <td><em>Single-precision \ref api-tir-fc-real "real"</em>
140 <td>#BT_FIELD_CLASS_TYPE_SINGLE_PRECISION_REAL
141 <td>bt_field_class_real_single_precision_create()
143 <td><em>Double-precision \ref api-tir-fc-real "real"</em>
144 <td>#BT_FIELD_CLASS_TYPE_DOUBLE_PRECISION_REAL
145 <td>bt_field_class_real_double_precision_create()
147 <td><em>\ref api-tir-fc-string "String"</em>
148 <td>#BT_FIELD_CLASS_TYPE_STRING
149 <td>bt_field_class_string_create()
151 <td><em>Static \ref api-tir-fc-array "array"</em>
152 <td>#BT_FIELD_CLASS_TYPE_STATIC_ARRAY
153 <td>bt_field_class_array_static_create()
155 <td><em>Dynamic \ref api-tir-fc-array "array" (no length field)</em>
156 <td>#BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD
157 <td>bt_field_class_array_dynamic_create()
159 <td><em>Dynamic \ref api-tir-fc-array "array" (with length field)</em>
160 <td>#BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD
161 <td>bt_field_class_array_dynamic_create()
163 <td><em>\ref api-tir-fc-struct "Structure"</em>
164 <td>#BT_FIELD_CLASS_TYPE_STRUCTURE
165 <td>bt_field_class_structure_create()
167 <td><em>\ref api-tir-fc-opt "Option" (no selector field)</em>
168 <td>#BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD
169 <td>bt_field_class_option_without_selector_create()
171 <td><em>\ref api-tir-fc-opt "Option" (boolean selector field)</em>
172 <td>#BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD
173 <td>bt_field_class_option_with_selector_field_bool_create()
175 <td><em>\ref api-tir-fc-opt "Option" (unsigned integer selector field)</em>
176 <td>#BT_FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
177 <td>bt_field_class_option_with_selector_field_integer_unsigned_create()
179 <td><em>\ref api-tir-fc-opt "Option" (signed integer selector field)</em>
180 <td>#BT_FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD
181 <td>bt_field_class_option_with_selector_field_integer_signed_create()
183 <td><em>\ref api-tir-fc-var "Variant" (no selector field)</em>
184 <td>#BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD
185 <td>bt_field_class_variant_create()
187 <td><em>\ref api-tir-fc-var "Variant" (unsigned integer selector field)</em>
188 <td>#BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
189 <td>bt_field_class_variant_create()
191 <td><em>\ref api-tir-fc-var "Variant" (signed integer selector field)</em>
192 <td>#BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD
193 <td>bt_field_class_variant_create()
196 You need a \bt_trace_cls to create a field class: create one from a
197 \bt_self_comp with bt_trace_class_create().
199 Outside the field class API, you can use field classes at four
200 locations, called <em>scopes</em>, within the trace IR API:
202 - To set the packet context field class of a \bt_stream_cls with
203 bt_stream_class_set_packet_context_field_class().
205 - To set the event common context field class of a stream class with
206 bt_stream_class_set_event_common_context_field_class().
208 - To set the specific context field class of an \bt_ev_cls with
209 bt_event_class_set_specific_context_field_class().
211 - To set the payload field class of an event class with
212 bt_event_class_set_payload_field_class().
214 When you call one of the four functions above:
216 - The passed field class must be a \bt_struct_fc.
218 - You must \em not have already called any of the four functions above
219 with the passed field class or with any of its contained field
222 - If any of the field classes recursively contained in the passed
223 field class has a \ref api-tir-fc-link "link to another field class",
224 it must honor the field class link rules.
226 Once you have called one of the four functions above, the passed field
227 class becomes \ref api-fund-freezing "frozen".
229 <h1>Common field class property</h1>
231 A field class has the following common property:
235 \anchor api-tir-fc-prop-user-attrs
236 \bt_dt_opt User attributes
239 User attributes of the field class.
241 User attributes are custom attributes attached to a field class.
243 Use bt_field_class_set_user_attributes(),
244 bt_field_class_borrow_user_attributes(), and
245 bt_field_class_borrow_user_attributes_const().
249 <h1>\anchor api-tir-fc-bool Boolean field class</h1>
251 @image html fc-bool.png
253 A <strong><em>boolean field class</em></strong> is the class
256 A boolean field contains a boolean value (#BT_TRUE or #BT_FALSE).
258 Create a boolean field class with bt_field_class_bool_create().
260 A boolean field class has no specific properties.
262 <h1>\anchor api-tir-fc-ba Bit array field class</h1>
264 @image html fc-ba.png
266 A <strong><em>bit array field class</em></strong> is the class
269 A bit array field contains a fixed-length array of bits.
271 Create a bit array field class with bt_field_class_bit_array_create().
273 A bit array field class has the following property:
277 \anchor api-tir-fc-ba-prop-len
281 Number of bits contained in the instances (bit array fields) of
282 the bit array field class.
284 As of \bt_name_version_min_maj, the maximum length of a bit array
287 You cannot change the length once the bit array field class is
290 Get a bit array field class's length with
291 bt_field_class_bit_array_get_length().
295 <h1>\anchor api-tir-fc-int Integer field classes</h1>
297 @image html fc-int.png
299 <strong><em>Integer field classes</em></strong> are classes
302 Integer fields contain integral values.
304 An integer field class is an \em abstract field class: you cannot create
305 one. The concrete integer field classes are:
308 <dt>Unsigned integer field class</dt>
310 Its instances (unsigned integer fields) contain an unsigned integral
313 Create with bt_field_class_integer_unsigned_create().
316 <dt>Signed integer field class</dt>
318 Its instances (signed integer fields) contain a signed integral
321 Create with bt_field_class_integer_signed_create().
325 Integer field classes have the following common properties:
329 \anchor api-tir-fc-int-prop-size
333 Expected range of values that the instances (integer fields)
334 of the integer field class can contain.
336 For example, if the field value range of an unsigned integer
337 field class is [0, 16383], then its unsigned integer fields
338 can only contain the values from 0 to 16383.
340 \bt_cp_sink_comp can benefit from this property to make some space
341 optimizations when writing trace data.
343 Use bt_field_class_integer_set_field_value_range() and
344 bt_field_class_integer_get_field_value_range().
348 \anchor api-tir-fc-int-prop-base
349 Preferred display base
352 Preferred base (2, 8, 10, or 16) to use when displaying the
353 instances (integer fields) of the integer field class.
355 Use bt_field_class_integer_set_preferred_display_base() and
356 bt_field_class_integer_get_preferred_display_base().
360 <h2>\anchor api-tir-fc-enum Enumeration field classes</h2>
362 @image html fc-enum.png
364 <strong><em>Enumeration field classes</em></strong> are classes
367 Enumeration field classes \em are \bt_p_int_fc: they have the integer
368 field classes properties.
370 Enumeration fields \em are integer fields: they contain integral values.
372 Enumeration field classes associate labels (strings) to specific
373 ranges of integral values. This association is called an enumeration
374 field class <em>mapping</em>.
376 For example, if an enumeration field class maps the label \c SUGAR to
377 the integer ranges [1, 19] and [25, 31], then an instance
378 (enumeration field) of this field class with the value 15 or 28 has the
379 label <code>SUGAR</code>.
381 An enumeration field class is an \em abstract field class: you cannot
382 create one. The concrete enumeration field classes are:
385 <dt>Unsigned enumeration field class</dt>
387 Its instances (unsigned enumeration fields) contain an unsigned
390 Create with bt_field_class_enumeration_unsigned_create().
393 <dt>Signed enumeration field class</dt>
395 Its instances (signed enumeration fields) contain a signed value
398 Create with bt_field_class_enumeration_signed_create().
402 Enumeration field classes have the following common property:
406 \anchor api-tir-fc-enum-prop-mappings
410 Set of mappings of the enumeration field class.
412 An enumeration field class mapping is a label (string) and an
415 The integer ranges of a given mapping or of multiple mappings of
416 the same enumeration field class can overlap. For example,
417 an enumeration field class can have those two mappings:
419 - <code>CALORIES</code>: [1, 11], [15, 37]
420 - <code>SODIUM</code>: [7, 13]
422 In that case, the values 2 and 30 correpond to the label
423 <code>CALORIES</code>, the value 12 to the label
424 <code>SODIUM</code>, and the value 10 to the labels
425 \c CALORIES \em and <code>SODIUM</code>.
427 Two mappings of the same enumeration field class cannot have the
430 Add a mapping to an enumeration field class with
431 bt_field_class_enumeration_unsigned_add_mapping() or
432 bt_field_class_enumeration_signed_add_mapping().
434 Get the number of mappings in an enumeration field class with
435 bt_field_class_enumeration_get_mapping_count().
437 Borrow a mapping from an enumeration field class with
438 bt_field_class_enumeration_unsigned_borrow_mapping_by_index_const(),
439 bt_field_class_enumeration_signed_borrow_mapping_by_index_const(),
440 bt_field_class_enumeration_unsigned_borrow_mapping_by_label_const(),
442 bt_field_class_enumeration_signed_borrow_mapping_by_label_const().
444 An enumeration field class mapping is a
445 \ref api-fund-unique-object "unique object": it
446 belongs to the enumeration field class which contains it.
448 There are two enumeration field class mapping types, depending on
449 the field class's type:
450 #bt_field_class_enumeration_unsigned_mapping and
451 #bt_field_class_enumeration_signed_mapping.
453 There is also the #bt_field_class_enumeration_mapping type for
454 common properties and operations (for example,
455 bt_field_class_enumeration_mapping_get_label()).
456 \ref api-fund-c-typing "Upcast" a specific enumeration field class
457 mapping to the #bt_field_class_enumeration_mapping type with
458 bt_field_class_enumeration_unsigned_mapping_as_mapping_const() or
459 bt_field_class_enumeration_signed_mapping_as_mapping_const().
461 Get all the enumeration field class labels mapped to a given integer
463 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value()
465 bt_field_class_enumeration_signed_get_mapping_labels_for_value().
469 <h1>\anchor api-tir-fc-real Real field classes</h1>
471 @image html fc-real.png
473 <strong><em>Real field classes</em></strong> are classes
477 <a href="https://en.wikipedia.org/wiki/Real_number">real</a>
478 values (\c float or \c double types).
480 A real field class is an \em abstract field class: you cannot create
481 one. The concrete real field classes are:
484 <dt>Single-precision real field class</dt>
486 Its instances (single-precision real fields) contain a \c float
489 Create with bt_field_class_real_single_precision_create().
492 <dt>Double-precision real field class</dt>
494 Its instances (double-precision real fields) contain a \c double
497 Create with bt_field_class_real_double_precision_create().
501 Real field classes have no specific properties.
503 <h1>\anchor api-tir-fc-string String field class</h1>
505 @image html fc-string.png
507 A <strong><em>string field class</em></strong> is the class
508 of \bt_p_string_field.
510 A string field contains an UTF-8 string value.
512 Create a string field class with bt_field_class_string_create().
514 A string field class has no specific properties.
516 <h1>\anchor api-tir-fc-array Array field classes</h1>
518 @image html fc-array.png
520 <strong><em>Array field classes</em></strong> are classes
521 of \bt_p_array_field.
523 Array fields contain zero or more fields which have the same class.
525 An array field class is an \em abstract field class: you cannot create
526 one. The concrete array field classes are:
529 <dt>Static array field class</dt>
531 Its instances (static array fields) contain a fixed number of
534 Create with bt_field_class_array_static_create().
536 A static array field class has the following specific property:
540 \anchor api-tir-fc-sarray-prop-len
544 Number of fields contained in the instances (static array
545 fields) of the static array field class.
547 You cannot change the length once the static array field class
550 Get a static array field class's length with
551 bt_field_class_array_static_get_length().
556 <dt>Dynamic array field class</dt>
558 Its instances (dynamic array fields) contain a variable number array
561 There are two types of dynamic array field classes: without or
562 with a length field. See
563 \ref api-tir-fc-link "Field classes with links to other field classes"
566 @image html darray-link.png "Dynamic array field class with a length field."
568 Create with bt_field_class_array_dynamic_create().
570 A dynamic array field class with a length field has the
575 \anchor api-tir-fc-darray-prop-len-fp
579 Field path of the linked length field class.
581 Get a dynamic array field class's length field path with
582 bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const().
588 Array field classes have the following common property:
592 \anchor api-tir-fc-array-prop-elem-fc
596 Class of the fields contained in the instances (array fields) of the
599 You cannot change the element field class once the array field class
602 Borrow an array field class's element field class with
603 Use bt_field_class_array_borrow_element_field_class() and
604 bt_field_class_array_borrow_element_field_class_const().
608 <h1>\anchor api-tir-fc-struct Structure field class</h1>
610 @image html fc-struct.png
612 A <strong><em>structure field class</em></strong> is the class
613 of a \bt_struct_field.
615 A structure field contains an ordered list of zero or more members. Each
616 structure field member is the instance of a structure field class
617 member. A structure field class member has a name, a field class,
620 Create a structure field class with bt_field_class_structure_create().
622 A structure field class has the following specific property:
626 \anchor api-tir-fc-struct-prop-members
630 Ordered list of members (zero or more) of the structure field class.
634 - A name, unique amongst all the member names of the same
635 structure field class.
639 The instances (structure fields) of a structure field class have
640 members which are instances of the corresponding structure field
643 Append a member to a structure field class with
644 bt_field_class_structure_append_member().
646 Borrow a member from a structure field class with
647 bt_field_class_structure_borrow_member_by_index(),
648 bt_field_class_structure_borrow_member_by_name(),
649 bt_field_class_structure_borrow_member_by_index_const(), and
650 bt_field_class_structure_borrow_member_by_name_const().
652 A structure field class member is a
653 \ref api-fund-unique-object "unique object": it
654 belongs to the structure field class which contains it.
656 The type of a structure field class member is
657 #bt_field_class_structure_member.
659 Get a structure field class member's name with
660 bt_field_class_structure_member_get_name().
662 Borrow a structure field class member's field class with
663 bt_field_class_structure_member_borrow_field_class() and
664 bt_field_class_structure_member_borrow_field_class_const().
666 Set a structure field class member's user attributes with
667 bt_field_class_structure_member_set_user_attributes().
669 Borrow a structure field class member's user attributes with
670 bt_field_class_structure_member_borrow_user_attributes() and
671 bt_field_class_structure_member_borrow_user_attributes_const().
675 <h1>\anchor api-tir-fc-opt Option field classes</h1>
677 @image html fc-opt.png
679 <strong><em>Option field classes</em></strong> are classes
682 An option field either does or doesn't contain a field, called its
685 An option field class is an \em abstract field class: you cannot create
686 one. An option field class either has a selector field (it's linked to a
687 selector field class; see
688 \ref api-tir-fc-link "Field classes with links to other field classes")
689 or none. Therefore, the concrete option field classes are:
692 <dt>Option field class without a selector field</dt>
694 Create with bt_field_class_option_without_selector_create().
696 An option field class without a selector field has no specific
700 <dt>Option field class with a boolean selector field</dt>
702 The linked selector field of an option field class's instance
703 (an option field) is a \bt_bool_field.
705 Consequently, the option field class's selector field class is
708 @image html opt-link.png "Option field class with a boolean selector field."
710 Create with bt_field_class_option_with_selector_field_bool_create().
712 An option field class with a boolean selector field has the
713 following specific property:
717 \anchor api-tir-fc-opt-prop-sel-rev
718 Selector is reversed?
721 Whether or not the linked boolean selector field makes the
722 option field class's instance (an option field) contain a field
723 when it's #BT_TRUE or when it's #BT_FALSE.
725 If this property is #BT_TRUE, then if the linked selector field
726 has the value #BT_FALSE, the option field contains a field.
729 bt_field_class_option_with_selector_field_bool_set_selector_is_reversed()
731 bt_field_class_option_with_selector_field_bool_selector_is_reversed().
736 <dt>Option field class with an unsigned selector field</dt>
738 The linked selector field of an option field class's instance
739 (an option field) is an \bt_uint_field.
741 Consequently, the option field class's selector field class is
745 bt_field_class_option_with_selector_field_integer_unsigned_create().
747 Pass an \bt_uint_rs on creation to set which values of the selector
748 field can make the option field contain a field.
750 An option field class with an unsigned integer selector field has
751 the following specific property:
755 \anchor api-tir-fc-opt-prop-uint-rs
756 Selector's unsigned integer ranges
759 If the linked unsigned integer selector field of an option
760 field class's instance (an option field) has a value which
761 intersects with the selector's unsigned integer ranges, then
762 the option field contains a field.
764 You cannot change the selector's unsigned integer ranges once
765 the option field class is created.
767 Borrow the selector's unsigned integer ranges from an
768 option field class with an unsigned integer selector field with
769 bt_field_class_option_with_selector_field_integer_unsigned_borrow_selector_ranges_const().
774 <dt>Option field class with a signed selector field</dt>
776 The linked selector field of an option field class's instance
777 (an option field) is a \bt_sint_field.
779 Consequently, the option field class's selector field class is
783 bt_field_class_option_with_selector_field_integer_signed_create().
785 Pass a \bt_sint_rs on creation to set which values of the selector
786 field can make the option field contain a field.
788 An option field class with a signed integer selector field has
789 the following specific property:
793 \anchor api-tir-fc-opt-prop-sint-rs
794 Selector's signed integer ranges
797 If the linked signed integer selector field of an option
798 field class's instance (an option field) has a value which
799 intersects with the selector's signed integer ranges, then
800 the option field contains a field.
802 You cannot change the selector's signed integer ranges once
803 the option field class is created.
805 Borrow the selector's signed integer ranges from an
806 option field class with a signed integer selector field with
807 bt_field_class_option_with_selector_field_integer_signed_borrow_selector_ranges_const().
813 Option field classes with a selector have the following common
818 \anchor api-tir-fc-opt-prop-sel-fp
822 Field path of the linked selector field class.
824 Borrow such an option field class's selector field path with
825 bt_field_class_option_with_selector_field_borrow_selector_field_path_const().
829 Option field classes have the following common property:
833 \anchor api-tir-fc-opt-prop-fc
837 Class of the optional field of an instance (option field) of the
840 You cannot change the optional field class once the option field
843 Borrow an option field class's optional field class with
844 Use bt_field_class_option_borrow_field_class() and
845 bt_field_class_option_borrow_field_class_const().
849 <h1>\anchor api-tir-fc-var Variant field classes</h1>
851 @image html fc-var.png
853 <strong><em>Variant field classes</em></strong> are classes
856 A variant field contains a field amongst one or more possible fields.
858 Variant field classes contain one or more options. Each variant field
859 class option has a name, a field class, user attributes, and integer
860 ranges, depending on the exact type.
862 A variant field class is an \em abstract field class: you cannot create
863 one. A variant field class either has a selector field (it's linked to a
864 selector field class; see
865 \ref api-tir-fc-link "Field classes with links to other field classes")
866 or none. Therefore, the concrete variant field classes are:
869 <dt>Variant field class without a selector field</dt>
871 Create with bt_field_class_variant_create(), passing \c NULL as
872 the selector field class.
874 Append an option to such a variant field class with
875 bt_field_class_variant_without_selector_append_option().
877 A variant field class without a selector field has no specific
881 <dt>Variant field class with an unsigned selector field</dt>
883 The linked selector field of a variant field class's instance
884 (a variant field) is an \bt_uint_field.
886 Consequently, the variant field class's selector field class is
889 @image html var-link.png "Variant field class with an unsigned integer selector field."
891 Create with bt_field_class_variant_create(), passing an
892 unsigned integer field class as the selector field class.
894 Append an option to such a variant field class with
895 bt_field_class_variant_with_selector_field_integer_unsigned_append_option().
897 Pass an \bt_uint_rs when you append an option to set which values of
898 the selector field can make the variant field have a given
901 Borrow such a variant field class's option with
902 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const()
904 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const().
907 <dt>Variant field class with a signed selector field</dt>
909 The linked selector field of a variant field class's instance
910 (a variant field) is a \bt_sint_field.
912 Consequently, the variant field class's selector field class is
915 Create with bt_field_class_variant_create(), passing a
916 signed integer field class as the selector field class.
918 Append an option to such a variant field class with
919 bt_field_class_variant_with_selector_field_integer_signed_append_option().
921 Pass a \bt_sint_rs when you append an option to set which values of
922 the selector field can make the variant field have a given
925 Borrow such a variant field class's option with
926 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const()
928 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const().
932 Variant field classes with a selector have the following common
937 \anchor api-tir-fc-var-prop-sel-fp
941 Field path of the linked selector field class.
943 Borrow such a variant field class's selector field path with
944 bt_field_class_variant_with_selector_field_borrow_selector_field_path_const().
948 Variant field classes have the following common property:
952 \anchor api-tir-fc-var-prop-opts
956 Options of the variant field class.
960 - A name, unique amongst all the option names of the same
965 If the variant field class is linked to a selector field class, then
966 each option also has an \bt_int_rs. In that case, the ranges of a
967 given option cannot overlap any range of any other option.
969 A variant field class must contain at least one option.
971 Depending on whether or not the variant field class has a selector
972 field class, append an option to a variant field class
973 with bt_field_class_variant_without_selector_append_option(),
974 bt_field_class_variant_with_selector_field_integer_unsigned_append_option(),
976 bt_field_class_variant_with_selector_field_integer_signed_append_option().
978 Get the number of options contained in a variant field class
979 with bt_field_class_variant_get_option_count().
981 A variant field class option is a
982 \ref api-fund-unique-object "unique object": it
983 belongs to the variant field class which contains it.
985 Borrow any variant field class's option with
986 bt_field_class_variant_borrow_option_by_index(),
987 bt_field_class_variant_borrow_option_by_name(),
988 bt_field_class_variant_borrow_option_by_index_const(), and
989 bt_field_class_variant_borrow_option_by_name_const().
991 Those functions return the common #bt_field_class_variant_option
992 type. Get the name of a variant field class option with
993 bt_field_class_variant_option_get_name(). Borrow a variant field
994 class option's field class with
995 bt_field_class_variant_option_borrow_field_class() and
996 bt_field_class_variant_option_borrow_field_class_const().
998 Borrow the option of a variant field classes with a selector field
1000 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(),
1001 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const(),
1002 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(), or
1003 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const(),
1004 depending on the selector field class's type.
1006 Those functions return the
1007 #bt_field_class_variant_with_selector_field_integer_unsigned_option or
1008 #bt_field_class_variant_with_selector_field_integer_signed_option type.
1009 \ref api-fund-c-typing "Upcast" those types to the
1010 #bt_field_class_variant_option type with
1011 bt_field_class_variant_with_selector_field_integer_unsigned_option_as_option_const()
1013 bt_field_class_variant_with_selector_field_integer_signed_option_as_option_const().
1015 Borrow the option's ranges from a variant field class with a
1016 selector field class with
1017 bt_field_class_variant_with_selector_field_integer_unsigned_option_borrow_ranges_const()
1019 bt_field_class_variant_with_selector_field_integer_signed_option_borrow_ranges_const().
1021 Set a variant field class option's user attributes with
1022 bt_field_class_variant_option_set_user_attributes().
1024 Borrow a variant field class option's user attributes with
1025 bt_field_class_variant_option_borrow_user_attributes() and
1026 bt_field_class_variant_option_borrow_user_attributes_const().
1030 <h1>\anchor api-tir-fc-link Field classes with links to other field classes</h1>
1032 \bt_cp_darray_fc, \bt_p_opt_fc, and \bt_p_var_fc \em can have links to
1033 other, preceding field classes.
1035 When a field class A has a link to another field class B, then
1036 an instance (\bt_field) of A has a link to an instance of B.
1038 This feature exists so that the linked field can contain the value of a
1039 dynamic property of the field. Those properties are:
1042 <dt>\bt_c_darray_field</dt>
1044 The linked field, a \bt_uint_field, contains the \b length of the
1045 dynamic array field.
1048 <dt>\bt_c_opt_field</dt>
1050 The linked field, either a \bt_bool_field or an \bt_int_field,
1051 indicates whether or not the option field has a field.
1054 <dt>\bt_c_var_field</dt>
1056 The linked field, an \bt_int_field, indicates the variant field's
1057 current selected field.
1061 Having a linked field class is <em>optional</em>: you always set the
1062 field properties with a dedicated function anyway. For example, even if
1063 a dynamic array field is linked to a preceding length field, you must
1064 still set its length with bt_field_array_dynamic_set_length(). In that
1065 case, the value of the length field must match what you pass to
1066 bt_field_array_dynamic_set_length().
1068 The purpose of this feature is to eventually save space when a
1069 \bt_sink_comp writes trace files: if the trace format can convey that
1070 a preceding, existing field represents the length of a dynamic array
1071 field, then the sink component doesn't need to write the dynamic array
1072 field's length twice. This is the case of the
1073 <a href="https://diamon.org/ctf/">Common Trace Format</a>, for
1076 @image html darray-link.png "A dynamic array field class linked to an unsigned integer field class."
1078 To link a field class A to a preceding field class B, pass
1079 field class B when you create field class A. For example, pass
1080 the \bt_uint_fc to bt_field_class_array_dynamic_create() to create a
1081 \bt_darray_fc with a length field.
1083 When you call bt_stream_class_set_packet_context_field_class(),
1084 bt_stream_class_set_event_common_context_field_class(),
1085 bt_event_class_set_specific_context_field_class(), or
1086 bt_event_class_set_payload_field_class() with a field class containing
1087 a field class A with a linked field class B, the path to
1088 B becomes available in A. The functions to borrow this field path are:
1090 - bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const()
1091 - bt_field_class_option_with_selector_field_borrow_selector_field_path_const()
1092 - bt_field_class_variant_with_selector_field_borrow_selector_field_path_const()
1094 A field path indicates how to reach a linked field from a given
1095 root <em>scope</em>. The available scopes are:
1098 <dt>#BT_FIELD_PATH_SCOPE_PACKET_CONTEXT</dt>
1100 Packet context field.
1102 See bt_packet_borrow_context_field_const().
1105 <dt>#BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT</dt>
1107 Event common context field.
1109 See bt_event_borrow_common_context_field_const().
1112 <dt>#BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT</dt>
1114 Event specific context field.
1116 See bt_event_borrow_specific_context_field_const().
1119 <dt>#BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD</dt>
1121 Event payload field.
1123 See bt_event_borrow_payload_field_const().
1127 The rules regarding field class A vs. field class B (linked
1130 - If A is within a packet context field class, B must also be in the
1131 same packet context field class.
1133 See bt_stream_class_set_packet_context_field_class().
1135 - If A is within a event common context field class, B must be in one
1138 - The same event common context field class.
1139 - The packet context field class of the same \bt_stream_cls.
1141 See bt_stream_class_set_event_common_context_field_class().
1143 - If A is within an event specific context field class, B must be in
1146 - The same event specific context field class.
1147 - The event common context field class of the same stream class.
1148 - The packet context field class of the same stream class.
1150 See bt_event_class_set_specific_context_field_class().
1152 - If A is within an event payload field class, B must be in one of:
1154 - The same event payload field class.
1155 - The event specific context field class of the same \bt_ev_cls.
1156 - The event common context field class of the same stream class.
1157 - The packet context field class of the same stream class.
1159 See bt_event_class_set_payload_field_class().
1161 - If both A and B are in the same scope, then:
1163 - The lowest common ancestor field class of A and B must be a
1168 Considering that the members of a structure field class are ordered,
1169 then B must be part of a member that's before the member which
1170 contains A in their lowest common ancestor structure field class.
1172 - The path from the lowest common ancestor structure field class of A
1173 and B to A and to B must only contain structure field classes.
1175 - If A is in a different scope than B, the path from the root scope of B
1176 to B must only contain structure field classes.
1185 @typedef struct bt_field_class bt_field_class;
1200 Field class type enumerators.
1202 typedef enum bt_field_class_type
{
1207 BT_FIELD_CLASS_TYPE_BOOL
= 1ULL << 0,
1213 BT_FIELD_CLASS_TYPE_BIT_ARRAY
= 1ULL << 1,
1219 No field class has this type: use it with
1220 bt_field_class_type_is().
1222 BT_FIELD_CLASS_TYPE_INTEGER
= 1ULL << 2,
1228 This type conceptually inherits #BT_FIELD_CLASS_TYPE_INTEGER.
1230 BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER
= (1ULL << 3) | BT_FIELD_CLASS_TYPE_INTEGER
,
1236 This type conceptually inherits #BT_FIELD_CLASS_TYPE_INTEGER.
1238 BT_FIELD_CLASS_TYPE_SIGNED_INTEGER
= (1ULL << 4) | BT_FIELD_CLASS_TYPE_INTEGER
,
1244 This type conceptually inherits #BT_FIELD_CLASS_TYPE_INTEGER.
1246 No field class has this type: use it with
1247 bt_field_class_type_is().
1249 BT_FIELD_CLASS_TYPE_ENUMERATION
= 1ULL << 5,
1255 This type conceptually inherits #BT_FIELD_CLASS_TYPE_ENUMERATION
1256 and #BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER.
1258 BT_FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION
= BT_FIELD_CLASS_TYPE_ENUMERATION
| BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER
,
1264 This type conceptually inherits #BT_FIELD_CLASS_TYPE_ENUMERATION
1265 and #BT_FIELD_CLASS_TYPE_SIGNED_INTEGER.
1267 BT_FIELD_CLASS_TYPE_SIGNED_ENUMERATION
= BT_FIELD_CLASS_TYPE_ENUMERATION
| BT_FIELD_CLASS_TYPE_SIGNED_INTEGER
,
1273 No field class has this type: use it with
1274 bt_field_class_type_is().
1276 BT_FIELD_CLASS_TYPE_REAL
= 1ULL << 6,
1280 Single-precision \bt_real_fc.
1282 This type conceptually inherits #BT_FIELD_CLASS_TYPE_REAL.
1284 BT_FIELD_CLASS_TYPE_SINGLE_PRECISION_REAL
= (1ULL << 7) | BT_FIELD_CLASS_TYPE_REAL
,
1288 Double-precision \bt_real_fc.
1290 This type conceptually inherits #BT_FIELD_CLASS_TYPE_REAL.
1292 BT_FIELD_CLASS_TYPE_DOUBLE_PRECISION_REAL
= (1ULL << 8) | BT_FIELD_CLASS_TYPE_REAL
,
1298 BT_FIELD_CLASS_TYPE_STRING
= 1ULL << 9,
1304 BT_FIELD_CLASS_TYPE_STRUCTURE
= 1ULL << 10,
1310 No field class has this type: use it with
1311 bt_field_class_type_is().
1313 BT_FIELD_CLASS_TYPE_ARRAY
= 1ULL << 11,
1319 This type conceptually inherits #BT_FIELD_CLASS_TYPE_ARRAY.
1321 BT_FIELD_CLASS_TYPE_STATIC_ARRAY
= (1ULL << 12) | BT_FIELD_CLASS_TYPE_ARRAY
,
1327 This type conceptually inherits #BT_FIELD_CLASS_TYPE_ARRAY.
1329 No field class has this type: use it with
1330 bt_field_class_type_is().
1332 BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY
= (1ULL << 13) | BT_FIELD_CLASS_TYPE_ARRAY
,
1336 \bt_c_darray_fc (without a length field).
1338 This type conceptually inherits
1339 #BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY.
1341 BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD
= (1ULL << 14) | BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY
,
1345 \bt_c_darray_fc (with a length field).
1347 This type conceptually inherits
1348 #BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY.
1350 BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD
= (1ULL << 15) | BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY
,
1356 No field class has this type: use it with
1357 bt_field_class_type_is().
1359 BT_FIELD_CLASS_TYPE_OPTION
= 1ULL << 16,
1363 \bt_c_opt_fc (without a selector field).
1365 BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD
= (1ULL << 17) | BT_FIELD_CLASS_TYPE_OPTION
,
1369 \bt_c_opt_fc (with a selector field).
1371 This type conceptually inherits #BT_FIELD_CLASS_TYPE_OPTION.
1373 No field class has this type: use it with
1374 bt_field_class_type_is().
1376 BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD
= (1ULL << 18) | BT_FIELD_CLASS_TYPE_OPTION
,
1380 \bt_c_opt_fc (with a boolean selector field).
1382 This type conceptually inherits
1383 #BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD.
1385 BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD
= (1ULL << 19) | BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD
,
1389 \bt_c_opt_fc (with an integer selector field).
1391 This type conceptually inherits
1392 #BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD.
1394 No field class has this type: use it with
1395 bt_field_class_type_is().
1397 BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD
= (1ULL << 20) | BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD
,
1401 \bt_c_opt_fc (with an unsigned integer selector field).
1403 This type conceptually inherits
1404 #BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD.
1406 BT_FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
= (1ULL << 21) | BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD
,
1410 \bt_c_opt_fc (with a signed integer selector field).
1412 This type conceptually inherits
1413 #BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD.
1415 BT_FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD
= (1ULL << 22) | BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD
,
1421 No field class has this type: use it with
1422 bt_field_class_type_is().
1424 BT_FIELD_CLASS_TYPE_VARIANT
= 1ULL << 23,
1428 \bt_c_var_fc (without a selector field).
1430 BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD
= (1ULL << 24) | BT_FIELD_CLASS_TYPE_VARIANT
,
1434 \bt_c_var_fc (with a selector field).
1436 This type conceptually inherits
1437 #BT_FIELD_CLASS_TYPE_VARIANT.
1439 No field class has this type: use it with
1440 bt_field_class_type_is().
1442 BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD
= (1ULL << 25) | BT_FIELD_CLASS_TYPE_VARIANT
,
1446 \bt_c_var_fc (with an integer selector field).
1448 This type conceptually inherits
1449 #BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD.
1451 No field class has this type: use it with
1452 bt_field_class_type_is().
1454 BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD
= (1ULL << 26) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD
,
1458 \bt_c_opt_fc (with an unsigned integer selector field).
1460 This type conceptually inherits
1461 #BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD.
1463 BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
= (1ULL << 27) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD
,
1467 \bt_c_opt_fc (with a signed integer selector field).
1469 This type conceptually inherits
1470 #BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD.
1472 BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD
= (1ULL << 28) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD
,
1475 * Make sure the enumeration type is a 64-bit integer in case
1476 * the project needs field class types in the future.
1478 * This is not part of the API.
1480 __BT_FIELD_CLASS_TYPE_BIG_VALUE
= 1ULL << 62,
1481 } bt_field_class_type
;
1485 Returns the type enumerator of the field class \bt_p{field_class}.
1487 @param[in] field_class
1488 Field class of which to get the type enumerator
1491 Type enumerator of \bt_p{field_class}.
1493 @bt_pre_not_null{field_class}
1495 @sa bt_field_class_type_is() —
1496 Returns whether or not the type of a field class conceptually is a
1499 extern bt_field_class_type
bt_field_class_get_type(
1500 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
1504 Returns whether or not the field class type \bt_p{type} conceptually
1505 \em is the field class type \bt_p{other_type}.
1507 For example, an \bt_uint_fc conceptually \em is an integer field class,
1511 bt_field_class_type_is(BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER, BT_FIELD_CLASS_TYPE_INTEGER)
1517 Field class type to check against \bt_p{other_type}.
1518 @param[in] other_type
1519 Field class type against which to check \bt_p{type}.
1522 #BT_TRUE if \bt_p{type} conceptually \em is \bt_p{other_type}.
1524 @sa bt_field_class_get_type() —
1525 Returns the type enumerator of a field class.
1528 bt_bool
bt_field_class_type_is(const bt_field_class_type type
,
1529 const bt_field_class_type other_type
) __BT_NOEXCEPT
1531 return (type
& other_type
) == other_type
;
1537 @name Common property
1543 Sets the user attributes of the field class \bt_p{field_class} to
1544 \bt_p{user_attributes}.
1546 See the \ref api-tir-fc-prop-user-attrs "user attributes" property.
1549 When you create a field class with one of the
1550 <code>bt_field_class_*_create()</code> functions, the field class's
1551 initial user attributes is an empty \bt_map_val. Therefore you can
1552 borrow it with bt_field_class_borrow_user_attributes() and fill it
1553 directly instead of setting a new one with this function.
1555 @param[in] field_class
1556 Field class of which to set the user attributes to
1557 \bt_p{user_attributes}.
1558 @param[in] user_attributes
1559 New user attributes of \bt_p{field_class}.
1561 @bt_pre_not_null{field_class}
1562 @bt_pre_hot{field_class}
1563 @bt_pre_not_null{user_attributes}
1564 @bt_pre_is_map_val{user_attributes}
1566 @sa bt_field_class_borrow_user_attributes() —
1567 Borrows the user attributes of a field class.
1569 extern void bt_field_class_set_user_attributes(
1570 bt_field_class
*field_class
,
1571 const bt_value
*user_attributes
) __BT_NOEXCEPT
;
1575 Borrows the user attributes of the field class \bt_p{field_class}.
1577 See the \ref api-tir-fc-prop-user-attrs "user attributes" property.
1580 When you create a field class with one of the
1581 <code>bt_field_class_*_create()</code> functions, the field class's
1582 initial user attributes is an empty \bt_map_val.
1584 @param[in] field_class
1585 Field class from which to borrow the user attributes.
1588 User attributes of \bt_p{field_class} (a \bt_map_val).
1590 @bt_pre_not_null{field_class}
1592 @sa bt_field_class_set_user_attributes() —
1593 Sets the user attributes of a field class.
1594 @sa bt_field_class_borrow_user_attributes_const() —
1595 \c const version of this function.
1597 extern bt_value
*bt_field_class_borrow_user_attributes(
1598 bt_field_class
*field_class
) __BT_NOEXCEPT
;
1602 Borrows the user attributes of the field class \bt_p{field_class}
1605 See bt_field_class_borrow_user_attributes().
1607 extern const bt_value
*bt_field_class_borrow_user_attributes_const(
1608 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
1613 @name Boolean field class
1619 Creates a \bt_bool_fc from the trace class \bt_p{trace_class}.
1621 On success, the returned boolean field class has the following
1629 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
1630 <td>Empty \bt_map_val
1633 @param[in] trace_class
1634 Trace class from which to create a boolean field class.
1637 New boolean field class reference, or \c NULL on memory error.
1639 @bt_pre_not_null{trace_class}
1641 extern bt_field_class
*bt_field_class_bool_create(
1642 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
1649 @name Bit array field class
1655 Creates a \bt_ba_fc with the length \bt_p{length} from the trace
1656 class \bt_p{trace_class}.
1658 On success, the returned bit array field class has the following
1666 <td>\ref api-tir-fc-ba-prop-len "Length"
1669 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
1670 <td>Empty \bt_map_val
1673 @param[in] trace_class
1674 Trace class from which to create a bit array field class.
1676 Length (number of bits) of the instances of the bit array field
1680 New bit array field class reference, or \c NULL on memory error.
1682 @bt_pre_not_null{trace_class}
1684 0 < \bt_p{length} ≤ 64.
1686 extern bt_field_class
*bt_field_class_bit_array_create(
1687 bt_trace_class
*trace_class
, uint64_t length
) __BT_NOEXCEPT
;
1691 Returns the length of the \bt_ba_fc \bt_p{field_class}.
1693 See the \ref api-tir-fc-ba-prop-len "length" property.
1695 @param[in] field_class
1696 Bit array field class of which to get the length.
1699 Length of \bt_p{field_class}.
1701 @bt_pre_not_null{field_class}
1702 @bt_pre_is_ba_fc{field_class}
1704 extern uint64_t bt_field_class_bit_array_get_length(
1705 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
1712 @name Integer field class
1718 Sets the field value range of the \bt_int_fc \bt_p{field_class}
1721 See the \ref api-tir-fc-int-prop-size "field value range" property.
1723 @param[in] field_class
1724 Integer field class of which to set the field value range to
1731 <dt>Unsigned integer field class</dt>
1732 <dd>[0, 2<sup><em>N</em></sup> − 1]</dd>
1734 <dt>Signed integer field class</dt>
1735 <dd>[−2<sup><em>N</em> − 1</sup>, 2<sup><em>N</em> − 1</sup> − 1]</dd>
1739 @bt_pre_not_null{field_class}
1740 @bt_pre_hot{field_class}
1741 @bt_pre_is_int_fc{field_class}
1743 1 ⩽ \bt_p{n} ⩽ 64.
1745 @sa bt_field_class_integer_get_field_value_range() —
1746 Returns the field value range of an integer field class.
1748 extern void bt_field_class_integer_set_field_value_range(
1749 bt_field_class
*field_class
, uint64_t n
) __BT_NOEXCEPT
;
1753 Returns the field value range of the \bt_int_fc \bt_p{field_class}.
1755 See the \ref api-tir-fc-int-prop-size "field value range" property.
1757 @param[in] field_class
1758 Integer field class of which to get the field value range.
1762 Field value range of \bt_p{field_class}, that is, \em N in:
1765 <dt>Unsigned integer field class</dt>
1766 <dd>[0, 2<sup><em>N</em></sup> − 1]</dd>
1768 <dt>Signed integer field class</dt>
1769 <dd>[−2<sup><em>N</em></sup>, 2<sup><em>N</em></sup> − 1]</dd>
1773 @bt_pre_not_null{field_class}
1774 @bt_pre_is_int_fc{field_class}
1776 @sa bt_field_class_integer_set_field_value_range() —
1777 Sets the field value range of an integer field class.
1779 extern uint64_t bt_field_class_integer_get_field_value_range(
1780 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
1784 Integer field class preferred display bases.
1786 typedef enum bt_field_class_integer_preferred_display_base
{
1791 BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_BINARY
= 2,
1797 BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_OCTAL
= 8,
1803 BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
= 10,
1809 BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_HEXADECIMAL
= 16,
1810 } bt_field_class_integer_preferred_display_base
;
1814 Sets the preferred display base of the \bt_int_fc \bt_p{field_class}
1815 to \bt_p{preferred_display_base}.
1817 See the \ref api-tir-fc-int-prop-base "preferred display base" property.
1819 @param[in] field_class
1820 Integer field class of which to set the preferred display base to
1821 \bt_p{preferred_display_base}.
1822 @param[in] preferred_display_base
1823 New preferred display base of \bt_p{field_class}.
1825 @bt_pre_not_null{field_class}
1826 @bt_pre_hot{field_class}
1827 @bt_pre_is_int_fc{field_class}
1829 @sa bt_field_class_integer_get_preferred_display_base() —
1830 Returns the preferred display base of an integer field class.
1832 extern void bt_field_class_integer_set_preferred_display_base(
1833 bt_field_class
*field_class
,
1834 bt_field_class_integer_preferred_display_base preferred_display_base
)
1839 Returns the preferred display base of the \bt_int_fc
1842 See the \ref api-tir-fc-int-prop-base "preferred display base" property.
1844 @param[in] field_class
1845 Integer field class of which to get the preferred display base.
1847 @retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_BINARY
1849 @retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_OCTAL
1851 @retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
1853 @retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_HEXADECIMAL
1856 @bt_pre_not_null{field_class}
1857 @bt_pre_is_int_fc{field_class}
1859 @sa bt_field_class_integer_set_preferred_display_base() —
1860 Sets the preferred display base of an integer field class.
1862 extern bt_field_class_integer_preferred_display_base
1863 bt_field_class_integer_get_preferred_display_base(
1864 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
1869 @name Unsigned integer field class
1875 Creates an \bt_uint_fc from the trace class \bt_p{trace_class}.
1877 On success, the returned unsigned integer field class has the following
1885 <td>\ref api-tir-fc-int-prop-size "Field value range"
1886 <td>[0, 2<sup>64</sup> − 1]
1888 <td>\ref api-tir-fc-int-prop-base "Preferred display base"
1889 <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
1891 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
1892 <td>Empty \bt_map_val
1895 @param[in] trace_class
1896 Trace class from which to create an unsigned integer field class.
1899 New unsigned integer field class reference, or \c NULL on memory error.
1901 @bt_pre_not_null{trace_class}
1903 extern bt_field_class
*bt_field_class_integer_unsigned_create(
1904 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
1909 @name Signed integer field class
1915 Creates an \bt_sint_fc from the trace class \bt_p{trace_class}.
1917 On success, the returned signed integer field class has the following
1925 <td>\ref api-tir-fc-int-prop-size "Field value range"
1926 <td>[−2<sup>63</sup>, 2<sup>63</sup> − 1]
1928 <td>\ref api-tir-fc-int-prop-base "Preferred display base"
1929 <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
1931 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
1932 <td>Empty \bt_map_val
1935 @param[in] trace_class
1936 Trace class from which to create a signed integer field class.
1939 New signed integer field class reference, or \c NULL on memory error.
1941 @bt_pre_not_null{trace_class}
1943 extern bt_field_class
*bt_field_class_integer_signed_create(
1944 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
1949 @name Single-precision real field class
1955 Creates a single-precision \bt_real_fc from the trace class
1958 On success, the returned single-precision real field class has the
1959 following property value:
1966 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
1967 <td>Empty \bt_map_val
1970 @param[in] trace_class
1971 Trace class from which to create a single-preicision real
1975 New single-precision real field class reference, or \c NULL on
1978 @bt_pre_not_null{trace_class}
1980 extern bt_field_class
*bt_field_class_real_single_precision_create(
1981 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
1986 @name Double-precision real field class
1992 Creates a double-precision \bt_real_fc from the trace class
1995 On success, the returned double-precision real field class has the
1996 following property value:
2003 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2004 <td>Empty \bt_map_val
2007 @param[in] trace_class
2008 Trace class from which to create a double-preicision real
2012 New double-precision real field class reference, or \c NULL on
2015 @bt_pre_not_null{trace_class}
2017 extern bt_field_class
*bt_field_class_real_double_precision_create(
2018 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
2023 @name Enumeration field class
2029 Array of \c const \bt_enum_fc labels.
2031 Returned by bt_field_class_enumeration_unsigned_get_mapping_labels_for_value()
2032 and bt_field_class_enumeration_signed_get_mapping_labels_for_value().
2034 typedef char const * const *bt_field_class_enumeration_mapping_label_array
;
2039 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value()
2041 bt_field_class_enumeration_signed_get_mapping_labels_for_value().
2043 typedef enum bt_field_class_enumeration_get_mapping_labels_for_value_status
{
2048 BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2054 BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2055 } bt_field_class_enumeration_get_mapping_labels_for_value_status
;
2059 Status codes for bt_field_class_enumeration_unsigned_add_mapping()
2060 and bt_field_class_enumeration_signed_add_mapping().
2062 typedef enum bt_field_class_enumeration_add_mapping_status
{
2067 BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2073 BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2074 } bt_field_class_enumeration_add_mapping_status
;
2079 @name Enumeration field class mapping
2084 @typedef struct bt_field_class_enumeration_mapping bt_field_class_enumeration_mapping;
2087 Enumeration field class mapping.
2092 Returns the number of mappings contained in the \bt_enum_fc
2095 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2097 @param[in] field_class
2098 Enumeration field class of which to get the number of contained
2102 Number of contained mappings in \bt_p{field_class}.
2104 @bt_pre_not_null{field_class}
2105 @bt_pre_is_enum_fc{field_class}
2107 extern uint64_t bt_field_class_enumeration_get_mapping_count(
2108 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
2112 Returns the label of the \bt_enum_fc mapping \bt_p{mapping}.
2114 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2117 Enumeration field class mapping of which to get the label.
2121 Label of \bt_p{mapping}.
2123 The returned pointer remains valid as long as \bt_p{mapping} exists.
2126 @bt_pre_not_null{mapping}
2128 extern const char *bt_field_class_enumeration_mapping_get_label(
2129 const bt_field_class_enumeration_mapping
*mapping
)
2135 @name Unsigned enumeration field class
2141 Creates an \bt_uenum_fc from the trace class \bt_p{trace_class}.
2143 On success, the returned unsigned enumeration field class has the
2144 following property values:
2151 <td>\ref api-tir-fc-int-prop-size "Field value range"
2152 <td>[0, 2<sup>64</sup> − 1]
2154 <td>\ref api-tir-fc-int-prop-base "Preferred display base"
2155 <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
2157 <td>\ref api-tir-fc-enum-prop-mappings "Mappings"
2160 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2161 <td>Empty \bt_map_val
2164 @param[in] trace_class
2165 Trace class from which to create an unsigned enumeration field
2169 New unsigned enumeration field class reference, or \c NULL on memory
2172 @bt_pre_not_null{trace_class}
2174 extern bt_field_class
*bt_field_class_enumeration_unsigned_create(
2175 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
2179 Adds a mapping to the \bt_uenum_fc \bt_p{field_class} having the
2180 label \bt_p{label} and the unsigned integer ranges \bt_p{ranges}.
2182 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2184 @param[in] field_class
2185 Unsigned enumeration field class to which to add a mapping having
2186 the label \bt_p{label} and the integer ranges \bt_p{ranges}.
2188 Label of the mapping to add to \bt_p{field_class} (copied).
2190 Unsigned integer ranges of the mapping to add to
2193 @retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK
2195 @retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR
2198 @bt_pre_not_null{field_class}
2199 @bt_pre_hot{field_class}
2200 @bt_pre_is_uenum_fc{field_class}
2201 @bt_pre_not_null{label}
2203 \bt_p{field_class} has no mapping with the label \bt_p{label}.
2204 @bt_pre_not_null{ranges}
2206 \bt_p{ranges} contains one or more unsigned integer ranges.
2208 extern bt_field_class_enumeration_add_mapping_status
2209 bt_field_class_enumeration_unsigned_add_mapping(
2210 bt_field_class
*field_class
, const char *label
,
2211 const bt_integer_range_set_unsigned
*ranges
) __BT_NOEXCEPT
;
2215 Borrows the mapping at index \bt_p{index} from the
2216 \bt_uenum_fc \bt_p{field_class}.
2218 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2220 @param[in] field_class
2221 Unsigned enumeration field class from which to borrow the mapping at
2224 Index of the mapping to borrow from \bt_p{field_class}.
2228 \em Borrowed reference of the mapping of
2229 \bt_p{field_class} at index \bt_p{index}.
2231 The returned pointer remains valid as long as \bt_p{field_class}
2235 @bt_pre_not_null{field_class}
2236 @bt_pre_is_uenum_fc{field_class}
2238 \bt_p{index} is less than the number of mappings in
2239 \bt_p{field_class} (as returned by
2240 bt_field_class_enumeration_get_mapping_count()).
2242 @sa bt_field_class_enumeration_get_mapping_count() —
2243 Returns the number of mappings contained in an
2244 enumeration field class.
2246 extern const bt_field_class_enumeration_unsigned_mapping
*
2247 bt_field_class_enumeration_unsigned_borrow_mapping_by_index_const(
2248 const bt_field_class
*field_class
, uint64_t index
)
2253 Borrows the mapping having the label \bt_p{label} from the
2254 \bt_uenum_fc \bt_p{field_class}.
2256 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2258 If there's no mapping having the label \bt_p{label} in
2259 \bt_p{field_class}, this function returns \c NULL.
2261 @param[in] field_class
2262 Unsigned enumeration field class from which to borrow the mapping
2263 having the label \bt_p{label}.
2265 Label of the mapping to borrow from \bt_p{field_class}.
2269 \em Borrowed reference of the mapping of
2270 \bt_p{field_class} having the label \bt_p{label}, or \c NULL
2273 The returned pointer remains valid as long as \bt_p{field_class}
2277 @bt_pre_not_null{field_class}
2278 @bt_pre_is_uenum_fc{field_class}
2279 @bt_pre_not_null{label}
2281 extern const bt_field_class_enumeration_unsigned_mapping
*
2282 bt_field_class_enumeration_unsigned_borrow_mapping_by_label_const(
2283 const bt_field_class
*field_class
, const char *label
)
2288 Returns an array of all the labels of the mappings of the
2289 \bt_uenum_fc \bt_p{field_class} of which the \bt_p_uint_rg contain
2290 the integral value \bt_p{value}.
2292 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2294 This function sets \bt_p{*labels} to the resulting array and
2295 \bt_p{*count} to the number of labels in \bt_p{*labels}.
2297 On success, if there's no mapping ranges containing the value
2298 \bt_p{value}, \bt_p{*count} is 0.
2300 @param[in] field_class
2301 Unsigned enumeration field class from which to get the labels of the
2302 mappings of which the ranges contain \bt_p{value}.
2304 Value for which to get the mapped labels in \bt_p{field_class}.
2307 <strong>On success</strong>, \bt_p{*labels}
2308 is an array of labels of the mappings of \bt_p{field_class}
2309 containing \bt_p{value}.
2311 The number of labels in \bt_p{*labels} is \bt_p{*count}.
2313 The array is owned by \bt_p{field_class} and remains valid as long
2316 - \bt_p{field_class} is not modified.
2317 - You don't call this function again with \bt_p{field_class}.
2320 <strong>On success</strong>, \bt_p{*count} is the number of labels
2321 in \bt_p{*labels} (can be 0).
2323 @retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK
2325 @retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR
2328 @bt_pre_not_null{field_class}
2329 @bt_pre_is_uenum_fc{field_class}
2330 @bt_pre_not_null{labels}
2331 @bt_pre_not_null{count}
2333 extern bt_field_class_enumeration_get_mapping_labels_for_value_status
2334 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value(
2335 const bt_field_class
*field_class
, uint64_t value
,
2336 bt_field_class_enumeration_mapping_label_array
*labels
,
2337 uint64_t *count
) __BT_NOEXCEPT
;
2342 @name Unsigned enumeration field class mapping
2347 @typedef struct bt_field_class_enumeration_unsigned_mapping bt_field_class_enumeration_unsigned_mapping;
2350 Unsigned enumeration field class mapping.
2355 Borrows the \bt_p_uint_rg from the \bt_uenum_fc mapping
2358 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2361 Unsigned enumeration field class mapping from which to borrow the
2362 unsigned integer ranges.
2365 Unsigned integer ranges of \bt_p{mapping}.
2367 @bt_pre_not_null{mapping}
2369 extern const bt_integer_range_set_unsigned
*
2370 bt_field_class_enumeration_unsigned_mapping_borrow_ranges_const(
2371 const bt_field_class_enumeration_unsigned_mapping
*mapping
)
2376 \ref api-fund-c-typing "Upcasts" the \bt_uenum_fc mapping
2377 \bt_p{mapping} to the common #bt_field_class_enumeration_mapping
2380 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2384 Unsigned enumeration field class mapping to upcast.
2390 \bt_p{mapping} as a common enumeration field class mapping.
2393 const bt_field_class_enumeration_mapping
*
2394 bt_field_class_enumeration_unsigned_mapping_as_mapping_const(
2395 const bt_field_class_enumeration_unsigned_mapping
*mapping
)
2398 return __BT_UPCAST_CONST(bt_field_class_enumeration_mapping
, mapping
);
2404 @name Signed enumeration field class
2410 Creates a \bt_senum_fc from the trace class \bt_p{trace_class}.
2412 On success, the returned signed enumeration field class has the
2413 following property values:
2420 <td>\ref api-tir-fc-int-prop-size "Field value range"
2421 <td>[−2<sup>63</sup>, 2<sup>63</sup> − 1]
2423 <td>\ref api-tir-fc-int-prop-base "Preferred display base"
2424 <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
2426 <td>\ref api-tir-fc-enum-prop-mappings "Mappings"
2429 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2430 <td>Empty \bt_map_val
2433 @param[in] trace_class
2434 Trace class from which to create a signed enumeration field
2438 New signed enumeration field class reference, or \c NULL on memory
2441 @bt_pre_not_null{trace_class}
2443 extern bt_field_class
*bt_field_class_enumeration_signed_create(
2444 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
2448 Adds a mapping to the \bt_senum_fc \bt_p{field_class} having the
2449 label \bt_p{label} and the \bt_p_sint_rg \bt_p{ranges}.
2451 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2453 @param[in] field_class
2454 Signed enumeration field class to which to add a mapping having
2455 the label \bt_p{label} and the integer ranges \bt_p{ranges}.
2457 Label of the mapping to add to \bt_p{field_class} (copied).
2459 Signed integer ranges of the mapping to add to
2462 @retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK
2464 @retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR
2467 @bt_pre_not_null{field_class}
2468 @bt_pre_hot{field_class}
2469 @bt_pre_is_senum_fc{field_class}
2470 @bt_pre_not_null{label}
2472 \bt_p{field_class} has no mapping with the label \bt_p{label}.
2473 @bt_pre_not_null{ranges}
2475 \bt_p{ranges} contains one or more signed integer ranges.
2477 extern bt_field_class_enumeration_add_mapping_status
2478 bt_field_class_enumeration_signed_add_mapping(
2479 bt_field_class
*field_class
, const char *label
,
2480 const bt_integer_range_set_signed
*ranges
) __BT_NOEXCEPT
;
2484 Borrows the mapping at index \bt_p{index} from the
2485 \bt_senum_fc \bt_p{field_class}.
2487 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2489 @param[in] field_class
2490 Signed enumeration field class from which to borrow the mapping at
2493 Index of the mapping to borrow from \bt_p{field_class}.
2497 \em Borrowed reference of the mapping of
2498 \bt_p{field_class} at index \bt_p{index}.
2500 The returned pointer remains valid as long as \bt_p{field_class}
2504 @bt_pre_not_null{field_class}
2505 @bt_pre_is_senum_fc{field_class}
2507 \bt_p{index} is less than the number of mappings in
2508 \bt_p{field_class} (as returned by
2509 bt_field_class_enumeration_get_mapping_count()).
2511 @sa bt_field_class_enumeration_get_mapping_count() —
2512 Returns the number of mappings contained in an
2513 enumeration field class.
2515 extern const bt_field_class_enumeration_signed_mapping
*
2516 bt_field_class_enumeration_signed_borrow_mapping_by_index_const(
2517 const bt_field_class
*field_class
, uint64_t index
)
2522 Borrows the mapping having the label \bt_p{label} from the
2523 \bt_senum_fc \bt_p{field_class}.
2525 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2527 If there's no mapping having the label \bt_p{label} in
2528 \bt_p{field_class}, this function returns \c NULL.
2530 @param[in] field_class
2531 Signed enumeration field class from which to borrow the mapping
2532 having the label \bt_p{label}.
2534 Label of the mapping to borrow from \bt_p{field_class}.
2538 \em Borrowed reference of the mapping of
2539 \bt_p{field_class} having the label \bt_p{label}, or \c NULL
2542 The returned pointer remains valid as long as \bt_p{field_class}
2546 @bt_pre_not_null{field_class}
2547 @bt_pre_is_senum_fc{field_class}
2548 @bt_pre_not_null{label}
2550 extern const bt_field_class_enumeration_signed_mapping
*
2551 bt_field_class_enumeration_signed_borrow_mapping_by_label_const(
2552 const bt_field_class
*field_class
, const char *label
)
2557 Returns an array of all the labels of the mappings of the
2558 \bt_senum_fc \bt_p{field_class} of which the \bt_p_sint_rg contain
2559 the integral value \bt_p{value}.
2561 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2563 This function sets \bt_p{*labels} to the resulting array and
2564 \bt_p{*count} to the number of labels in \bt_p{*labels}.
2566 On success, if there's no mapping ranges containing the value
2567 \bt_p{value}, \bt_p{*count} is 0.
2569 @param[in] field_class
2570 Signed enumeration field class from which to get the labels of the
2571 mappings of which the ranges contain \bt_p{value}.
2573 Value for which to get the mapped labels in \bt_p{field_class}.
2576 <strong>On success</strong>, \bt_p{*labels}
2577 is an array of labels of the mappings of \bt_p{field_class}
2578 containing \bt_p{value}.
2580 The number of labels in \bt_p{*labels} is \bt_p{*count}.
2582 The array is owned by \bt_p{field_class} and remains valid as long
2585 - \bt_p{field_class} is not modified.
2586 - You don't call this function again with \bt_p{field_class}.
2589 <strong>On success</strong>, \bt_p{*count} is the number of labels
2590 in \bt_p{*labels} (can be 0).
2592 @retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK
2594 @retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR
2597 @bt_pre_not_null{field_class}
2598 @bt_pre_is_senum_fc{field_class}
2599 @bt_pre_not_null{labels}
2600 @bt_pre_not_null{count}
2602 extern bt_field_class_enumeration_get_mapping_labels_for_value_status
2603 bt_field_class_enumeration_signed_get_mapping_labels_for_value(
2604 const bt_field_class
*field_class
, int64_t value
,
2605 bt_field_class_enumeration_mapping_label_array
*labels
,
2606 uint64_t *count
) __BT_NOEXCEPT
;
2611 @name Signed enumeration field class mapping
2616 @typedef struct bt_field_class_enumeration_signed_mapping bt_field_class_enumeration_signed_mapping;
2619 Signed enumeration field class mapping.
2624 Borrows the \bt_p_sint_rg from the \bt_senum_fc mapping
2627 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2630 Signed enumeration field class mapping from which to borrow the
2631 signed integer ranges.
2634 Signed integer ranges of \bt_p{mapping}.
2636 @bt_pre_not_null{mapping}
2638 extern const bt_integer_range_set_signed
*
2639 bt_field_class_enumeration_signed_mapping_borrow_ranges_const(
2640 const bt_field_class_enumeration_signed_mapping
*mapping
)
2645 \ref api-fund-c-typing "Upcasts" the \bt_senum_fc mapping
2646 \bt_p{mapping} to the common #bt_field_class_enumeration_mapping
2649 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2653 Signed enumeration field class mapping to upcast.
2659 \bt_p{mapping} as a common enumeration field class mapping.
2662 const bt_field_class_enumeration_mapping
*
2663 bt_field_class_enumeration_signed_mapping_as_mapping_const(
2664 const bt_field_class_enumeration_signed_mapping
*mapping
)
2667 return __BT_UPCAST_CONST(bt_field_class_enumeration_mapping
, mapping
);
2673 @name String field class
2679 Creates a \bt_string_fc from the trace class \bt_p{trace_class}.
2681 On success, the returned string field class has the following property
2689 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2690 <td>Empty \bt_map_val
2693 @param[in] trace_class
2694 Trace class from which to create a string field class.
2697 New string field class reference, or \c NULL on memory error.
2699 @bt_pre_not_null{trace_class}
2701 extern bt_field_class
*bt_field_class_string_create(
2702 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
2707 @name Array field class
2713 Borrows the element field class from the \bt_array_fc
2716 See the \ref api-tir-fc-array-prop-elem-fc "element field class"
2719 @param[in] field_class
2720 Array field class from which to borrow the element field class.
2723 Element field class of \bt_p{field_class}.
2725 @bt_pre_not_null{field_class}
2726 @bt_pre_is_array_fc{field_class}
2728 @sa bt_field_class_array_borrow_element_field_class_const() —
2729 \c const version of this function.
2731 extern bt_field_class
*bt_field_class_array_borrow_element_field_class(
2732 bt_field_class
*field_class
) __BT_NOEXCEPT
;
2736 Borrows the element field class from the \bt_array_fc
2737 \bt_p{field_class} (\c const version).
2739 See bt_field_class_array_borrow_element_field_class().
2741 extern const bt_field_class
*
2742 bt_field_class_array_borrow_element_field_class_const(
2743 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
2748 @name Static array field class
2754 Creates a \bt_sarray_fc having the element field class
2755 \bt_p{element_field_class} and the length \bt_p{length} from the
2756 trace class \bt_p{trace_class}.
2758 On success, the returned static array field class has the following
2766 <td>\ref api-tir-fc-array-prop-elem-fc "Element field class"
2767 <td>\bt_p{element_field_class}
2769 <td>\ref api-tir-fc-sarray-prop-len "Length"
2772 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2773 <td>Empty \bt_map_val
2776 @param[in] trace_class
2777 Trace class from which to create a static array field class.
2778 @param[in] element_field_class
2779 Class of the element fields of the instances of the static array
2780 field class to create.
2782 Length of the instances of the static array field class to create.
2785 New static array field class reference, or \c NULL on memory error.
2787 @bt_pre_not_null{trace_class}
2788 @bt_pre_not_null{element_field_class}
2789 bt_pre_fc_not_in_tc{element_field_class}
2791 @bt_post_success_frozen{element_field_class}
2793 extern bt_field_class
*bt_field_class_array_static_create(
2794 bt_trace_class
*trace_class
,
2795 bt_field_class
*element_field_class
, uint64_t length
)
2800 Returns the length of the \bt_sarray_fc \bt_p{field_class}.
2802 See the \ref api-tir-fc-sarray-prop-len "length" property.
2804 @param[in] field_class
2805 Static array field class of which to get the length.
2808 Length of \bt_p{field_class}.
2810 @bt_pre_not_null{field_class}
2811 @bt_pre_is_sarray_fc{field_class}
2813 extern uint64_t bt_field_class_array_static_get_length(
2814 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
2819 @name Dynamic array field class
2825 Creates a \bt_darray_fc having the element field class
2826 \bt_p{element_field_class} from the trace class \bt_p{trace_class}.
2828 If \bt_p{length_field_class} is not \c NULL, then the created dynamic
2829 array field class has a linked length field class.
2831 \ref api-tir-fc-link "Field classes with links to other field classes"
2834 On success, the returned dynamic array field class has the following
2842 <td>\ref api-tir-fc-array-prop-elem-fc "Element field class"
2843 <td>\bt_p{element_field_class}
2845 <td>\ref api-tir-fc-darray-prop-len-fp "Length field path"
2847 \em None (if \bt_p{length_field_class} is not \c NULL, this
2848 property becomes available when the returned field class becomes
2849 part of an \bt_ev_cls or of a \bt_stream_cls)
2851 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2852 <td>Empty \bt_map_val
2855 @param[in] trace_class
2856 Trace class from which to create a dynamic array field class.
2857 @param[in] element_field_class
2858 Class of the element fields of the instances of the dynamic array
2859 field class to create.
2860 @param[in] length_field_class
2862 Linked length field class of the dynamic array field class to
2869 New dynamic array field class reference, or \c NULL on memory error.
2871 @bt_pre_not_null{trace_class}
2872 @bt_pre_not_null{element_field_class}
2873 @bt_pre_fc_not_in_tc{element_field_class}
2875 <strong>If \bt_p{length_field_class} is not \c NULL</strong>,
2876 \bt_p{length_field_class} is an \bt_uint_fc.
2878 @bt_post_success_frozen{element_field_class}
2879 @bt_post_success_frozen{length_field_class}
2881 extern bt_field_class
*bt_field_class_array_dynamic_create(
2882 bt_trace_class
*trace_class
,
2883 bt_field_class
*element_field_class
,
2884 bt_field_class
*length_field_class
) __BT_NOEXCEPT
;
2889 @name Dynamic array field class with length field
2895 Borrows the length field path from the \bt_darray_fc (with a length
2896 field) \bt_p{field_class}.
2898 See the \ref api-tir-fc-darray-prop-len-fp "length field path" property.
2900 This property is only available when a \bt_struct_fc containing
2901 (recursively) \bt_p{field_class} is passed to one of:
2903 - bt_stream_class_set_packet_context_field_class()
2904 - bt_stream_class_set_event_common_context_field_class()
2905 - bt_event_class_set_specific_context_field_class()
2906 - bt_event_class_set_payload_field_class()
2908 In the meantime, this function returns \c NULL.
2910 @param[in] field_class
2911 Dynamic array field class from which to borrow the length
2915 Length field path of \bt_p{field_class}.
2917 @bt_pre_not_null{field_class}
2918 @bt_pre_is_darray_wl_fc{field_class}
2920 extern const bt_field_path
*
2921 bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const(
2922 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
2927 @name Structure field class
2933 Creates a \bt_struct_fc from the trace class \bt_p{trace_class}.
2935 On success, the returned structure field class has the following
2943 <td>\ref api-tir-fc-struct-prop-members "Members"
2946 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2947 <td>Empty \bt_map_val
2950 @param[in] trace_class
2951 Trace class from which to create a structure field class.
2954 New structure field class reference, or \c NULL on memory error.
2956 @bt_pre_not_null{trace_class}
2958 extern bt_field_class
*bt_field_class_structure_create(
2959 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
2963 Status codes for bt_field_class_structure_append_member().
2965 typedef enum bt_field_class_structure_append_member_status
{
2970 BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2976 BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2977 } bt_field_class_structure_append_member_status
;
2981 Appends a member to the \bt_struct_fc \bt_p{field_class} having the
2982 name \bt_p{name} and the field class \bt_p{member_field_class}.
2984 See the \ref api-tir-fc-struct-prop-members "members" property.
2986 @param[in] field_class
2987 Structure field class to which to append a member having
2988 the name \bt_p{name} and the field class \bt_p{member_field_class}.
2990 Name of the member to append to \bt_p{field_class} (copied).
2991 @param[in] member_field_class
2992 Field class of the member to append to \bt_p{field_class}.
2994 @retval #BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_OK
2996 @retval #BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_MEMORY_ERROR
2999 @bt_pre_not_null{field_class}
3000 @bt_pre_hot{field_class}
3001 @bt_pre_is_struct_fc{field_class}
3003 \bt_p{field_class} has no member with the name \bt_p{name}.
3004 @bt_pre_not_null{name}
3005 @bt_pre_not_null{member_field_class}
3006 @bt_pre_fc_not_in_tc{member_field_class}
3008 @bt_post_success_frozen{member_field_class}
3010 extern bt_field_class_structure_append_member_status
3011 bt_field_class_structure_append_member(
3012 bt_field_class
*field_class
,
3013 const char *name
, bt_field_class
*member_field_class
)
3018 Returns the number of members contained in the \bt_struct_fc
3021 See the \ref api-tir-fc-struct-prop-members "members" property.
3023 @param[in] field_class
3024 Structure field class of which to get the number of contained
3028 Number of contained members in \bt_p{field_class}.
3030 @bt_pre_not_null{field_class}
3031 @bt_pre_is_struct_fc{field_class}
3033 extern uint64_t bt_field_class_structure_get_member_count(
3034 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
3038 Borrows the member at index \bt_p{index} from the
3039 \bt_struct_fc \bt_p{field_class}.
3041 See the \ref api-tir-fc-struct-prop-members "members" property.
3043 @param[in] field_class
3044 Structure field class from which to borrow the member at
3047 Index of the member to borrow from \bt_p{field_class}.
3051 \em Borrowed reference of the member of
3052 \bt_p{field_class} at index \bt_p{index}.
3054 The returned pointer remains valid as long as \bt_p{field_class}
3058 @bt_pre_not_null{field_class}
3059 @bt_pre_is_struct_fc{field_class}
3061 \bt_p{index} is less than the number of members in
3062 \bt_p{field_class} (as returned by
3063 bt_field_class_structure_get_member_count()).
3065 @sa bt_field_class_structure_get_member_count() —
3066 Returns the number of members contained in a structure field class.
3067 @sa bt_field_class_structure_borrow_member_by_index_const() —
3068 \c const version of this function.
3070 extern bt_field_class_structure_member
*
3071 bt_field_class_structure_borrow_member_by_index(
3072 bt_field_class
*field_class
, uint64_t index
) __BT_NOEXCEPT
;
3076 Borrows the member at index \bt_p{index} from the
3077 \bt_struct_fc \bt_p{field_class} (\c const version).
3079 See bt_field_class_structure_borrow_member_by_index().
3081 extern const bt_field_class_structure_member
*
3082 bt_field_class_structure_borrow_member_by_index_const(
3083 const bt_field_class
*field_class
, uint64_t index
)
3088 Borrows the member having the name \bt_p{name} from the
3089 \bt_struct_fc \bt_p{field_class}.
3091 See the \ref api-tir-fc-struct-prop-members "members" property.
3093 If there's no member having the name \bt_p{name} in
3094 \bt_p{field_class}, this function returns \c NULL.
3096 @param[in] field_class
3097 Structure field class from which to borrow the member having the
3100 Name of the member to borrow from \bt_p{field_class}.
3104 \em Borrowed reference of the member of
3105 \bt_p{field_class} having the name \bt_p{name}, or \c NULL
3108 The returned pointer remains valid as long as \bt_p{field_class}
3112 @bt_pre_not_null{field_class}
3113 @bt_pre_is_struct_fc{field_class}
3114 @bt_pre_not_null{name}
3116 @sa bt_field_class_structure_borrow_member_by_name_const() —
3117 \c const version of this function.
3119 extern bt_field_class_structure_member
*
3120 bt_field_class_structure_borrow_member_by_name(
3121 bt_field_class
*field_class
, const char *name
) __BT_NOEXCEPT
;
3125 Borrows the member having the name \bt_p{name} from the
3126 \bt_struct_fc \bt_p{field_class} (\c const version).
3128 See bt_field_class_structure_borrow_member_by_name().
3130 extern const bt_field_class_structure_member
*
3131 bt_field_class_structure_borrow_member_by_name_const(
3132 const bt_field_class
*field_class
, const char *name
)
3138 @name Structure field class member
3143 @typedef struct bt_field_class_structure_member bt_field_class_structure_member;
3146 Structure field class member.
3151 Returns the name of the \bt_struct_fc member \bt_p{member}.
3153 See the \ref api-tir-fc-struct-prop-members "members" property.
3156 Structure field class member of which to get the name.
3160 Name of \bt_p{member}.
3162 The returned pointer remains valid as long as \bt_p{member} exists.
3165 @bt_pre_not_null{member}
3167 extern const char *bt_field_class_structure_member_get_name(
3168 const bt_field_class_structure_member
*member
) __BT_NOEXCEPT
;
3172 Borrows the field class from the \bt_struct_fc member
3175 See the \ref api-tir-fc-struct-prop-members "members" property.
3178 Structure field class member from which to borrow the field class.
3181 Field class of \bt_p{member}.
3183 @bt_pre_not_null{member}
3185 @sa bt_field_class_structure_member_borrow_field_class_const() —
3186 \c const version of this function.
3188 extern bt_field_class
*
3189 bt_field_class_structure_member_borrow_field_class(
3190 bt_field_class_structure_member
*member
) __BT_NOEXCEPT
;
3194 Borrows the field class from the \bt_struct_fc member
3195 \bt_p{member} (\c const version).
3197 See bt_field_class_structure_member_borrow_field_class().
3199 extern const bt_field_class
*
3200 bt_field_class_structure_member_borrow_field_class_const(
3201 const bt_field_class_structure_member
*member
) __BT_NOEXCEPT
;
3205 Sets the user attributes of the \bt_struct_fc member \bt_p{member}
3206 to \bt_p{user_attributes}.
3208 See the \ref api-tir-fc-struct-prop-members "members" property.
3211 When you append a member to a structure field class with
3212 bt_field_class_structure_append_member(), the member's
3213 initial user attributes is an empty \bt_map_val. Therefore you can
3215 bt_field_class_structure_member_borrow_user_attributes() and fill it
3216 directly instead of setting a new one with this function.
3219 Structure field class member of which to set the user attributes to
3220 \bt_p{user_attributes}.
3221 @param[in] user_attributes
3222 New user attributes of \bt_p{member}.
3224 @bt_pre_not_null{member}
3226 @bt_pre_not_null{user_attributes}
3227 @bt_pre_is_map_val{user_attributes}
3229 @sa bt_field_class_structure_member_borrow_user_attributes() —
3230 Borrows the user attributes of a structure field class member.
3232 extern void bt_field_class_structure_member_set_user_attributes(
3233 bt_field_class_structure_member
*member
,
3234 const bt_value
*user_attributes
) __BT_NOEXCEPT
;
3238 Borrows the user attributes of the \bt_struct_fc member
3241 See the \ref api-tir-fc-struct-prop-members "members" property.
3244 When you append a member to a structure field class with
3245 bt_field_class_structure_append_member(), the member's
3246 initial user attributes is an empty \bt_map_val.
3249 Structure field class member from which to borrow the user
3253 User attributes of \bt_p{member} (a \bt_map_val).
3255 @bt_pre_not_null{member}
3257 @sa bt_field_class_structure_member_set_user_attributes() —
3258 Sets the user attributes of a structure field class member.
3259 @sa bt_field_class_structure_member_borrow_user_attributes_const() —
3260 \c const version of this function.
3263 bt_field_class_structure_member_borrow_user_attributes(
3264 bt_field_class_structure_member
*member
) __BT_NOEXCEPT
;
3268 Borrows the user attributes of the \bt_struct_fc member
3269 \bt_p{member} (\c const version).
3271 See bt_field_class_structure_member_borrow_user_attributes().
3273 extern const bt_value
*
3274 bt_field_class_structure_member_borrow_user_attributes_const(
3275 const bt_field_class_structure_member
*member
) __BT_NOEXCEPT
;
3280 @name Option field class
3286 Borrows the optional field class from the \bt_opt_fc
3289 See the \ref api-tir-fc-opt-prop-fc "optional field class" property.
3291 @param[in] field_class
3292 Option field class from which to borrow the optional field class.
3295 Optional field class of \bt_p{field_class}.
3297 @bt_pre_not_null{field_class}
3298 @bt_pre_is_opt_fc{field_class}
3300 @sa bt_field_class_option_borrow_field_class_const() —
3301 \c const version of this function.
3303 extern bt_field_class
*bt_field_class_option_borrow_field_class(
3304 bt_field_class
*field_class
) __BT_NOEXCEPT
;
3308 Borrows the optional field class from the \bt_opt_fc
3309 \bt_p{field_class} (\c const version).
3311 See bt_field_class_option_borrow_field_class().
3313 extern const bt_field_class
*
3314 bt_field_class_option_borrow_field_class_const(
3315 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
3320 @name Option field class without a selector field
3326 Creates an \bt_opt_fc (without a selector field) having the optional
3327 field class \bt_p{optional_field_class} from the trace class
3330 On success, the returned option field class has the following property
3338 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
3339 <td>\bt_p{optional_field_class}
3341 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3342 <td>Empty \bt_map_val
3345 @param[in] trace_class
3346 Trace class from which to create an option field class.
3347 @param[in] optional_field_class
3348 Class of the optional fields of the instances of the option field
3352 New option field class reference, or \c NULL on memory error.
3354 @bt_pre_not_null{trace_class}
3355 @bt_pre_not_null{optional_field_class}
3356 @bt_pre_fc_not_in_tc{optional_field_class}
3358 @bt_post_success_frozen{optional_field_class}
3360 extern bt_field_class
*bt_field_class_option_without_selector_create(
3361 bt_trace_class
*trace_class
,
3362 bt_field_class
*optional_field_class
) __BT_NOEXCEPT
;
3367 @name Option field class with a selector field
3373 Borrows the selector field path from the \bt_opt_fc (with a selector
3374 field) \bt_p{field_class}.
3376 See the \ref api-tir-fc-opt-prop-sel-fp "selector field path" property.
3378 This property is only available when a \bt_struct_fc containing
3379 (recursively) \bt_p{field_class} is passed to one of:
3381 - bt_stream_class_set_packet_context_field_class()
3382 - bt_stream_class_set_event_common_context_field_class()
3383 - bt_event_class_set_specific_context_field_class()
3384 - bt_event_class_set_payload_field_class()
3386 In the meantime, this function returns \c NULL.
3388 @param[in] field_class
3389 Option field class from which to borrow the selector field path.
3392 Selector field path of \bt_p{field_class}.
3394 @bt_pre_not_null{field_class}
3395 @bt_pre_is_opt_ws_fc{field_class}
3397 extern const bt_field_path
*
3398 bt_field_class_option_with_selector_field_borrow_selector_field_path_const(
3399 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
3404 @name Option field class with a boolean selector field
3410 Creates an \bt_opt_fc (with a boolean selector field) having the
3411 optional field class \bt_p{optional_field_class} from the trace
3412 class \bt_p{trace_class}.
3414 On success, the returned option field class has the following property
3422 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
3423 <td>\bt_p{optional_field_class}
3425 <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
3427 \em None (this property becomes available when the returned field
3428 class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
3430 <td>\ref api-tir-fc-opt-prop-sel-rev "Selector is reversed?"
3433 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3434 <td>Empty \bt_map_val
3437 @param[in] trace_class
3438 Trace class from which to create an option field class.
3439 @param[in] optional_field_class
3440 Class of the optional fields of the instances of the option field
3442 @param[in] selector_field_class
3443 Linked selector field class of the option field class to create.
3446 New option field class reference, or \c NULL on memory error.
3448 @bt_pre_not_null{trace_class}
3449 @bt_pre_not_null{optional_field_class}
3450 @bt_pre_fc_not_in_tc{optional_field_class}
3451 @bt_pre_not_null{selector_field_class}
3453 \bt_p{selector_field_class} is a \bt_bool_fc.
3455 @bt_post_success_frozen{optional_field_class}
3456 @bt_post_success_frozen{selector_field_class}
3458 extern bt_field_class
*bt_field_class_option_with_selector_field_bool_create(
3459 bt_trace_class
*trace_class
,
3460 bt_field_class
*optional_field_class
,
3461 bt_field_class
*selector_field_class
) __BT_NOEXCEPT
;
3465 Sets whether or not the selector of the \bt_opt_fc (with a boolean
3466 selector field) \bt_p{field_class} is reversed.
3468 See the \ref api-tir-fc-opt-prop-sel-rev "selector is reversed?"
3471 @param[in] field_class
3472 Option field class of which to set whether or not its selector
3474 @param[in] selector_is_reversed
3475 #BT_TRUE to make \bt_p{field_class} have a reversed selector.
3477 @bt_pre_not_null{field_class}
3478 @bt_pre_hot{field_class}
3479 @bt_pre_is_opt_wbs_fc{field_class}
3481 @sa bt_field_class_option_with_selector_field_bool_selector_is_reversed() —
3482 Returns whether or not the selector of an option field class (with
3483 a boolean selector field) is reversed.
3486 bt_field_class_option_with_selector_field_bool_set_selector_is_reversed(
3487 bt_field_class
*field_class
, bt_bool selector_is_reversed
)
3492 Returns whether or not the selector of the
3493 \bt_opt_fc (with a boolean selector field) is reversed.
3495 See the \ref api-tir-fc-opt-prop-sel-rev "selector is reversed?"
3498 @param[in] field_class
3499 Option field class of which to get whether or not its selector is
3503 #BT_TRUE if the selector of \bt_p{field_class} is reversed.
3505 @bt_pre_not_null{field_class}
3506 @bt_pre_is_opt_wbs_fc{field_class}
3508 @sa bt_field_class_option_with_selector_field_bool_set_selector_is_reversed() —
3509 Sets whether or not the selector of an option field class (with
3510 a boolean selector field) is reversed.
3513 bt_field_class_option_with_selector_field_bool_selector_is_reversed(
3514 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
3519 @name Option field class with an unsigned integer selector field
3525 Creates an \bt_opt_fc (with an unsigned integer selector field)
3526 having the optional field class \bt_p{optional_field_class} from the
3527 trace class \bt_p{trace_class}.
3529 On success, the returned option field class has the following property
3537 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
3538 <td>\bt_p{optional_field_class}
3540 <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
3542 \em None (this property becomes available when the returned field
3543 class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
3545 <td>\ref api-tir-fc-opt-prop-uint-rs "Selector's unsigned integer ranges"
3548 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3549 <td>Empty \bt_map_val
3552 @param[in] trace_class
3553 Trace class from which to create an option field class.
3554 @param[in] optional_field_class
3555 Class of the optional fields of the instances of the option field
3557 @param[in] selector_field_class
3558 Linked selector field class of the option field class to create.
3560 Selector's unsigned integer ranges of the option field class to
3564 New option field class reference, or \c NULL on memory error.
3566 @bt_pre_not_null{trace_class}
3567 @bt_pre_not_null{optional_field_class}
3568 @bt_pre_fc_not_in_tc{optional_field_class}
3569 @bt_pre_not_null{selector_field_class}
3571 \bt_p{selector_field_class} is a \bt_uint_fc.
3572 @bt_pre_not_null{ranges}
3574 \bt_p{ranges} contains one or more \bt_p_uint_rg.
3576 @bt_post_success_frozen{optional_field_class}
3577 @bt_post_success_frozen{selector_field_class}
3578 @bt_post_success_frozen{ranges}
3580 extern bt_field_class
*
3581 bt_field_class_option_with_selector_field_integer_unsigned_create(
3582 bt_trace_class
*trace_class
,
3583 bt_field_class
*optional_field_class
,
3584 bt_field_class
*selector_field_class
,
3585 const bt_integer_range_set_unsigned
*ranges
)
3590 Borrows the \bt_p_uint_rg from the \bt_opt_fc (with an unsigned
3591 integer selector field) \bt_p{field_class}.
3594 \ref api-tir-fc-opt-prop-uint-rs "selector's unsigned integer ranges"
3597 @param[in] field_class
3598 Option field class from which to borrow the unsigned integer ranges.
3601 Unsigned integer ranges of \bt_p{field_class}.
3603 @bt_pre_not_null{field_class}
3604 @bt_pre_is_opt_wuis_fc{field_class}
3606 extern const bt_integer_range_set_unsigned
*
3607 bt_field_class_option_with_selector_field_integer_unsigned_borrow_selector_ranges_const(
3608 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
3613 @name Option field class with a signed integer selector field
3619 Creates an \bt_opt_fc (with a signed integer selector field)
3620 having the optional field class \bt_p{optional_field_class} from the
3621 trace class \bt_p{trace_class}.
3623 On success, the returned option field class has the following property
3631 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
3632 <td>\bt_p{optional_field_class}
3634 <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
3636 \em None (this property becomes available when the returned field
3637 class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
3639 <td>\ref api-tir-fc-opt-prop-sint-rs "Selector's signed integer ranges"
3642 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3643 <td>Empty \bt_map_val
3646 @param[in] trace_class
3647 Trace class from which to create an option field class.
3648 @param[in] optional_field_class
3649 Class of the optional fields of the instances of the option field
3651 @param[in] selector_field_class
3652 Linked selector field class of the option field class to create.
3654 Selector's signed integer ranges of the option field class to
3658 New option field class reference, or \c NULL on memory error.
3660 @bt_pre_not_null{trace_class}
3661 @bt_pre_not_null{optional_field_class}
3662 @bt_pre_fc_not_in_tc{optional_field_class}
3663 @bt_pre_not_null{selector_field_class}
3665 \bt_p{selector_field_class} is a \bt_uint_fc.
3666 @bt_pre_not_null{ranges}
3668 \bt_p{ranges} contains one or more \bt_p_uint_rg.
3670 @bt_post_success_frozen{optional_field_class}
3671 @bt_post_success_frozen{selector_field_class}
3672 @bt_post_success_frozen{ranges}
3674 extern bt_field_class
*
3675 bt_field_class_option_with_selector_field_integer_signed_create(
3676 bt_trace_class
*trace_class
,
3677 bt_field_class
*optional_field_class
,
3678 bt_field_class
*selector_field_class
,
3679 const bt_integer_range_set_signed
*ranges
) __BT_NOEXCEPT
;
3683 Borrows the \bt_p_sint_rg from the \bt_opt_fc (with a signed
3684 integer selector field) \bt_p{field_class}.
3687 \ref api-tir-fc-opt-prop-sint-rs "selector's signed integer ranges"
3690 @param[in] field_class
3691 Option field class from which to borrow the signed integer ranges.
3694 Signed integer ranges of \bt_p{field_class}.
3696 @bt_pre_not_null{field_class}
3697 @bt_pre_is_opt_wsis_fc{field_class}
3699 extern const bt_integer_range_set_signed
*
3700 bt_field_class_option_with_selector_field_integer_signed_borrow_selector_ranges_const(
3701 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
3706 @name Variant field class
3712 Creates a \bt_var_fc from the trace class \bt_p{trace_class}.
3714 If \bt_p{selector_field_class} is not \c NULL, then the created variant
3715 field class has a linked selector field class.
3717 \ref api-tir-fc-link "Field classes with links to other field classes"
3720 On success, the returned variant field class has the following
3728 <td>\ref api-tir-fc-var-prop-sel-fp "Selector field path"
3730 \em None (if \bt_p{selector_field_class} is not \c NULL, this
3731 property becomes available when the returned field class becomes
3732 part of an \bt_ev_cls or of a \bt_stream_cls)
3734 <td>\ref api-tir-fc-var-prop-opts "Options"
3737 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3738 <td>Empty \bt_map_val
3741 @param[in] trace_class
3742 Trace class from which to create a variant field class.
3743 @param[in] selector_field_class
3745 Linked selector field class of the variant field class to create.
3751 New variant field class reference, or \c NULL on memory error.
3753 @bt_pre_not_null{trace_class}
3755 <strong>If \bt_p{selector_field_class} is not \c NULL</strong>,
3756 \bt_p{selector_field_class} is an \bt_int_fc.
3758 @bt_post_success_frozen{element_field_class}
3759 @bt_post_success_frozen{selector_field_class}
3761 extern bt_field_class
*bt_field_class_variant_create(
3762 bt_trace_class
*trace_class
,
3763 bt_field_class
*selector_field_class
) __BT_NOEXCEPT
;
3767 Returns the number of options contained in the \bt_var_fc
3770 See the \ref api-tir-fc-var-prop-opts "options" property.
3772 @param[in] field_class
3773 Variant field class of which to get the number of contained
3777 Number of contained options in \bt_p{field_class}.
3779 @bt_pre_not_null{field_class}
3780 @bt_pre_is_var_fc{field_class}
3782 extern uint64_t bt_field_class_variant_get_option_count(
3783 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
3787 Borrows the option at index \bt_p{index} from the
3788 \bt_var_fc \bt_p{field_class}.
3790 See the \ref api-tir-fc-var-prop-opts "options" property.
3792 @param[in] field_class
3793 Variant field class from which to borrow the option at
3796 Index of the option to borrow from \bt_p{field_class}.
3800 \em Borrowed reference of the option of
3801 \bt_p{field_class} at index \bt_p{index}.
3803 The returned pointer remains valid as long as \bt_p{field_class}
3807 @bt_pre_not_null{field_class}
3808 @bt_pre_is_var_fc{field_class}
3810 \bt_p{index} is less than the number of options in
3811 \bt_p{field_class} (as returned by
3812 bt_field_class_variant_get_option_count()).
3814 @sa bt_field_class_variant_get_option_count() —
3815 Returns the number of options contained in a variant field class.
3816 @sa bt_field_class_variant_borrow_option_by_index_const() —
3817 \c const version of this function.
3819 extern bt_field_class_variant_option
*
3820 bt_field_class_variant_borrow_option_by_index(
3821 bt_field_class
*field_class
, uint64_t index
) __BT_NOEXCEPT
;
3825 Borrows the option at index \bt_p{index} from the
3826 \bt_var_fc \bt_p{field_class} (\c const version).
3828 See bt_field_class_variant_borrow_option_by_index().
3830 extern const bt_field_class_variant_option
*
3831 bt_field_class_variant_borrow_option_by_index_const(
3832 const bt_field_class
*field_class
, uint64_t index
)
3837 Borrows the option having the name \bt_p{name} from the
3838 \bt_var_fc \bt_p{field_class}.
3840 See the \ref api-tir-fc-var-prop-opts "options" property.
3842 If there's no option having the name \bt_p{name} in
3843 \bt_p{field_class}, this function returns \c NULL.
3845 @param[in] field_class
3846 Variant field class from which to borrow the option having the
3849 Name of the option to borrow from \bt_p{field_class}.
3853 \em Borrowed reference of the option of
3854 \bt_p{field_class} having the name \bt_p{name}, or \c NULL
3857 The returned pointer remains valid as long as \bt_p{field_class}
3861 @bt_pre_not_null{field_class}
3862 @bt_pre_is_var_fc{field_class}
3863 @bt_pre_not_null{name}
3865 @sa bt_field_class_variant_borrow_option_by_name_const() —
3866 \c const version of this function.
3868 extern bt_field_class_variant_option
*
3869 bt_field_class_variant_borrow_option_by_name(
3870 bt_field_class
*field_class
, const char *name
) __BT_NOEXCEPT
;
3874 Borrows the option having the name \bt_p{name} from the
3875 \bt_var_fc \bt_p{field_class} (\c const version).
3877 See bt_field_class_variant_borrow_option_by_name().
3879 extern const bt_field_class_variant_option
*
3880 bt_field_class_variant_borrow_option_by_name_const(
3881 const bt_field_class
*field_class
, const char *name
)
3887 @name Variant field class option
3892 @typedef struct bt_field_class_variant_option bt_field_class_variant_option;
3895 Variant field class option.
3900 Returns the name of the \bt_var_fc option \bt_p{option}.
3902 See the \ref api-tir-fc-var-prop-opts "options" property.
3905 Variant field class option of which to get the name.
3909 Name of \bt_p{option}.
3911 The returned pointer remains valid as long as \bt_p{option} exists.
3914 @bt_pre_not_null{option}
3916 extern const char *bt_field_class_variant_option_get_name(
3917 const bt_field_class_variant_option
*option
) __BT_NOEXCEPT
;
3921 Borrows the field class from the \bt_var_fc option
3924 See the \ref api-tir-fc-var-prop-opts "options" property.
3927 Variant field class option from which to borrow the field class.
3930 Field class of \bt_p{option}.
3932 @bt_pre_not_null{option}
3934 @sa bt_field_class_variant_option_borrow_field_class_const() —
3935 \c const version of this function.
3937 extern bt_field_class
*bt_field_class_variant_option_borrow_field_class(
3938 bt_field_class_variant_option
*option
) __BT_NOEXCEPT
;
3942 Borrows the field class from the \bt_var_fc option
3943 \bt_p{option} (\c const version).
3945 See bt_field_class_variant_option_borrow_field_class().
3947 extern const bt_field_class
*
3948 bt_field_class_variant_option_borrow_field_class_const(
3949 const bt_field_class_variant_option
*option
) __BT_NOEXCEPT
;
3953 Sets the user attributes of the \bt_var_fc option \bt_p{option}
3954 to \bt_p{user_attributes}.
3956 See the \ref api-tir-fc-var-prop-opts "options" property.
3959 When you append an option to a variant field class with
3960 bt_field_class_variant_without_selector_append_option(),
3961 bt_field_class_variant_with_selector_field_integer_unsigned_append_option(),
3963 bt_field_class_variant_with_selector_field_integer_signed_append_option(),
3964 the option's initial user attributes is an empty \bt_map_val.
3965 Therefore you can borrow it with
3966 bt_field_class_variant_option_borrow_user_attributes() and fill it
3967 directly instead of setting a new one with this function.
3970 Variant field class option of which to set the user attributes to
3971 \bt_p{user_attributes}.
3972 @param[in] user_attributes
3973 New user attributes of \bt_p{option}.
3975 @bt_pre_not_null{option}
3977 @bt_pre_not_null{user_attributes}
3978 @bt_pre_is_map_val{user_attributes}
3980 @sa bt_field_class_variant_option_borrow_user_attributes() —
3981 Borrows the user attributes of a variant field class option.
3983 extern void bt_field_class_variant_option_set_user_attributes(
3984 bt_field_class_variant_option
*option
,
3985 const bt_value
*user_attributes
) __BT_NOEXCEPT
;
3989 Borrows the user attributes of the \bt_var_fc option \bt_p{option}.
3991 See the \ref api-tir-fc-var-prop-opts "options" property.
3994 When you append an option to a variant field class with
3995 bt_field_class_variant_without_selector_append_option(),
3996 bt_field_class_variant_with_selector_field_integer_unsigned_append_option(),
3998 bt_field_class_variant_with_selector_field_integer_signed_append_option(),
3999 the option's initial user attributes is an empty \bt_map_val.
4002 Variant field class option from which to borrow the user
4006 User attributes of \bt_p{option} (a \bt_map_val).
4008 @bt_pre_not_null{option}
4010 @sa bt_field_class_variant_option_set_user_attributes() —
4011 Sets the user attributes of a variant field class option.
4012 @sa bt_field_class_variant_option_borrow_user_attributes_const() —
4013 \c const version of this function.
4015 extern bt_value
*bt_field_class_variant_option_borrow_user_attributes(
4016 bt_field_class_variant_option
*option
) __BT_NOEXCEPT
;
4020 Borrows the user attributes of the \bt_var_fc option \bt_p{option}
4023 See bt_field_class_variant_option_borrow_user_attributes().
4025 extern const bt_value
*bt_field_class_variant_option_borrow_user_attributes_const(
4026 const bt_field_class_variant_option
*option
) __BT_NOEXCEPT
;
4031 @name Variant field class without a selector field
4038 bt_field_class_variant_without_selector_append_option().
4040 typedef enum bt_field_class_variant_without_selector_append_option_status
{
4045 BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
4051 BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
4052 } bt_field_class_variant_without_selector_append_option_status
;
4056 Appends an option to the \bt_var_fc (without a selector field)
4057 \bt_p{field_class} having the name \bt_p{name} and the
4058 field class \bt_p{option_field_class}.
4060 See the \ref api-tir-fc-var-prop-opts "options" property.
4062 @param[in] field_class
4063 Variant field class to which to append an option having
4064 the name \bt_p{name} and the field class \bt_p{option_field_class}.
4066 Name of the option to append to \bt_p{field_class} (copied).
4067 @param[in] option_field_class
4068 Field class of the option to append to \bt_p{field_class}.
4070 @retval #BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
4072 @retval #BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
4075 @bt_pre_not_null{field_class}
4076 @bt_pre_hot{field_class}
4077 @bt_pre_is_var_wos_fc{field_class}
4079 \bt_p{field_class} has no option with the name \bt_p{name}.
4080 @bt_pre_not_null{name}
4081 @bt_pre_not_null{option_field_class}
4082 @bt_pre_fc_not_in_tc{option_field_class}
4084 @bt_post_success_frozen{option_field_class}
4086 extern bt_field_class_variant_without_selector_append_option_status
4087 bt_field_class_variant_without_selector_append_option(
4088 bt_field_class
*field_class
, const char *name
,
4089 bt_field_class
*option_field_class
) __BT_NOEXCEPT
;
4094 @name Variant field class with a selector field
4101 bt_field_class_variant_with_selector_field_integer_unsigned_append_option()
4103 bt_field_class_variant_with_selector_field_integer_signed_append_option().
4105 typedef enum bt_field_class_variant_with_selector_field_integer_append_option_status
{
4110 BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
4116 BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
4117 } bt_field_class_variant_with_selector_field_integer_append_option_status
;
4121 Borrows the selector field path from the \bt_var_fc (with a selector
4122 field) \bt_p{field_class}.
4124 See the \ref api-tir-fc-var-prop-sel-fp "selector field path" property.
4126 This property is only available when a \bt_struct_fc containing
4127 (recursively) \bt_p{field_class} is passed to one of:
4129 - bt_stream_class_set_packet_context_field_class()
4130 - bt_stream_class_set_event_common_context_field_class()
4131 - bt_event_class_set_specific_context_field_class()
4132 - bt_event_class_set_payload_field_class()
4134 In the meantime, this function returns \c NULL.
4136 @param[in] field_class
4137 Variant field class from which to borrow the selector field path.
4140 Selector field path of \bt_p{field_class}.
4142 @bt_pre_not_null{field_class}
4143 @bt_pre_is_var_ws_fc{field_class}
4145 extern const bt_field_path
*
4146 bt_field_class_variant_with_selector_field_borrow_selector_field_path_const(
4147 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
4152 @name Variant field class with an unsigned integer selector field
4158 Appends an option to the \bt_var_fc (with an unsigned integer
4159 selector field) \bt_p{field_class} having the name \bt_p{name},
4160 the field class \bt_p{option_field_class}, and the
4161 \bt_p_uint_rg \bt_p{ranges}.
4163 See the \ref api-tir-fc-var-prop-opts "options" property.
4165 @param[in] field_class
4166 Variant field class to which to append an option having
4167 the name \bt_p{name}, the field class \bt_p{option_field_class},
4168 and the unsigned integer ranges \bt_p{ranges}.
4170 Name of the option to append to \bt_p{field_class} (copied).
4171 @param[in] option_field_class
4172 Field class of the option to append to \bt_p{field_class}.
4174 Unsigned integer ranges of the option to append to
4177 @retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
4179 @retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
4182 @bt_pre_not_null{field_class}
4183 @bt_pre_hot{field_class}
4184 @bt_pre_is_var_wuis_fc{field_class}
4186 \bt_p{field_class} has no option with the name \bt_p{name}.
4187 @bt_pre_not_null{name}
4188 @bt_pre_not_null{option_field_class}
4189 @bt_pre_fc_not_in_tc{option_field_class}
4190 @bt_pre_not_null{Å—anges}
4192 \bt_p{ranges} contains one or more unsigned integer ranges.
4194 The unsigned integer ranges in \bt_p{ranges} do not overlap
4195 any unsigned integer range of any existing option in
4198 @bt_post_success_frozen{option_field_class}
4200 extern bt_field_class_variant_with_selector_field_integer_append_option_status
4201 bt_field_class_variant_with_selector_field_integer_unsigned_append_option(
4202 bt_field_class
*field_class
, const char *name
,
4203 bt_field_class
*option_field_class
,
4204 const bt_integer_range_set_unsigned
*ranges
) __BT_NOEXCEPT
;
4208 Borrows the option at index \bt_p{index} from the
4209 \bt_var_fc (with an unsigned integer selector field)
4212 See the \ref api-tir-fc-var-prop-opts "options" property.
4214 @param[in] field_class
4215 Variant field class from which to borrow the option at
4218 Index of the option to borrow from \bt_p{field_class}.
4222 \em Borrowed reference of the option of
4223 \bt_p{field_class} at index \bt_p{index}.
4225 The returned pointer remains valid as long as \bt_p{field_class}
4229 @bt_pre_not_null{field_class}
4230 @bt_pre_is_var_wuis_fc{field_class}
4232 \bt_p{index} is less than the number of options in
4233 \bt_p{field_class} (as returned by
4234 bt_field_class_variant_get_option_count()).
4236 @sa bt_field_class_variant_get_option_count() —
4237 Returns the number of options contained in a variant field class.
4239 extern const bt_field_class_variant_with_selector_field_integer_unsigned_option
*
4240 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(
4241 const bt_field_class
*field_class
, uint64_t index
)
4246 Borrows the option having the name \bt_p{name} from the
4247 \bt_var_fc (with an unsigned integer selector field)
4250 See the \ref api-tir-fc-var-prop-opts "options" property.
4252 If there's no option having the name \bt_p{name} in
4253 \bt_p{field_class}, this function returns \c NULL.
4255 @param[in] field_class
4256 Variant field class from which to borrow the option having the
4259 Name of the option to borrow from \bt_p{field_class}.
4263 \em Borrowed reference of the option of
4264 \bt_p{field_class} having the name \bt_p{name}, or \c NULL
4267 The returned pointer remains valid as long as \bt_p{field_class}
4271 @bt_pre_not_null{field_class}
4272 @bt_pre_is_var_wuis_fc{field_class}
4273 @bt_pre_not_null{name}
4275 @sa bt_field_class_variant_borrow_option_by_name_const() —
4276 Borrows an option by name from a variant field class.
4278 extern const bt_field_class_variant_with_selector_field_integer_unsigned_option
*
4279 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const(
4280 const bt_field_class
*field_class
, const char *name
)
4286 @name Variant field class (with an unsigned integer selector field) option
4291 @typedef struct bt_field_class_variant_with_selector_field_integer_unsigned_option bt_field_class_variant_with_selector_field_integer_unsigned_option;
4294 Variant field class (with an unsigned integer selector field) option.
4299 Borrows the \bt_p_uint_rg from the \bt_var_fc (with an unsigned
4300 integer selector field) option \bt_p{option}.
4302 See the \ref api-tir-fc-var-prop-opts "options" property.
4305 Variant field class option from which to borrow the
4306 unsigned integer ranges.
4309 Unsigned integer ranges of \bt_p{option}.
4311 @bt_pre_not_null{option}
4313 extern const bt_integer_range_set_unsigned
*
4314 bt_field_class_variant_with_selector_field_integer_unsigned_option_borrow_ranges_const(
4315 const bt_field_class_variant_with_selector_field_integer_unsigned_option
*option
)
4320 \ref api-fund-c-typing "Upcasts" the \bt_var_fc (with an
4321 unsigned integer selector field) option \bt_p{option} to the
4322 common #bt_field_class_variant_option type.
4324 See the \ref api-tir-fc-var-prop-opts "options" property.
4328 Variant field class option to upcast.
4334 \bt_p{option} as a common variant field class option.
4337 const bt_field_class_variant_option
*
4338 bt_field_class_variant_with_selector_field_integer_unsigned_option_as_option_const(
4339 const bt_field_class_variant_with_selector_field_integer_unsigned_option
*option
)
4342 return __BT_UPCAST_CONST(bt_field_class_variant_option
, option
);
4348 @name Variant field class with a signed integer selector field
4354 Appends an option to the \bt_var_fc (with a signed integer
4355 selector field) \bt_p{field_class} having the name \bt_p{name},
4356 the field class \bt_p{option_field_class}, and the
4357 \bt_p_sint_rg \bt_p{ranges}.
4359 See the \ref api-tir-fc-var-prop-opts "options" property.
4361 @param[in] field_class
4362 Variant field class to which to append an option having
4363 the name \bt_p{name} and the field class \bt_p{option_field_class},
4364 and the signed integer ranges \bt_p{ranges}.
4366 Name of the option to append to \bt_p{field_class} (copied).
4367 @param[in] option_field_class
4368 Field class of the option to append to \bt_p{field_class}.
4370 Signed integer ranges of the option to append to
4373 @retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
4375 @retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
4378 @bt_pre_not_null{field_class}
4379 @bt_pre_hot{field_class}
4380 @bt_pre_is_var_wsis_fc{field_class}
4382 \bt_p{field_class} has no option with the name \bt_p{name}.
4383 @bt_pre_not_null{name}
4384 @bt_pre_not_null{option_field_class}
4385 @bt_pre_fc_not_in_tc{option_field_class}
4386 @bt_pre_not_null{Å—anges}
4388 \bt_p{ranges} contains one or more signed integer ranges.
4390 The signed integer ranges in \bt_p{ranges} do not overlap with
4391 any signed integer range of any existing option in
4394 @bt_post_success_frozen{option_field_class}
4396 extern bt_field_class_variant_with_selector_field_integer_append_option_status
4397 bt_field_class_variant_with_selector_field_integer_signed_append_option(
4398 bt_field_class
*field_class
, const char *name
,
4399 bt_field_class
*option_field_class
,
4400 const bt_integer_range_set_signed
*ranges
)
4405 Borrows the option at index \bt_p{index} from the
4406 \bt_var_fc (with a signed integer selector field)
4409 See the \ref api-tir-fc-var-prop-opts "options" property.
4411 @param[in] field_class
4412 Variant field class from which to borrow the option at
4415 Index of the option to borrow from \bt_p{field_class}.
4419 \em Borrowed reference of the option of
4420 \bt_p{field_class} at index \bt_p{index}.
4422 The returned pointer remains valid as long as \bt_p{field_class}
4426 @bt_pre_not_null{field_class}
4427 @bt_pre_is_var_wsis_fc{field_class}
4429 \bt_p{index} is less than the number of options in
4430 \bt_p{field_class} (as returned by
4431 bt_field_class_variant_get_option_count()).
4433 @sa bt_field_class_variant_get_option_count() —
4434 Returns the number of options contained in a variant field class.
4436 extern const bt_field_class_variant_with_selector_field_integer_signed_option
*
4437 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(
4438 const bt_field_class
*field_class
, uint64_t index
)
4443 Borrows the option having the name \bt_p{name} from the
4444 \bt_var_fc (with a signed integer selector field)
4447 See the \ref api-tir-fc-var-prop-opts "options" property.
4449 If there's no option having the name \bt_p{name} in
4450 \bt_p{field_class}, this function returns \c NULL.
4452 @param[in] field_class
4453 Variant field class from which to borrow the option having the
4456 Name of the option to borrow from \bt_p{field_class}.
4460 \em Borrowed reference of the option of
4461 \bt_p{field_class} having the name \bt_p{name}, or \c NULL
4464 The returned pointer remains valid as long as \bt_p{field_class}
4468 @bt_pre_not_null{field_class}
4469 @bt_pre_is_var_wsis_fc{field_class}
4470 @bt_pre_not_null{name}
4472 @sa bt_field_class_variant_borrow_option_by_name_const() —
4473 Borrows an option by name from a variant field class.
4475 extern const bt_field_class_variant_with_selector_field_integer_signed_option
*
4476 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const(
4477 const bt_field_class
*field_class
, const char *name
)
4483 @name Variant field class (with a signed integer selector field) option
4488 @typedef struct bt_field_class_variant_with_selector_field_integer_signed_option bt_field_class_variant_with_selector_field_integer_signed_option;
4491 Variant field class (with a signed integer selector field) option.
4496 Borrows the \bt_p_sint_rg from the \bt_var_fc (with a signed
4497 integer selector field) option \bt_p{option}.
4499 See the \ref api-tir-fc-var-prop-opts "options" property.
4502 Variant field class option from which to borrow the
4503 signed integer ranges.
4506 Signed integer ranges of \bt_p{option}.
4508 @bt_pre_not_null{option}
4510 extern const bt_integer_range_set_signed
*
4511 bt_field_class_variant_with_selector_field_integer_signed_option_borrow_ranges_const(
4512 const bt_field_class_variant_with_selector_field_integer_signed_option
*option
)
4517 \ref api-fund-c-typing "Upcasts" the \bt_var_fc (with a signed
4518 integer selector field) option \bt_p{option} to the
4519 common #bt_field_class_variant_option type.
4521 See the \ref api-tir-fc-var-prop-opts "options" property.
4525 Variant field class option to upcast.
4531 \bt_p{option} as a common variant field class option.
4534 const bt_field_class_variant_option
*
4535 bt_field_class_variant_with_selector_field_integer_signed_option_as_option_const(
4536 const bt_field_class_variant_with_selector_field_integer_signed_option
*option
)
4539 return __BT_UPCAST_CONST(bt_field_class_variant_option
, option
);
4545 @name Reference count
4551 Increments the \ref api-fund-shared-object "reference count" of
4552 the field class \bt_p{field_class}.
4554 @param[in] field_class
4556 Field class of which to increment the reference count.
4561 @sa bt_field_class_put_ref() —
4562 Decrements the reference count of a field class.
4564 extern void bt_field_class_get_ref(
4565 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
4569 Decrements the \ref api-fund-shared-object "reference count" of
4570 the field class \bt_p{field_class}.
4572 @param[in] field_class
4574 Field class of which to decrement the reference count.
4579 @sa bt_field_class_get_ref() —
4580 Increments the reference count of a field class.
4582 extern void bt_field_class_put_ref(
4583 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
4587 Decrements the reference count of the field class
4588 \bt_p{_field_class}, and then sets \bt_p{_field_class} to \c NULL.
4592 Field class of which to decrement the reference count.
4594 Can contain \c NULL.
4597 @bt_pre_assign_expr{_field_class}
4599 #define BT_FIELD_CLASS_PUT_REF_AND_RESET(_field_class) \
4601 bt_field_class_put_ref(_field_class); \
4602 (_field_class) = NULL; \
4607 Decrements the reference count of the field class \bt_p{_dst}, sets
4608 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
4610 This macro effectively moves a field class reference from the expression
4611 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
4612 \bt_p{_dst} reference.
4616 Destination expression.
4618 Can contain \c NULL.
4624 Can contain \c NULL.
4627 @bt_pre_assign_expr{_dst}
4628 @bt_pre_assign_expr{_src}
4630 #define BT_FIELD_CLASS_MOVE_REF(_dst, _src) \
4632 bt_field_class_put_ref(_dst); \
4645 #endif /* BABELTRACE2_TRACE_IR_FIELD_CLASS_H */