1 #ifndef BABELTRACE2_TRACE_IR_FIELD_CLASS_H
2 #define BABELTRACE2_TRACE_IR_FIELD_CLASS_H
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
33 #include <babeltrace2/types.h>
40 @defgroup api-tir-fc Field classes
44 Classes of \bt_p_field.
46 <strong><em>Field classes</em></strong> are the classes of \bt_p_field:
48 @image html field-class-zoom.png
50 Field classes are \ref api-tir "trace IR" metadata objects.
52 There are many types of field classes. They can be divided into two main
58 Classes of fields which contain a simple value.
60 The scalar field classes are:
62 - \ref api-tir-fc-bool "Boolean"
63 - \ref api-tir-fc-ba "Bit array"
64 - \ref api-tir-fc-int "Integer" (unsigned and signed)
65 - \ref api-tir-fc-enum "Enumeration" (unsigned and signed)
66 - \ref api-tir-fc-real "Real" (single-precision and double-precision)
67 - \ref api-tir-fc-string "String"
72 Classes of fields which contain other fields.
74 The container field classes are:
76 - \ref api-tir-fc-array "Array" (static and dynamic)
77 - \ref api-tir-fc-struct "Structure"
78 - \ref api-tir-fc-opt "Option"
79 - \ref api-tir-fc-var "Variant"
83 @image html fc-to-field.png "Fields (green) are instances of field classes (orange)."
85 Some field classes conceptually inherit other field classes, eventually
86 making an inheritance hierarchy. For example, a \bt_sarray_fc
87 \em is an array field class. Therefore, a static array field class has
88 any property that an array field class has.
90 The complete field class inheritance hierarchy is:
92 @image html all-field-classes.png
94 In the illustration above:
96 - You can create any field class with a dark background with
97 a dedicated <code>bt_field_class_*_create()</code> function.
99 - A field class with a pale background is an \em abstract field class:
100 you cannot create it, but it has properties, therefore there are
101 functions which apply to it.
103 For example, bt_field_class_integer_set_preferred_display_base()
104 applies to any \bt_int_fc.
106 Field classes are \ref api-fund-shared-object "shared objects": get a
107 new reference with bt_field_class_get_ref() and put an existing
108 reference with bt_field_class_put_ref().
110 Some library functions \ref api-fund-freezing "freeze" field classes on
111 success. The documentation of those functions indicate this
114 All the field class types share the same C type, #bt_field_class.
116 Get the type enumerator of a field class with bt_field_class_get_type().
117 Get whether or not a field class type conceptually \em is a given type
118 with the inline bt_field_class_type_is() function.
120 The following table shows the available type enumerators and creation
121 functions for each type of \em concrete (non-abstract) field class:
127 <th>Creation function
129 <td><em>\ref api-tir-fc-bool "Boolean"</em>
130 <td>#BT_FIELD_CLASS_TYPE_BOOL
131 <td>bt_field_class_bool_create()
133 <td><em>\ref api-tir-fc-ba "Bit array"</em>
134 <td>#BT_FIELD_CLASS_TYPE_BIT_ARRAY
135 <td>bt_field_class_bit_array_create()
137 <td><em>Unsigned \ref api-tir-fc-int "integer"</em>
138 <td>#BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER
139 <td>bt_field_class_integer_unsigned_create()
141 <td><em>Signed \ref api-tir-fc-int "integer"</em>
142 <td>#BT_FIELD_CLASS_TYPE_SIGNED_INTEGER
143 <td>bt_field_class_integer_signed_create()
145 <td><em>Unsigned \ref api-tir-fc-enum "enumeration"</em>
146 <td>#BT_FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION
147 <td>bt_field_class_enumeration_unsigned_create()
149 <td><em>Signed \ref api-tir-fc-enum "enumeration"</em>
150 <td>#BT_FIELD_CLASS_TYPE_SIGNED_ENUMERATION
151 <td>bt_field_class_enumeration_signed_create()
153 <td><em>Single-precision \ref api-tir-fc-real "real"</em>
154 <td>#BT_FIELD_CLASS_TYPE_SINGLE_PRECISION_REAL
155 <td>bt_field_class_real_single_precision_create()
157 <td><em>Double-precision \ref api-tir-fc-real "real"</em>
158 <td>#BT_FIELD_CLASS_TYPE_DOUBLE_PRECISION_REAL
159 <td>bt_field_class_real_double_precision_create()
161 <td><em>\ref api-tir-fc-string "String"</em>
162 <td>#BT_FIELD_CLASS_TYPE_STRING
163 <td>bt_field_class_string_create()
165 <td><em>Static \ref api-tir-fc-array "array"</em>
166 <td>#BT_FIELD_CLASS_TYPE_STATIC_ARRAY
167 <td>bt_field_class_array_static_create()
169 <td><em>Dynamic \ref api-tir-fc-array "array" (no length field)</em>
170 <td>#BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD
171 <td>bt_field_class_array_dynamic_create()
173 <td><em>Dynamic \ref api-tir-fc-array "array" (with length field)</em>
174 <td>#BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD
175 <td>bt_field_class_array_dynamic_create()
177 <td><em>\ref api-tir-fc-struct "Structure"</em>
178 <td>#BT_FIELD_CLASS_TYPE_STRUCTURE
179 <td>bt_field_class_structure_create()
181 <td><em>\ref api-tir-fc-opt "Option" (no selector field)</em>
182 <td>#BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD
183 <td>bt_field_class_option_without_selector_create()
185 <td><em>\ref api-tir-fc-opt "Option" (boolean selector field)</em>
186 <td>#BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD
187 <td>bt_field_class_option_with_selector_field_bool_create()
189 <td><em>\ref api-tir-fc-opt "Option" (unsigned integer selector field)</em>
190 <td>#BT_FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
191 <td>bt_field_class_option_with_selector_field_integer_unsigned_create()
193 <td><em>\ref api-tir-fc-opt "Option" (signed integer selector field)</em>
194 <td>#BT_FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD
195 <td>bt_field_class_option_with_selector_field_integer_signed_create()
197 <td><em>\ref api-tir-fc-var "Variant" (no selector field)</em>
198 <td>#BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD
199 <td>bt_field_class_variant_create()
201 <td><em>\ref api-tir-fc-var "Variant" (unsigned integer selector field)</em>
202 <td>#BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
203 <td>bt_field_class_variant_create()
205 <td><em>\ref api-tir-fc-var "Variant" (signed integer selector field)</em>
206 <td>#BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD
207 <td>bt_field_class_variant_create()
210 You need a \bt_trace_cls to create a field class: create one from a
211 \bt_self_comp with bt_trace_class_create().
213 Outside the field class API, you can use field classes at four
214 locations, called <em>scopes</em>, within the trace IR API:
216 - To set the packet context field class of a \bt_stream_cls with
217 bt_stream_class_set_packet_context_field_class().
219 - To set the event common context field class of a stream class with
220 bt_stream_class_set_event_common_context_field_class().
222 - To set the specific context field class of an \bt_ev_cls with
223 bt_event_class_set_specific_context_field_class().
225 - To set the payload field class of an event class with
226 bt_event_class_set_payload_field_class().
228 When you call one of the four functions above:
230 - The passed field class must be a \bt_struct_fc.
232 - You must \em not have already called any of the four functions above
233 with the passed field class or with any of its contained field
236 - If any of the field classes recursively contained in the passed
237 field class has a \ref api-tir-fc-link "link to another field class",
238 it must honor the field class link rules.
240 Once you have called one of the four functions above, the passed field
241 class becomes \ref api-fund-freezing "frozen".
243 <h1>Common field class property</h1>
245 A field class has the following common property:
249 \anchor api-tir-fc-prop-user-attrs
250 \bt_dt_opt User attributes
253 User attributes of the field class.
255 User attributes are custom attributes attached to a field class.
257 Use bt_field_class_set_user_attributes(),
258 bt_field_class_borrow_user_attributes(), and
259 bt_field_class_borrow_user_attributes_const().
263 <h1>\anchor api-tir-fc-bool Boolean field class</h1>
265 @image html fc-bool.png
267 A <strong><em>boolean field class</em></strong> is the class
270 A boolean field contains a boolean value (#BT_TRUE or #BT_FALSE).
272 Create a boolean field class with bt_field_class_bool_create().
274 A boolean field class has no specific properties.
276 <h1>\anchor api-tir-fc-ba Bit array field class</h1>
278 @image html fc-ba.png
280 A <strong><em>bit array field class</em></strong> is the class
283 A bit array field contains a fixed-length array of bits.
285 Create a bit array field class with bt_field_class_bit_array_create().
287 A bit array field class has the following property:
291 \anchor api-tir-fc-ba-prop-len
295 Number of bits contained in the instances (bit array fields) of
296 the bit array field class.
298 As of \bt_name_version_min_maj, the maximum length of a bit array
301 You cannot change the length once the bit array field class is
304 Get a bit array field class's length with
305 bt_field_class_bit_array_get_length().
309 <h1>\anchor api-tir-fc-int Integer field classes</h1>
311 @image html fc-int.png
313 <strong><em>Integer field classes</em></strong> are classes
316 Integer fields contain integral values.
318 An integer field class is an \em abstract field class: you cannot create
319 one. The concrete integer field classes are:
322 <dt>Unsigned integer field class</dt>
324 Its instances (unsigned integer fields) contain an unsigned integral
327 Create with bt_field_class_integer_unsigned_create().
330 <dt>Signed integer field class</dt>
332 Its instances (signed integer fields) contain a signed integral
335 Create with bt_field_class_integer_signed_create().
339 Integer field classes have the following common properties:
343 \anchor api-tir-fc-int-prop-size
347 Expected range of values that the instances (integer fields)
348 of the integer field class can contain.
350 For example, if the field value range of an unsigned integer
351 field class is [0, 16383], then its unsigned integer fields
352 can only contain the values from 0 to 16383.
354 \bt_cp_sink_comp can benefit from this property to make some space
355 optimizations when writing trace data.
357 Use bt_field_class_integer_set_field_value_range() and
358 bt_field_class_integer_get_field_value_range().
362 \anchor api-tir-fc-int-prop-base
363 Preferred display base
366 Preferred base (2, 8, 10, or 16) to use when displaying the
367 instances (integer fields) of the integer field class.
369 Use bt_field_class_integer_set_preferred_display_base() and
370 bt_field_class_integer_get_preferred_display_base().
374 <h2>\anchor api-tir-fc-enum Enumeration field classes</h2>
376 @image html fc-enum.png
378 <strong><em>Enumeration field classes</em></strong> are classes
381 Enumeration field classes \em are \bt_p_int_fc: they have the integer
382 field classes properties.
384 Enumeration fields \em are integer fields: they contain integral values.
386 Enumeration field classes associate labels (strings) to specific
387 ranges of integral values. This association is called an enumeration
388 field class <em>mapping</em>.
390 For example, if an enumeration field class maps the label \c SUGAR to
391 the integer ranges [1, 19] and [25, 31], then an instance
392 (enumeration field) of this field class with the value 15 or 28 has the
393 label <code>SUGAR</code>.
395 An enumeration field class is an \em abstract field class: you cannot
396 create one. The concrete enumeration field classes are:
399 <dt>Unsigned enumeration field class</dt>
401 Its instances (unsigned enumeration fields) contain an unsigned
404 Create with bt_field_class_enumeration_unsigned_create().
407 <dt>Signed enumeration field class</dt>
409 Its instances (signed enumeration fields) contain a signed value
412 Create with bt_field_class_enumeration_signed_create().
416 Enumeration field classes have the following common property:
420 \anchor api-tir-fc-enum-prop-mappings
424 Set of mappings of the enumeration field class.
426 An enumeration field class mapping is a label (string) and an
429 The integer ranges of a given mapping or of multiple mappings of
430 the same enumeration field class can overlap. For example,
431 an enumeration field class can have those two mappings:
433 - <code>CALORIES</code>: [1, 11], [15, 37]
434 - <code>SODIUM</code>: [7, 13]
436 In that case, the values 2 and 30 correpond to the label
437 <code>CALORIES</code>, the value 12 to the label
438 <code>SODIUM</code>, and the value 10 to the labels
439 \c CALORIES \em and <code>SODIUM</code>.
441 Two mappings of the same enumeration field class cannot have the
444 Add a mapping to an enumeration field class with
445 bt_field_class_enumeration_unsigned_add_mapping() or
446 bt_field_class_enumeration_signed_add_mapping().
448 Get the number of mappings in an enumeration field class with
449 bt_field_class_enumeration_get_mapping_count().
451 Borrow a mapping from an enumeration field class with
452 bt_field_class_enumeration_unsigned_borrow_mapping_by_index_const(),
453 bt_field_class_enumeration_signed_borrow_mapping_by_index_const(),
454 bt_field_class_enumeration_unsigned_borrow_mapping_by_label_const(),
456 bt_field_class_enumeration_signed_borrow_mapping_by_label_const().
458 An enumeration field class mapping is a
459 \ref api-fund-unique-object "unique object": it
460 belongs to the enumeration field class which contains it.
462 There are two enumeration field class mapping types, depending on
463 the field class's type:
464 #bt_field_class_enumeration_unsigned_mapping and
465 #bt_field_class_enumeration_signed_mapping.
467 There is also the #bt_field_class_enumeration_mapping type for
468 common properties and operations (for example,
469 bt_field_class_enumeration_mapping_get_label()).
470 \ref api-fund-c-typing "Upcast" a specific enumeration field class
471 mapping to the #bt_field_class_enumeration_mapping type with
472 bt_field_class_enumeration_unsigned_mapping_as_mapping_const() or
473 bt_field_class_enumeration_signed_mapping_as_mapping_const().
475 Get all the enumeration field class labels mapped to a given integer
477 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value()
479 bt_field_class_enumeration_signed_get_mapping_labels_for_value().
483 <h1>\anchor api-tir-fc-real Real field classes</h1>
485 @image html fc-real.png
487 <strong><em>Real field classes</em></strong> are classes
491 <a href="https://en.wikipedia.org/wiki/Real_number">real</a>
492 values (\c float or \c double types).
494 A real field class is an \em abstract field class: you cannot create
495 one. The concrete real field classes are:
498 <dt>Single-precision real field class</dt>
500 Its instances (single-precision real fields) contain a \c float
503 Create with bt_field_class_real_single_precision_create().
506 <dt>Double-precision real field class</dt>
508 Its instances (double-precision real fields) contain a \c double
511 Create with bt_field_class_real_double_precision_create().
515 Real field classes have no specific properties.
517 <h1>\anchor api-tir-fc-string String field class</h1>
519 @image html fc-string.png
521 A <strong><em>string field class</em></strong> is the class
522 of \bt_p_string_field.
524 A string field contains an UTF-8 string value.
526 Create a string field class with bt_field_class_string_create().
528 A string field class has no specific properties.
530 <h1>\anchor api-tir-fc-array Array field classes</h1>
532 @image html fc-array.png
534 <strong><em>Array field classes</em></strong> are classes
535 of \bt_p_array_field.
537 Array fields contain zero or more fields which have the same class.
539 An array field class is an \em abstract field class: you cannot create
540 one. The concrete array field classes are:
543 <dt>Static array field class</dt>
545 Its instances (static array fields) contain a fixed number of
548 Create with bt_field_class_array_static_create().
550 A static array field class has the following specific property:
554 \anchor api-tir-fc-sarray-prop-len
558 Number of fields contained in the instances (static array
559 fields) of the static array field class.
561 You cannot change the length once the static array field class
564 Get a static array field class's length with
565 bt_field_class_array_static_get_length().
570 <dt>Dynamic array field class</dt>
572 Its instances (dynamic array fields) contain a variable number array
575 There are two types of dynamic array field classes: without or
576 with a length field. See
577 \ref api-tir-fc-link "Field classes with links to other field classes"
580 @image html darray-link.png "Dynamic array field class with a length field."
582 Create with bt_field_class_array_dynamic_create().
584 A dynamic array field class with a length field has the
589 \anchor api-tir-fc-darray-prop-len-fp
593 Field path of the linked length field class.
595 Get a dynamic array field class's length field path with
596 bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const().
602 Array field classes have the following common property:
606 \anchor api-tir-fc-array-prop-elem-fc
610 Class of the fields contained in the instances (array fields) of the
613 You cannot change the element field class once the array field class
616 Borrow an array field class's element field class with
617 Use bt_field_class_array_borrow_element_field_class() and
618 bt_field_class_array_borrow_element_field_class_const().
622 <h1>\anchor api-tir-fc-struct Structure field class</h1>
624 @image html fc-struct.png
626 A <strong><em>structure field class</em></strong> is the class
627 of a \bt_struct_field.
629 A structure field contains an ordered list of zero or more members. Each
630 structure field member is the instance of a structure field class
631 member. A structure field class member has a name, a field class,
634 Create a structure field class with bt_field_class_structure_create().
636 A structure field class has the following specific property:
640 \anchor api-tir-fc-struct-prop-members
644 Ordered list of members (zero or more) of the structure field class.
648 - A name, unique amongst all the member names of the same
649 structure field class.
653 The instances (structure fields) of a structure field class have
654 members which are instances of the corresponding structure field
657 Append a member to a structure field class with
658 bt_field_class_structure_append_member().
660 Borrow a member from a structure field class with
661 bt_field_class_structure_borrow_member_by_index(),
662 bt_field_class_structure_borrow_member_by_name(),
663 bt_field_class_structure_borrow_member_by_index_const(), and
664 bt_field_class_structure_borrow_member_by_name_const().
666 A structure field class member is a
667 \ref api-fund-unique-object "unique object": it
668 belongs to the structure field class which contains it.
670 The type of a structure field class member is
671 #bt_field_class_structure_member.
673 Get a structure field class member's name with
674 bt_field_class_structure_member_get_name().
676 Borrow a structure field class member's field class with
677 bt_field_class_structure_member_borrow_field_class() and
678 bt_field_class_structure_member_borrow_field_class_const().
680 Set a structure field class member's user attributes with
681 bt_field_class_structure_member_set_user_attributes().
683 Borrow a structure field class member's user attributes with
684 bt_field_class_structure_member_borrow_user_attributes() and
685 bt_field_class_structure_member_borrow_user_attributes_const().
689 <h1>\anchor api-tir-fc-opt Option field classes</h1>
691 @image html fc-opt.png
693 <strong><em>Option field classes</em></strong> are classes
696 An option field either does or doesn't contain a field, called its
699 An option field class is an \em abstract field class: you cannot create
700 one. An option field class either has a selector field (it's linked to a
701 selector field class; see
702 \ref api-tir-fc-link "Field classes with links to other field classes")
703 or none. Therefore, the concrete option field classes are:
706 <dt>Option field class without a selector field</dt>
708 Create with bt_field_class_option_without_selector_create().
710 An option field class without a selector field has no specific
714 <dt>Option field class with a boolean selector field</dt>
716 The linked selector field of an option field class's instance
717 (an option field) is a \bt_bool_field.
719 Consequently, the option field class's selector field class is
722 @image html opt-link.png "Option field class with a boolean selector field."
724 Create with bt_field_class_option_with_selector_field_bool_create().
726 An option field class with a boolean selector field has the
727 following specific property:
731 \anchor api-tir-fc-opt-prop-sel-rev
732 Selector is reversed?
735 Whether or not the linked boolean selector field makes the
736 option field class's instance (an option field) contain a field
737 when it's #BT_TRUE or when it's #BT_FALSE.
739 If this property is #BT_TRUE, then if the linked selector field
740 has the value #BT_FALSE, the option field contains a field.
743 bt_field_class_option_with_selector_field_bool_set_selector_is_reversed()
745 bt_field_class_option_with_selector_field_bool_selector_is_reversed().
750 <dt>Option field class with an unsigned selector field</dt>
752 The linked selector field of an option field class's instance
753 (an option field) is an \bt_uint_field.
755 Consequently, the option field class's selector field class is
759 bt_field_class_option_with_selector_field_integer_unsigned_create().
761 Pass an \bt_uint_rs on creation to set which values of the selector
762 field can make the option field contain a field.
764 An option field class with an unsigned integer selector field has
765 the following specific property:
769 \anchor api-tir-fc-opt-prop-uint-rs
770 Selector's unsigned integer ranges
773 If the linked unsigned integer selector field of an option
774 field class's instance (an option field) has a value which
775 intersects with the selector's unsigned integer ranges, then
776 the option field contains a field.
778 You cannot change the selector's unsigned integer ranges once
779 the option field class is created.
781 Borrow the selector's unsigned integer ranges from an
782 option field class with an unsigned integer selector field with
783 bt_field_class_option_with_selector_field_integer_unsigned_borrow_selector_ranges_const().
788 <dt>Option field class with a signed selector field</dt>
790 The linked selector field of an option field class's instance
791 (an option field) is a \bt_sint_field.
793 Consequently, the option field class's selector field class is
797 bt_field_class_option_with_selector_field_integer_signed_create().
799 Pass a \bt_sint_rs on creation to set which values of the selector
800 field can make the option field contain a field.
802 An option field class with a signed integer selector field has
803 the following specific property:
807 \anchor api-tir-fc-opt-prop-sint-rs
808 Selector's signed integer ranges
811 If the linked signed integer selector field of an option
812 field class's instance (an option field) has a value which
813 intersects with the selector's signed integer ranges, then
814 the option field contains a field.
816 You cannot change the selector's signed integer ranges once
817 the option field class is created.
819 Borrow the selector's signed integer ranges from an
820 option field class with a signed integer selector field with
821 bt_field_class_option_with_selector_field_integer_signed_borrow_selector_ranges_const().
827 Option field classes with a selector have the following common
832 \anchor api-tir-fc-opt-prop-sel-fp
836 Field path of the linked selector field class.
838 Borrow such an option field class's selector field path with
839 bt_field_class_option_with_selector_field_borrow_selector_field_path_const().
843 Option field classes have the following common property:
847 \anchor api-tir-fc-opt-prop-fc
851 Class of the optional field of an instance (option field) of the
854 You cannot change the optional field class once the option field
857 Borrow an option field class's optional field class with
858 Use bt_field_class_option_borrow_field_class() and
859 bt_field_class_option_borrow_field_class_const().
863 <h1>\anchor api-tir-fc-var Variant field classes</h1>
865 @image html fc-var.png
867 <strong><em>Variant field classes</em></strong> are classes
870 A variant field contains a field amongst one or more possible fields.
872 Variant field classes contain one or more options. Each variant field
873 class option has a name, a field class, user attributes, and integer
874 ranges, depending on the exact type.
876 A variant field class is an \em abstract field class: you cannot create
877 one. A variant field class either has a selector field (it's linked to a
878 selector field class; see
879 \ref api-tir-fc-link "Field classes with links to other field classes")
880 or none. Therefore, the concrete variant field classes are:
883 <dt>Variant field class without a selector field</dt>
885 Create with bt_field_class_variant_create(), passing \c NULL as
886 the selector field class.
888 Append an option to such a variant field class with
889 bt_field_class_variant_without_selector_append_option().
891 A variant field class without a selector field has no specific
895 <dt>Variant field class with an unsigned selector field</dt>
897 The linked selector field of a variant field class's instance
898 (a variant field) is an \bt_uint_field.
900 Consequently, the variant field class's selector field class is
903 @image html var-link.png "Variant field class with an unsigned integer selector field."
905 Create with bt_field_class_variant_create(), passing an
906 unsigned integer field class as the selector field class.
908 Append an option to such a variant field class with
909 bt_field_class_variant_with_selector_field_integer_unsigned_append_option().
911 Pass an \bt_uint_rs when you append an option to set which values of
912 the selector field can make the variant field have a given
915 Borrow such a variant field class's option with
916 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const()
918 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const().
921 <dt>Variant field class with a signed selector field</dt>
923 The linked selector field of a variant field class's instance
924 (a variant field) is a \bt_sint_field.
926 Consequently, the variant field class's selector field class is
929 Create with bt_field_class_variant_create(), passing a
930 signed integer field class as the selector field class.
932 Append an option to such a variant field class with
933 bt_field_class_variant_with_selector_field_integer_signed_append_option().
935 Pass a \bt_sint_rs when you append an option to set which values of
936 the selector field can make the variant field have a given
939 Borrow such a variant field class's option with
940 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const()
942 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const().
946 Variant field classes with a selector have the following common
951 \anchor api-tir-fc-var-prop-sel-fp
955 Field path of the linked selector field class.
957 Borrow such a variant field class's selector field path with
958 bt_field_class_variant_with_selector_field_borrow_selector_field_path_const().
962 Variant field classes have the following common property:
966 \anchor api-tir-fc-var-prop-opts
970 Options of the variant field class.
974 - A name, unique amongst all the option names of the same
979 If the variant field class is linked to a selector field class, then
980 each option also has an \bt_int_rs. In that case, the ranges of a
981 given option cannot overlap any range of any other option.
983 A variant field class must contain at least one option.
985 Depending on whether or not the variant field class has a selector
986 field class, append an option to a variant field class
987 with bt_field_class_variant_without_selector_append_option(),
988 bt_field_class_variant_with_selector_field_integer_unsigned_append_option(),
990 bt_field_class_variant_with_selector_field_integer_signed_append_option().
992 Get the number of options contained in a variant field class
993 with bt_field_class_variant_get_option_count().
995 A variant field class option is a
996 \ref api-fund-unique-object "unique object": it
997 belongs to the variant field class which contains it.
999 Borrow any variant field class's option with
1000 bt_field_class_variant_borrow_option_by_index(),
1001 bt_field_class_variant_borrow_option_by_name(),
1002 bt_field_class_variant_borrow_option_by_index_const(), and
1003 bt_field_class_variant_borrow_option_by_name_const().
1005 Those functions return the common #bt_field_class_variant_option
1006 type. Get the name of a variant field class option with
1007 bt_field_class_variant_option_get_name(). Borrow a variant field
1008 class option's field class with
1009 bt_field_class_variant_option_borrow_field_class() and
1010 bt_field_class_variant_option_borrow_field_class_const().
1012 Borrow the option of a variant field classes with a selector field
1014 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(),
1015 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const(),
1016 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(), or
1017 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const(),
1018 depending on the selector field class's type.
1020 Those functions return the
1021 #bt_field_class_variant_with_selector_field_integer_unsigned_option or
1022 #bt_field_class_variant_with_selector_field_integer_signed_option type.
1023 \ref api-fund-c-typing "Upcast" those types to the
1024 #bt_field_class_variant_option type with
1025 bt_field_class_variant_with_selector_field_integer_unsigned_option_as_option_const()
1027 bt_field_class_variant_with_selector_field_integer_signed_option_as_option_const().
1029 Borrow the option's ranges from a variant field class with a
1030 selector field class with
1031 bt_field_class_variant_with_selector_field_integer_unsigned_option_borrow_ranges_const()
1033 bt_field_class_variant_with_selector_field_integer_signed_option_borrow_ranges_const().
1035 Set a variant field class option's user attributes with
1036 bt_field_class_variant_option_set_user_attributes().
1038 Borrow a variant field class option's user attributes with
1039 bt_field_class_variant_option_borrow_user_attributes() and
1040 bt_field_class_variant_option_borrow_user_attributes_const().
1044 <h1>\anchor api-tir-fc-link Field classes with links to other field classes</h1>
1046 \bt_cp_darray_fc, \bt_p_opt_fc, and \bt_p_var_fc \em can have links to
1047 other, preceding field classes.
1049 When a field class A has a link to another field class B, then
1050 an instance (\bt_field) of A has a link to an instance of B.
1052 This feature exists so that the linked field can contain the value of a
1053 dynamic property of the field. Those properties are:
1056 <dt>\bt_c_darray_field</dt>
1058 The linked field, a \bt_uint_field, contains the \b length of the
1059 dynamic array field.
1062 <dt>\bt_c_opt_field</dt>
1064 The linked field, either a \bt_bool_field or an \bt_int_field,
1065 indicates whether or not the option field has a field.
1068 <dt>\bt_c_var_field</dt>
1070 The linked field, an \bt_int_field, indicates the variant field's
1071 current selected field.
1075 Having a linked field class is <em>optional</em>: you always set the
1076 field properties with a dedicated function anyway. For example, even if
1077 a dynamic array field is linked to a preceding length field, you must
1078 still set its length with bt_field_array_dynamic_set_length(). In that
1079 case, the value of the length field must match what you pass to
1080 bt_field_array_dynamic_set_length().
1082 The purpose of this feature is to eventually save space when a
1083 \bt_sink_comp writes trace files: if the trace format can convey that
1084 a preceding, existing field represents the length of a dynamic array
1085 field, then the sink component doesn't need to write the dynamic array
1086 field's length twice. This is the case of the
1087 <a href="https://diamon.org/ctf/">Common Trace Format</a>, for
1090 @image html darray-link.png "A dynamic array field class linked to an unsigned integer field class."
1092 To link a field class A to a preceding field class B, pass
1093 field class B when you create field class A. For example, pass
1094 the \bt_uint_fc to bt_field_class_array_dynamic_create() to create a
1095 \bt_darray_fc with a length field.
1097 When you call bt_stream_class_set_packet_context_field_class(),
1098 bt_stream_class_set_event_common_context_field_class(),
1099 bt_event_class_set_specific_context_field_class(), or
1100 bt_event_class_set_payload_field_class() with a field class containing
1101 a field class A with a linked field class B, the path to
1102 B becomes available in A. The functions to borrow this field path are:
1104 - bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const()
1105 - bt_field_class_option_with_selector_field_borrow_selector_field_path_const()
1106 - bt_field_class_variant_with_selector_field_borrow_selector_field_path_const()
1108 A field path indicates how to reach a linked field from a given
1109 root <em>scope</em>. The available scopes are:
1112 <dt>#BT_FIELD_PATH_SCOPE_PACKET_CONTEXT</dt>
1114 Packet context field.
1116 See bt_packet_borrow_context_field_const().
1119 <dt>#BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT</dt>
1121 Event common context field.
1123 See bt_event_borrow_common_context_field_const().
1126 <dt>#BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT</dt>
1128 Event specific context field.
1130 See bt_event_borrow_specific_context_field_const().
1133 <dt>#BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD</dt>
1135 Event payload field.
1137 See bt_event_borrow_payload_field_const().
1141 The rules regarding field class A vs. field class B (linked
1144 - If A is within a packet context field class, B must also be in the
1145 same packet context field class.
1147 See bt_stream_class_set_packet_context_field_class().
1149 - If A is within a event common context field class, B must be in one
1152 - The same event common context field class.
1153 - The packet context field class of the same \bt_stream_cls.
1155 See bt_stream_class_set_event_common_context_field_class().
1157 - If A is within an event specific context field class, B must be in
1160 - The same event specific context field class.
1161 - The event common context field class of the same stream class.
1162 - The packet context field class of the same stream class.
1164 See bt_event_class_set_specific_context_field_class().
1166 - If A is within an event payload field class, B must be in one of:
1168 - The same event payload field class.
1169 - The event specific context field class of the same \bt_ev_cls.
1170 - The event common context field class of the same stream class.
1171 - The packet context field class of the same stream class.
1173 See bt_event_class_set_payload_field_class().
1175 - If both A and B are in the same scope, then:
1177 - The lowest common ancestor field class of A and B must be a
1182 Considering that the members of a structure field class are ordered,
1183 then B must be part of a member that's before the member which
1184 contains A in their lowest common ancestor structure field class.
1186 - The path from the lowest common ancestor structure field class of A
1187 and B to A and to B must only contain structure field classes.
1189 - If A is in a different scope than B, the path from the root scope of B
1190 to B must only contain structure field classes.
1199 @typedef struct bt_field_class bt_field_class;
1214 Field class type enumerators.
1216 typedef enum bt_field_class_type
{
1221 BT_FIELD_CLASS_TYPE_BOOL
= 1ULL << 0,
1227 BT_FIELD_CLASS_TYPE_BIT_ARRAY
= 1ULL << 1,
1233 No field class has this type: use it with
1234 bt_field_class_type_is().
1236 BT_FIELD_CLASS_TYPE_INTEGER
= 1ULL << 2,
1242 This type conceptually inherits #BT_FIELD_CLASS_TYPE_INTEGER.
1244 BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER
= (1ULL << 3) | BT_FIELD_CLASS_TYPE_INTEGER
,
1250 This type conceptually inherits #BT_FIELD_CLASS_TYPE_INTEGER.
1252 BT_FIELD_CLASS_TYPE_SIGNED_INTEGER
= (1ULL << 4) | BT_FIELD_CLASS_TYPE_INTEGER
,
1258 This type conceptually inherits #BT_FIELD_CLASS_TYPE_INTEGER.
1260 No field class has this type: use it with
1261 bt_field_class_type_is().
1263 BT_FIELD_CLASS_TYPE_ENUMERATION
= 1ULL << 5,
1269 This type conceptually inherits #BT_FIELD_CLASS_TYPE_ENUMERATION
1270 and #BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER.
1272 BT_FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION
= BT_FIELD_CLASS_TYPE_ENUMERATION
| BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER
,
1278 This type conceptually inherits #BT_FIELD_CLASS_TYPE_ENUMERATION
1279 and #BT_FIELD_CLASS_TYPE_SIGNED_INTEGER.
1281 BT_FIELD_CLASS_TYPE_SIGNED_ENUMERATION
= BT_FIELD_CLASS_TYPE_ENUMERATION
| BT_FIELD_CLASS_TYPE_SIGNED_INTEGER
,
1287 No field class has this type: use it with
1288 bt_field_class_type_is().
1290 BT_FIELD_CLASS_TYPE_REAL
= 1ULL << 6,
1294 Single-precision \bt_real_fc.
1296 This type conceptually inherits #BT_FIELD_CLASS_TYPE_REAL.
1298 BT_FIELD_CLASS_TYPE_SINGLE_PRECISION_REAL
= (1ULL << 7) | BT_FIELD_CLASS_TYPE_REAL
,
1302 Double-precision \bt_real_fc.
1304 This type conceptually inherits #BT_FIELD_CLASS_TYPE_REAL.
1306 BT_FIELD_CLASS_TYPE_DOUBLE_PRECISION_REAL
= (1ULL << 8) | BT_FIELD_CLASS_TYPE_REAL
,
1312 BT_FIELD_CLASS_TYPE_STRING
= 1ULL << 9,
1318 BT_FIELD_CLASS_TYPE_STRUCTURE
= 1ULL << 10,
1324 No field class has this type: use it with
1325 bt_field_class_type_is().
1327 BT_FIELD_CLASS_TYPE_ARRAY
= 1ULL << 11,
1333 This type conceptually inherits #BT_FIELD_CLASS_TYPE_ARRAY.
1335 BT_FIELD_CLASS_TYPE_STATIC_ARRAY
= (1ULL << 12) | BT_FIELD_CLASS_TYPE_ARRAY
,
1341 This type conceptually inherits #BT_FIELD_CLASS_TYPE_ARRAY.
1343 No field class has this type: use it with
1344 bt_field_class_type_is().
1346 BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY
= (1ULL << 13) | BT_FIELD_CLASS_TYPE_ARRAY
,
1350 \bt_c_darray_fc (without a length field).
1352 This type conceptually inherits
1353 #BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY.
1355 BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD
= (1ULL << 14) | BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY
,
1359 \bt_c_darray_fc (with a length field).
1361 This type conceptually inherits
1362 #BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY.
1364 BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD
= (1ULL << 15) | BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY
,
1370 No field class has this type: use it with
1371 bt_field_class_type_is().
1373 BT_FIELD_CLASS_TYPE_OPTION
= 1ULL << 16,
1377 \bt_c_opt_fc (without a selector field).
1379 BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD
= (1ULL << 17) | BT_FIELD_CLASS_TYPE_OPTION
,
1383 \bt_c_opt_fc (with a selector field).
1385 This type conceptually inherits #BT_FIELD_CLASS_TYPE_OPTION.
1387 No field class has this type: use it with
1388 bt_field_class_type_is().
1390 BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD
= (1ULL << 18) | BT_FIELD_CLASS_TYPE_OPTION
,
1394 \bt_c_opt_fc (with a boolean selector field).
1396 This type conceptually inherits
1397 #BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD.
1399 BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD
= (1ULL << 19) | BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD
,
1403 \bt_c_opt_fc (with an integer selector field).
1405 This type conceptually inherits
1406 #BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD.
1408 No field class has this type: use it with
1409 bt_field_class_type_is().
1411 BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD
= (1ULL << 20) | BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD
,
1415 \bt_c_opt_fc (with an unsigned integer selector field).
1417 This type conceptually inherits
1418 #BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD.
1420 BT_FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
= (1ULL << 21) | BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD
,
1424 \bt_c_opt_fc (with a signed integer selector field).
1426 This type conceptually inherits
1427 #BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD.
1429 BT_FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD
= (1ULL << 22) | BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD
,
1435 No field class has this type: use it with
1436 bt_field_class_type_is().
1438 BT_FIELD_CLASS_TYPE_VARIANT
= 1ULL << 23,
1442 \bt_c_var_fc (without a selector field).
1444 BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD
= (1ULL << 24) | BT_FIELD_CLASS_TYPE_VARIANT
,
1448 \bt_c_var_fc (with a selector field).
1450 This type conceptually inherits
1451 #BT_FIELD_CLASS_TYPE_VARIANT.
1453 No field class has this type: use it with
1454 bt_field_class_type_is().
1456 BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD
= (1ULL << 25) | BT_FIELD_CLASS_TYPE_VARIANT
,
1460 \bt_c_var_fc (with an integer selector field).
1462 This type conceptually inherits
1463 #BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD.
1465 No field class has this type: use it with
1466 bt_field_class_type_is().
1468 BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD
= (1ULL << 26) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD
,
1472 \bt_c_opt_fc (with an unsigned integer selector field).
1474 This type conceptually inherits
1475 #BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD.
1477 BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
= (1ULL << 27) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD
,
1481 \bt_c_opt_fc (with a signed integer selector field).
1483 This type conceptually inherits
1484 #BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD.
1486 BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD
= (1ULL << 28) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD
,
1489 * Make sure the enumeration type is a 64-bit integer in case
1490 * the project needs field class types in the future.
1492 * This is not part of the API.
1494 __BT_FIELD_CLASS_TYPE_BIG_VALUE
= 1ULL << 62,
1495 } bt_field_class_type
;
1499 Returns the type enumerator of the field class \bt_p{field_class}.
1501 @param[in] field_class
1502 Field class of which to get the type enumerator
1505 Type enumerator of \bt_p{field_class}.
1507 @bt_pre_not_null{field_class}
1509 @sa bt_field_class_type_is() —
1510 Returns whether or not the type of a field class conceptually is a
1513 extern bt_field_class_type
bt_field_class_get_type(
1514 const bt_field_class
*field_class
);
1518 Returns whether or not the field class type \bt_p{type} conceptually
1519 \em is the field class type \bt_p{other_type}.
1521 For example, an \bt_uint_fc conceptually \em is an integer field class,
1525 bt_field_class_type_is(BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER, BT_FIELD_CLASS_TYPE_INTEGER)
1531 Field class type to check against \bt_p{other_type}.
1532 @param[in] other_type
1533 Field class type against which to check \bt_p{type}.
1536 #BT_TRUE if \bt_p{type} conceptually \em is \bt_p{other_type}.
1538 @sa bt_field_class_get_type() —
1539 Returns the type enumerator of a field class.
1542 bt_bool
bt_field_class_type_is(const bt_field_class_type type
,
1543 const bt_field_class_type other_type
)
1545 return (type
& other_type
) == other_type
;
1551 @name Common property
1557 Sets the user attributes of the field class \bt_p{field_class} to
1558 \bt_p{user_attributes}.
1560 See the \ref api-tir-fc-prop-user-attrs "user attributes" property.
1563 When you create a field class with one of the
1564 <code>bt_field_class_*_create()</code> functions, the field class's
1565 initial user attributes is an empty \bt_map_val. Therefore you can
1566 borrow it with bt_field_class_borrow_user_attributes() and fill it
1567 directly instead of setting a new one with this function.
1569 @param[in] field_class
1570 Field class of which to set the user attributes to
1571 \bt_p{user_attributes}.
1572 @param[in] user_attributes
1573 New user attributes of \bt_p{field_class}.
1575 @bt_pre_not_null{field_class}
1576 @bt_pre_hot{field_class}
1577 @bt_pre_not_null{user_attributes}
1578 @bt_pre_is_map_val{user_attributes}
1580 @sa bt_field_class_borrow_user_attributes() —
1581 Borrows the user attributes of a field class.
1583 extern void bt_field_class_set_user_attributes(
1584 bt_field_class
*field_class
, const bt_value
*user_attributes
);
1588 Borrows the user attributes of the field class \bt_p{field_class}.
1590 See the \ref api-tir-fc-prop-user-attrs "user attributes" property.
1593 When you create a field class with one of the
1594 <code>bt_field_class_*_create()</code> functions, the field class's
1595 initial user attributes is an empty \bt_map_val.
1597 @param[in] field_class
1598 Field class from which to borrow the user attributes.
1601 User attributes of \bt_p{field_class} (a \bt_map_val).
1603 @bt_pre_not_null{field_class}
1605 @sa bt_field_class_set_user_attributes() —
1606 Sets the user attributes of a field class.
1607 @sa bt_field_class_borrow_user_attributes_const() —
1608 \c const version of this function.
1610 extern bt_value
*bt_field_class_borrow_user_attributes(
1611 bt_field_class
*field_class
);
1615 Borrows the user attributes of the field class \bt_p{field_class}
1618 See bt_field_class_borrow_user_attributes().
1620 extern const bt_value
*bt_field_class_borrow_user_attributes_const(
1621 const bt_field_class
*field_class
);
1626 @name Boolean field class
1632 Creates a \bt_bool_fc from the trace class \bt_p{trace_class}.
1634 On success, the returned boolean field class has the following
1642 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
1643 <td>Empty \bt_map_val
1646 @param[in] trace_class
1647 Trace class from which to create a boolean field class.
1650 New boolean field class reference, or \c NULL on memory error.
1652 @bt_pre_not_null{trace_class}
1654 extern bt_field_class
*bt_field_class_bool_create(
1655 bt_trace_class
*trace_class
);
1662 @name Bit array field class
1668 Creates a \bt_ba_fc with the length \bt_p{length} from the trace
1669 class \bt_p{trace_class}.
1671 On success, the returned bit array field class has the following
1679 <td>\ref api-tir-fc-ba-prop-len "Length"
1682 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
1683 <td>Empty \bt_map_val
1686 @param[in] trace_class
1687 Trace class from which to create a bit array field class.
1689 Length (number of bits) of the instances of the bit array field
1693 New bit array field class reference, or \c NULL on memory error.
1695 @bt_pre_not_null{trace_class}
1697 0 < \bt_p{length} ≤ 64.
1699 extern bt_field_class
*bt_field_class_bit_array_create(
1700 bt_trace_class
*trace_class
, uint64_t length
);
1704 Returns the length of the \bt_ba_fc \bt_p{field_class}.
1706 See the \ref api-tir-fc-ba-prop-len "length" property.
1708 @param[in] field_class
1709 Bit array field class of which to get the length.
1712 Length of \bt_p{field_class}.
1714 @bt_pre_not_null{field_class}
1715 @bt_pre_is_ba_fc{field_class}
1717 extern uint64_t bt_field_class_bit_array_get_length(
1718 const bt_field_class
*field_class
);
1725 @name Integer field class
1731 Sets the field value range of the \bt_int_fc \bt_p{field_class}
1734 See the \ref api-tir-fc-int-prop-size "field value range" property.
1736 @param[in] field_class
1737 Integer field class of which to set the field value range to
1744 <dt>Unsigned integer field class</dt>
1745 <dd>[0, 2<sup><em>N</em></sup> - 1]</dd>
1747 <dt>Signed integer field class</dt>
1748 <dd>[-2<sup><em>N</em></sup>, 2<sup><em>N</em></sup> - 1]</dd>
1752 @bt_pre_not_null{field_class}
1753 @bt_pre_hot{field_class}
1754 @bt_pre_is_int_fc{field_class}
1758 @sa bt_field_class_integer_get_field_value_range() —
1759 Returns the field value range of an integer field class.
1761 extern void bt_field_class_integer_set_field_value_range(
1762 bt_field_class
*field_class
, uint64_t n
);
1766 Returns the field value range of the \bt_int_fc \bt_p{field_class}.
1768 See the \ref api-tir-fc-int-prop-size "field value range" property.
1770 @param[in] field_class
1771 Integer field class of which to get the field value range.
1775 Field value range of \bt_p{field_class}, that is, \em N in:
1778 <dt>Unsigned integer field class</dt>
1779 <dd>[0, 2<sup><em>N</em></sup> - 1]</dd>
1781 <dt>Signed integer field class</dt>
1782 <dd>[-2<sup><em>N</em></sup>, 2<sup><em>N</em></sup> - 1]</dd>
1786 @bt_pre_not_null{field_class}
1787 @bt_pre_is_int_fc{field_class}
1789 @sa bt_field_class_integer_set_field_value_range() —
1790 Sets the field value range of an integer field class.
1792 extern uint64_t bt_field_class_integer_get_field_value_range(
1793 const bt_field_class
*field_class
);
1797 Integer field class preferred display bases.
1799 typedef enum bt_field_class_integer_preferred_display_base
{
1804 BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_BINARY
= 2,
1810 BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_OCTAL
= 8,
1816 BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
= 10,
1822 BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_HEXADECIMAL
= 16,
1823 } bt_field_class_integer_preferred_display_base
;
1827 Sets the preferred display base of the \bt_int_fc \bt_p{field_class}
1828 to \bt_p{preferred_display_base}.
1830 See the \ref api-tir-fc-int-prop-base "preferred display base" property.
1832 @param[in] field_class
1833 Integer field class of which to set the preferred display base to
1834 \bt_p{preferred_display_base}.
1835 @param[in] preferred_display_base
1836 New preferred display base of \bt_p{field_class}.
1838 @bt_pre_not_null{field_class}
1839 @bt_pre_hot{field_class}
1840 @bt_pre_is_int_fc{field_class}
1842 @sa bt_field_class_integer_get_preferred_display_base() —
1843 Returns the preferred display base of an integer field class.
1845 extern void bt_field_class_integer_set_preferred_display_base(
1846 bt_field_class
*field_class
,
1847 bt_field_class_integer_preferred_display_base preferred_display_base
);
1851 Returns the preferred display base of the \bt_int_fc
1854 See the \ref api-tir-fc-int-prop-base "preferred display base" property.
1856 @param[in] field_class
1857 Integer field class of which to get the preferred display base.
1859 @retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_BINARY
1861 @retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_OCTAL
1863 @retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
1865 @retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_HEXADECIMAL
1868 @bt_pre_not_null{field_class}
1869 @bt_pre_is_int_fc{field_class}
1871 @sa bt_field_class_integer_set_preferred_display_base() —
1872 Sets the preferred display base of an integer field class.
1874 extern bt_field_class_integer_preferred_display_base
1875 bt_field_class_integer_get_preferred_display_base(
1876 const bt_field_class
*field_class
);
1881 @name Unsigned integer field class
1887 Creates an \bt_uint_fc from the trace class \bt_p{trace_class}.
1889 On success, the returned unsigned integer field class has the following
1897 <td>\ref api-tir-fc-int-prop-size "Field value range"
1898 <td>[0, 2<sup>64</sup> - 1]
1900 <td>\ref api-tir-fc-int-prop-base "Preferred display base"
1901 <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
1903 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
1904 <td>Empty \bt_map_val
1907 @param[in] trace_class
1908 Trace class from which to create an unsigned integer field class.
1911 New unsigned integer field class reference, or \c NULL on memory error.
1913 @bt_pre_not_null{trace_class}
1915 extern bt_field_class
*bt_field_class_integer_unsigned_create(
1916 bt_trace_class
*trace_class
);
1921 @name Signed integer field class
1927 Creates an \bt_sint_fc from the trace class \bt_p{trace_class}.
1929 On success, the returned signed integer field class has the following
1937 <td>\ref api-tir-fc-int-prop-size "Field value range"
1938 <td>[-2<sup>63</sup>, 2<sup>63</sup> - 1]
1940 <td>\ref api-tir-fc-int-prop-base "Preferred display base"
1941 <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
1943 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
1944 <td>Empty \bt_map_val
1947 @param[in] trace_class
1948 Trace class from which to create a signed integer field class.
1951 New signed integer field class reference, or \c NULL on memory error.
1953 @bt_pre_not_null{trace_class}
1955 extern bt_field_class
*bt_field_class_integer_signed_create(
1956 bt_trace_class
*trace_class
);
1961 @name Single-precision real field class
1967 Creates a single-precision \bt_real_fc from the trace class
1970 On success, the returned single-precision real field class has the
1971 following property value:
1978 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
1979 <td>Empty \bt_map_val
1982 @param[in] trace_class
1983 Trace class from which to create a single-preicision real
1987 New single-precision real field class reference, or \c NULL on
1990 @bt_pre_not_null{trace_class}
1992 extern bt_field_class
*bt_field_class_real_single_precision_create(
1993 bt_trace_class
*trace_class
);
1998 @name Double-precision real field class
2004 Creates a double-precision \bt_real_fc from the trace class
2007 On success, the returned double-precision real field class has the
2008 following property value:
2015 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2016 <td>Empty \bt_map_val
2019 @param[in] trace_class
2020 Trace class from which to create a double-preicision real
2024 New double-precision real field class reference, or \c NULL on
2027 @bt_pre_not_null{trace_class}
2029 extern bt_field_class
*bt_field_class_real_double_precision_create(
2030 bt_trace_class
*trace_class
);
2035 @name Enumeration field class
2041 Array of \c const \bt_enum_fc labels.
2043 Returned by bt_field_class_enumeration_unsigned_get_mapping_labels_for_value()
2044 and bt_field_class_enumeration_signed_get_mapping_labels_for_value().
2046 typedef char const * const *bt_field_class_enumeration_mapping_label_array
;
2051 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value()
2053 bt_field_class_enumeration_signed_get_mapping_labels_for_value().
2055 typedef enum bt_field_class_enumeration_get_mapping_labels_for_value_status
{
2060 BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2066 BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2067 } bt_field_class_enumeration_get_mapping_labels_for_value_status
;
2071 Status codes for bt_field_class_enumeration_unsigned_add_mapping()
2072 and bt_field_class_enumeration_signed_add_mapping().
2074 typedef enum bt_field_class_enumeration_add_mapping_status
{
2079 BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2085 BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2086 } bt_field_class_enumeration_add_mapping_status
;
2091 @name Enumeration field class mapping
2096 @typedef struct bt_field_class_enumeration_mapping bt_field_class_enumeration_mapping;
2099 Enumeration field class mapping.
2104 Returns the number of mappings contained in the \bt_enum_fc
2107 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2109 @param[in] field_class
2110 Enumeration field class of which to get the number of contained
2114 Number of contained mappings in \bt_p{field_class}.
2116 @bt_pre_not_null{field_class}
2117 @bt_pre_is_enum_fc{field_class}
2119 extern uint64_t bt_field_class_enumeration_get_mapping_count(
2120 const bt_field_class
*field_class
);
2124 Returns the label of the \bt_enum_fc mapping \bt_p{mapping}.
2126 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2129 Enumeration field class mapping of which to get the label.
2133 Label of \bt_p{mapping}.
2135 The returned pointer remains valid as long as \bt_p{mapping} exists.
2138 @bt_pre_not_null{mapping}
2140 extern const char *bt_field_class_enumeration_mapping_get_label(
2141 const bt_field_class_enumeration_mapping
*mapping
);
2146 @name Unsigned enumeration field class
2152 Creates an \bt_uenum_fc from the trace class \bt_p{trace_class}.
2154 On success, the returned unsigned enumeration field class has the
2155 following property values:
2162 <td>\ref api-tir-fc-int-prop-size "Field value range"
2163 <td>[0, 2<sup>64</sup> - 1]
2165 <td>\ref api-tir-fc-int-prop-base "Preferred display base"
2166 <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
2168 <td>\ref api-tir-fc-enum-prop-mappings "Mappings"
2171 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2172 <td>Empty \bt_map_val
2175 @param[in] trace_class
2176 Trace class from which to create an unsigned enumeration field
2180 New unsigned enumeration field class reference, or \c NULL on memory
2183 @bt_pre_not_null{trace_class}
2185 extern bt_field_class
*bt_field_class_enumeration_unsigned_create(
2186 bt_trace_class
*trace_class
);
2190 Adds a mapping to the \bt_uenum_fc \bt_p{field_class} having the
2191 label \bt_p{label} and the unsigned integer ranges \bt_p{ranges}.
2193 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2195 @param[in] field_class
2196 Unsigned enumeration field class to which to add a mapping having
2197 the label \bt_p{label} and the integer ranges \bt_p{ranges}.
2199 Label of the mapping to add to \bt_p{field_class} (copied).
2201 Unsigned integer ranges of the mapping to add to
2204 @retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK
2206 @retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR
2209 @bt_pre_not_null{field_class}
2210 @bt_pre_hot{field_class}
2211 @bt_pre_is_uenum_fc{field_class}
2212 @bt_pre_not_null{label}
2214 \bt_p{field_class} has no mapping with the label \bt_p{label}.
2215 @bt_pre_not_null{ranges}
2217 \bt_p{ranges} contains one or more unsigned integer ranges.
2219 extern bt_field_class_enumeration_add_mapping_status
2220 bt_field_class_enumeration_unsigned_add_mapping(
2221 bt_field_class
*field_class
, const char *label
,
2222 const bt_integer_range_set_unsigned
*ranges
);
2226 Borrows the mapping at index \bt_p{index} from the
2227 \bt_uenum_fc \bt_p{field_class}.
2229 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2231 @param[in] field_class
2232 Unsigned enumeration field class from which to borrow the mapping at
2235 Index of the mapping to borrow from \bt_p{field_class}.
2239 \em Borrowed reference of the mapping of
2240 \bt_p{field_class} at index \bt_p{index}.
2242 The returned pointer remains valid as long as \bt_p{field_class}
2246 @bt_pre_not_null{field_class}
2247 @bt_pre_is_uenum_fc{field_class}
2249 \bt_p{index} is less than the number of mappings in
2250 \bt_p{field_class} (as returned by
2251 bt_field_class_enumeration_get_mapping_count()).
2253 @sa bt_field_class_enumeration_get_mapping_count() —
2254 Returns the number of mappings contained in an
2255 enumeration field class.
2257 extern const bt_field_class_enumeration_unsigned_mapping
*
2258 bt_field_class_enumeration_unsigned_borrow_mapping_by_index_const(
2259 const bt_field_class
*field_class
, uint64_t index
);
2263 Borrows the mapping having the label \bt_p{label} from the
2264 \bt_uenum_fc \bt_p{field_class}.
2266 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2268 If there's no mapping having the label \bt_p{label} in
2269 \bt_p{field_class}, this function returns \c NULL.
2271 @param[in] field_class
2272 Unsigned enumeration field class from which to borrow the mapping
2273 having the label \bt_p{label}.
2275 Label of the mapping to borrow from \bt_p{field_class}.
2279 \em Borrowed reference of the mapping of
2280 \bt_p{field_class} having the label \bt_p{label}, or \c NULL
2283 The returned pointer remains valid as long as \bt_p{field_class}
2287 @bt_pre_not_null{field_class}
2288 @bt_pre_is_uenum_fc{field_class}
2289 @bt_pre_not_null{label}
2291 extern const bt_field_class_enumeration_unsigned_mapping
*
2292 bt_field_class_enumeration_unsigned_borrow_mapping_by_label_const(
2293 const bt_field_class
*field_class
, const char *label
);
2297 Returns an array of all the labels of the mappings of the
2298 \bt_uenum_fc \bt_p{field_class} of which the \bt_p_uint_rg contain
2299 the integral value \bt_p{value}.
2301 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2303 This function sets \bt_p{*labels} to the resulting array and
2304 \bt_p{*count} to the number of labels in \bt_p{*labels}.
2306 On success, if there's no mapping ranges containing the value
2307 \bt_p{value}, \bt_p{*count} is 0.
2309 @param[in] field_class
2310 Unsigned enumeration field class from which to get the labels of the
2311 mappings of which the ranges contain \bt_p{value}.
2313 Value for which to get the mapped labels in \bt_p{field_class}.
2316 <strong>On success</strong>, \bt_p{*labels}
2317 is an array of labels of the mappings of \bt_p{field_class}
2318 containing \bt_p{value}.
2320 The number of labels in \bt_p{*labels} is \bt_p{*count}.
2322 The array is owned by \bt_p{field_class} and remains valid as long
2325 - \bt_p{field_class} is not modified.
2326 - You don't call this function again with \bt_p{field_class}.
2329 <strong>On success</strong>, \bt_p{*count} is the number of labels
2330 in \bt_p{*labels} (can be 0).
2332 @retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK
2334 @retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR
2337 @bt_pre_not_null{field_class}
2338 @bt_pre_is_uenum_fc{field_class}
2339 @bt_pre_not_null{labels}
2340 @bt_pre_not_null{count}
2342 extern bt_field_class_enumeration_get_mapping_labels_for_value_status
2343 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value(
2344 const bt_field_class
*field_class
, uint64_t value
,
2345 bt_field_class_enumeration_mapping_label_array
*labels
,
2351 @name Unsigned enumeration field class mapping
2356 @typedef struct bt_field_class_enumeration_unsigned_mapping bt_field_class_enumeration_unsigned_mapping;
2359 Unsigned enumeration field class mapping.
2364 Borrows the \bt_p_uint_rg from the \bt_uenum_fc mapping
2367 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2370 Unsigned enumeration field class mapping from which to borrow the
2371 unsigned integer ranges.
2374 Unsigned integer ranges of \bt_p{mapping}.
2376 @bt_pre_not_null{mapping}
2378 extern const bt_integer_range_set_unsigned
*
2379 bt_field_class_enumeration_unsigned_mapping_borrow_ranges_const(
2380 const bt_field_class_enumeration_unsigned_mapping
*mapping
);
2384 \ref api-fund-c-typing "Upcasts" the \bt_uenum_fc mapping
2385 \bt_p{mapping} to the common #bt_field_class_enumeration_mapping
2388 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2392 Unsigned enumeration field class mapping to upcast.
2398 \bt_p{mapping} as a common enumeration field class mapping.
2401 const bt_field_class_enumeration_mapping
*
2402 bt_field_class_enumeration_unsigned_mapping_as_mapping_const(
2403 const bt_field_class_enumeration_unsigned_mapping
*mapping
)
2405 return __BT_UPCAST_CONST(bt_field_class_enumeration_mapping
, mapping
);
2411 @name Signed enumeration field class
2417 Creates a \bt_senum_fc from the trace class \bt_p{trace_class}.
2419 On success, the returned signed enumeration field class has the
2420 following property values:
2427 <td>\ref api-tir-fc-int-prop-size "Field value range"
2428 <td>[-2<sup>63</sup>, 2<sup>63</sup> - 1]
2430 <td>\ref api-tir-fc-int-prop-base "Preferred display base"
2431 <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
2433 <td>\ref api-tir-fc-enum-prop-mappings "Mappings"
2436 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2437 <td>Empty \bt_map_val
2440 @param[in] trace_class
2441 Trace class from which to create a signed enumeration field
2445 New signed enumeration field class reference, or \c NULL on memory
2448 @bt_pre_not_null{trace_class}
2450 extern bt_field_class
*bt_field_class_enumeration_signed_create(
2451 bt_trace_class
*trace_class
);
2455 Adds a mapping to the \bt_senum_fc \bt_p{field_class} having the
2456 label \bt_p{label} and the \bt_p_sint_rg \bt_p{ranges}.
2458 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2460 @param[in] field_class
2461 Signed enumeration field class to which to add a mapping having
2462 the label \bt_p{label} and the integer ranges \bt_p{ranges}.
2464 Label of the mapping to add to \bt_p{field_class} (copied).
2466 Signed integer ranges of the mapping to add to
2469 @retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK
2471 @retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR
2474 @bt_pre_not_null{field_class}
2475 @bt_pre_hot{field_class}
2476 @bt_pre_is_senum_fc{field_class}
2477 @bt_pre_not_null{label}
2479 \bt_p{field_class} has no mapping with the label \bt_p{label}.
2480 @bt_pre_not_null{ranges}
2482 \bt_p{ranges} contains one or more signed integer ranges.
2484 extern bt_field_class_enumeration_add_mapping_status
2485 bt_field_class_enumeration_signed_add_mapping(
2486 bt_field_class
*field_class
, const char *label
,
2487 const bt_integer_range_set_signed
*ranges
);
2491 Borrows the mapping at index \bt_p{index} from the
2492 \bt_senum_fc \bt_p{field_class}.
2494 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2496 @param[in] field_class
2497 Signed enumeration field class from which to borrow the mapping at
2500 Index of the mapping to borrow from \bt_p{field_class}.
2504 \em Borrowed reference of the mapping of
2505 \bt_p{field_class} at index \bt_p{index}.
2507 The returned pointer remains valid as long as \bt_p{field_class}
2511 @bt_pre_not_null{field_class}
2512 @bt_pre_is_senum_fc{field_class}
2514 \bt_p{index} is less than the number of mappings in
2515 \bt_p{field_class} (as returned by
2516 bt_field_class_enumeration_get_mapping_count()).
2518 @sa bt_field_class_enumeration_get_mapping_count() —
2519 Returns the number of mappings contained in an
2520 enumeration field class.
2522 extern const bt_field_class_enumeration_signed_mapping
*
2523 bt_field_class_enumeration_signed_borrow_mapping_by_index_const(
2524 const bt_field_class
*field_class
, uint64_t index
);
2528 Borrows the mapping having the label \bt_p{label} from the
2529 \bt_senum_fc \bt_p{field_class}.
2531 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2533 If there's no mapping having the label \bt_p{label} in
2534 \bt_p{field_class}, this function returns \c NULL.
2536 @param[in] field_class
2537 Signed enumeration field class from which to borrow the mapping
2538 having the label \bt_p{label}.
2540 Label of the mapping to borrow from \bt_p{field_class}.
2544 \em Borrowed reference of the mapping of
2545 \bt_p{field_class} having the label \bt_p{label}, or \c NULL
2548 The returned pointer remains valid as long as \bt_p{field_class}
2552 @bt_pre_not_null{field_class}
2553 @bt_pre_is_senum_fc{field_class}
2554 @bt_pre_not_null{label}
2556 extern const bt_field_class_enumeration_signed_mapping
*
2557 bt_field_class_enumeration_signed_borrow_mapping_by_label_const(
2558 const bt_field_class
*field_class
, const char *label
);
2562 Returns an array of all the labels of the mappings of the
2563 \bt_senum_fc \bt_p{field_class} of which the \bt_p_sint_rg contain
2564 the integral value \bt_p{value}.
2566 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2568 This function sets \bt_p{*labels} to the resulting array and
2569 \bt_p{*count} to the number of labels in \bt_p{*labels}.
2571 On success, if there's no mapping ranges containing the value
2572 \bt_p{value}, \bt_p{*count} is 0.
2574 @param[in] field_class
2575 Signed enumeration field class from which to get the labels of the
2576 mappings of which the ranges contain \bt_p{value}.
2578 Value for which to get the mapped labels in \bt_p{field_class}.
2581 <strong>On success</strong>, \bt_p{*labels}
2582 is an array of labels of the mappings of \bt_p{field_class}
2583 containing \bt_p{value}.
2585 The number of labels in \bt_p{*labels} is \bt_p{*count}.
2587 The array is owned by \bt_p{field_class} and remains valid as long
2590 - \bt_p{field_class} is not modified.
2591 - You don't call this function again with \bt_p{field_class}.
2594 <strong>On success</strong>, \bt_p{*count} is the number of labels
2595 in \bt_p{*labels} (can be 0).
2597 @retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK
2599 @retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR
2602 @bt_pre_not_null{field_class}
2603 @bt_pre_is_senum_fc{field_class}
2604 @bt_pre_not_null{labels}
2605 @bt_pre_not_null{count}
2607 extern bt_field_class_enumeration_get_mapping_labels_for_value_status
2608 bt_field_class_enumeration_signed_get_mapping_labels_for_value(
2609 const bt_field_class
*field_class
, int64_t value
,
2610 bt_field_class_enumeration_mapping_label_array
*labels
,
2616 @name Signed enumeration field class mapping
2621 @typedef struct bt_field_class_enumeration_signed_mapping bt_field_class_enumeration_signed_mapping;
2624 Signed enumeration field class mapping.
2629 Borrows the \bt_p_sint_rg from the \bt_senum_fc mapping
2632 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2635 Signed enumeration field class mapping from which to borrow the
2636 signed integer ranges.
2639 Signed integer ranges of \bt_p{mapping}.
2641 @bt_pre_not_null{mapping}
2643 extern const bt_integer_range_set_signed
*
2644 bt_field_class_enumeration_signed_mapping_borrow_ranges_const(
2645 const bt_field_class_enumeration_signed_mapping
*mapping
);
2649 \ref api-fund-c-typing "Upcasts" the \bt_senum_fc mapping
2650 \bt_p{mapping} to the common #bt_field_class_enumeration_mapping
2653 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2657 Signed enumeration field class mapping to upcast.
2663 \bt_p{mapping} as a common enumeration field class mapping.
2666 const bt_field_class_enumeration_mapping
*
2667 bt_field_class_enumeration_signed_mapping_as_mapping_const(
2668 const bt_field_class_enumeration_signed_mapping
*mapping
)
2670 return __BT_UPCAST_CONST(bt_field_class_enumeration_mapping
, mapping
);
2676 @name String field class
2682 Creates a \bt_string_fc from the trace class \bt_p{trace_class}.
2684 On success, the returned string field class has the following property
2692 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2693 <td>Empty \bt_map_val
2696 @param[in] trace_class
2697 Trace class from which to create a string field class.
2700 New string field class reference, or \c NULL on memory error.
2702 @bt_pre_not_null{trace_class}
2704 extern bt_field_class
*bt_field_class_string_create(
2705 bt_trace_class
*trace_class
);
2710 @name Array field class
2716 Borrows the element field class from the \bt_array_fc
2719 See the \ref api-tir-fc-array-prop-elem-fc "element field class"
2722 @param[in] field_class
2723 Array field class from which to borrow the element field class.
2726 Element field class of \bt_p{field_class}.
2728 @bt_pre_not_null{field_class}
2729 @bt_pre_is_array_fc{field_class}
2731 @sa bt_field_class_array_borrow_element_field_class_const() —
2732 \c const version of this function.
2734 extern bt_field_class
*bt_field_class_array_borrow_element_field_class(
2735 bt_field_class
*field_class
);
2739 Borrows the element field class from the \bt_array_fc
2740 \bt_p{field_class} (\c const version).
2742 See bt_field_class_array_borrow_element_field_class().
2744 extern const bt_field_class
*
2745 bt_field_class_array_borrow_element_field_class_const(
2746 const bt_field_class
*field_class
);
2751 @name Static array field class
2757 Creates a \bt_sarray_fc having the element field class
2758 \bt_p{element_field_class} and the length \bt_p{length} from the
2759 trace class \bt_p{trace_class}.
2761 On success, the returned static array field class has the following
2769 <td>\ref api-tir-fc-array-prop-elem-fc "Element field class"
2770 <td>\bt_p{element_field_class}
2772 <td>\ref api-tir-fc-sarray-prop-len "Length"
2775 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2776 <td>Empty \bt_map_val
2779 @param[in] trace_class
2780 Trace class from which to create a static array field class.
2781 @param[in] element_field_class
2782 Class of the element fields of the instances of the static array
2783 field class to create.
2785 Length of the instances of the static array field class to create.
2788 New static array field class reference, or \c NULL on memory error.
2790 @bt_pre_not_null{trace_class}
2791 @bt_pre_not_null{element_field_class}
2792 bt_pre_fc_not_in_tc{element_field_class}
2794 @bt_post_success_frozen{element_field_class}
2796 extern bt_field_class
*bt_field_class_array_static_create(
2797 bt_trace_class
*trace_class
,
2798 bt_field_class
*element_field_class
, uint64_t length
);
2802 Returns the length of the \bt_sarray_fc \bt_p{field_class}.
2804 See the \ref api-tir-fc-sarray-prop-len "length" property.
2806 @param[in] field_class
2807 Static array field class of which to get the length.
2810 Length of \bt_p{field_class}.
2812 @bt_pre_not_null{field_class}
2813 @bt_pre_is_sarray_fc{field_class}
2815 extern uint64_t bt_field_class_array_static_get_length(
2816 const bt_field_class
*field_class
);
2821 @name Dynamic array field class
2827 Creates a \bt_darray_fc having the element field class
2828 \bt_p{element_field_class} from the trace class \bt_p{trace_class}.
2830 If \bt_p{length_field_class} is not \c NULL, then the created dynamic
2831 array field class has a linked length field class.
2833 \ref api-tir-fc-link "Field classes with links to other field classes"
2836 On success, the returned dynamic array field class has the following
2844 <td>\ref api-tir-fc-array-prop-elem-fc "Element field class"
2845 <td>\bt_p{element_field_class}
2847 <td>\ref api-tir-fc-darray-prop-len-fp "Length field path"
2849 \em None (if \bt_p{length_field_class} is not \c NULL, this
2850 property becomes available when the returned field class becomes
2851 part of an \bt_ev_cls or of a \bt_stream_cls)
2853 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2854 <td>Empty \bt_map_val
2857 @param[in] trace_class
2858 Trace class from which to create a dynamic array field class.
2859 @param[in] element_field_class
2860 Class of the element fields of the instances of the dynamic array
2861 field class to create.
2862 @param[in] length_field_class
2864 Linked length field class of the dynamic array field class to
2871 New dynamic array field class reference, or \c NULL on memory error.
2873 @bt_pre_not_null{trace_class}
2874 @bt_pre_not_null{element_field_class}
2875 @bt_pre_fc_not_in_tc{element_field_class}
2877 <strong>If \bt_p{length_field_class} is not \c NULL</strong>,
2878 \bt_p{length_field_class} is an \bt_uint_fc.
2880 @bt_post_success_frozen{element_field_class}
2881 @bt_post_success_frozen{length_field_class}
2883 extern bt_field_class
*bt_field_class_array_dynamic_create(
2884 bt_trace_class
*trace_class
,
2885 bt_field_class
*element_field_class
,
2886 bt_field_class
*length_field_class
);
2891 @name Dynamic array field class with length field
2897 Borrows the length field path from the \bt_darray_fc (with a length
2898 field) \bt_p{field_class}.
2900 See the \ref api-tir-fc-darray-prop-len-fp "length field path" property.
2902 This property is only available when a \bt_struct_fc containing
2903 (recursively) \bt_p{field_class} is passed to one of:
2905 - bt_stream_class_set_packet_context_field_class()
2906 - bt_stream_class_set_event_common_context_field_class()
2907 - bt_event_class_set_specific_context_field_class()
2908 - bt_event_class_set_payload_field_class()
2910 In the meantime, this function returns \c NULL.
2912 @param[in] field_class
2913 Dynamic array field class from which to borrow the length
2917 Length field path of \bt_p{field_class}.
2919 @bt_pre_not_null{field_class}
2920 @bt_pre_is_darray_wl_fc{field_class}
2922 extern const bt_field_path
*
2923 bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const(
2924 const bt_field_class
*field_class
);
2929 @name Structure field class
2935 Creates a \bt_struct_fc from the trace class \bt_p{trace_class}.
2937 On success, the returned structure field class has the following
2945 <td>\ref api-tir-fc-struct-prop-members "Members"
2948 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2949 <td>Empty \bt_map_val
2952 @param[in] trace_class
2953 Trace class from which to create a structure field class.
2956 New structure field class reference, or \c NULL on memory error.
2958 @bt_pre_not_null{trace_class}
2960 extern bt_field_class
*bt_field_class_structure_create(
2961 bt_trace_class
*trace_class
);
2965 Status codes for bt_field_class_structure_append_member().
2967 typedef enum bt_field_class_structure_append_member_status
{
2972 BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2978 BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2979 } bt_field_class_structure_append_member_status
;
2983 Appends a member to the \bt_struct_fc \bt_p{field_class} having the
2984 name \bt_p{name} and the field class \bt_p{member_field_class}.
2986 See the \ref api-tir-fc-struct-prop-members "members" property.
2988 @param[in] field_class
2989 Structure field class to which to append a member having
2990 the name \bt_p{name} and the field class \bt_p{member_field_class}.
2992 Name of the member to append to \bt_p{field_class} (copied).
2993 @param[in] member_field_class
2994 Field class of the member to append to \bt_p{field_class}.
2996 @retval #BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_OK
2998 @retval #BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_MEMORY_ERROR
3001 @bt_pre_not_null{field_class}
3002 @bt_pre_hot{field_class}
3003 @bt_pre_is_struct_fc{field_class}
3005 \bt_p{field_class} has no member with the name \bt_p{name}.
3006 @bt_pre_not_null{name}
3007 @bt_pre_not_null{member_field_class}
3008 @bt_pre_fc_not_in_tc{member_field_class}
3010 @bt_post_success_frozen{member_field_class}
3012 extern bt_field_class_structure_append_member_status
3013 bt_field_class_structure_append_member(
3014 bt_field_class
*field_class
,
3015 const char *name
, bt_field_class
*member_field_class
);
3019 Returns the number of members contained in the \bt_struct_fc
3022 See the \ref api-tir-fc-struct-prop-members "members" property.
3024 @param[in] field_class
3025 Structure field class of which to get the number of contained
3029 Number of contained members in \bt_p{field_class}.
3031 @bt_pre_not_null{field_class}
3032 @bt_pre_is_struct_fc{field_class}
3034 extern uint64_t bt_field_class_structure_get_member_count(
3035 const bt_field_class
*field_class
);
3039 Borrows the member at index \bt_p{index} from the
3040 \bt_struct_fc \bt_p{field_class}.
3042 See the \ref api-tir-fc-struct-prop-members "members" property.
3044 @param[in] field_class
3045 Structure field class from which to borrow the member at
3048 Index of the member to borrow from \bt_p{field_class}.
3052 \em Borrowed reference of the member of
3053 \bt_p{field_class} at index \bt_p{index}.
3055 The returned pointer remains valid as long as \bt_p{field_class}
3059 @bt_pre_not_null{field_class}
3060 @bt_pre_is_struct_fc{field_class}
3062 \bt_p{index} is less than the number of members in
3063 \bt_p{field_class} (as returned by
3064 bt_field_class_structure_get_member_count()).
3066 @sa bt_field_class_structure_get_member_count() —
3067 Returns the number of members contained in a structure field class.
3068 @sa bt_field_class_structure_borrow_member_by_index_const() —
3069 \c const version of this function.
3071 extern bt_field_class_structure_member
*
3072 bt_field_class_structure_borrow_member_by_index(
3073 bt_field_class
*field_class
, uint64_t index
);
3077 Borrows the member at index \bt_p{index} from the
3078 \bt_struct_fc \bt_p{field_class} (\c const version).
3080 See bt_field_class_structure_borrow_member_by_index().
3082 extern const bt_field_class_structure_member
*
3083 bt_field_class_structure_borrow_member_by_index_const(
3084 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
);
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
);
3137 @name Structure field class member
3142 @typedef struct bt_field_class_structure_member bt_field_class_structure_member;
3145 Structure field class member.
3150 Returns the name of the \bt_struct_fc member \bt_p{member}.
3152 See the \ref api-tir-fc-struct-prop-members "members" property.
3155 Structure field class member of which to get the name.
3159 Name of \bt_p{member}.
3161 The returned pointer remains valid as long as \bt_p{member} exists.
3164 @bt_pre_not_null{member}
3166 extern const char *bt_field_class_structure_member_get_name(
3167 const bt_field_class_structure_member
*member
);
3171 Borrows the field class from the \bt_struct_fc member
3174 See the \ref api-tir-fc-struct-prop-members "members" property.
3177 Structure field class member from which to borrow the field class.
3180 Field class of \bt_p{member}.
3182 @bt_pre_not_null{member}
3184 @sa bt_field_class_structure_member_borrow_field_class_const() —
3185 \c const version of this function.
3187 extern bt_field_class
*
3188 bt_field_class_structure_member_borrow_field_class(
3189 bt_field_class_structure_member
*member
);
3193 Borrows the field class from the \bt_struct_fc member
3194 \bt_p{member} (\c const version).
3196 See bt_field_class_structure_member_borrow_field_class().
3198 extern const bt_field_class
*
3199 bt_field_class_structure_member_borrow_field_class_const(
3200 const bt_field_class_structure_member
*member
);
3204 Sets the user attributes of the \bt_struct_fc member \bt_p{member}
3205 to \bt_p{user_attributes}.
3207 See the \ref api-tir-fc-struct-prop-members "members" property.
3210 When you append a member to a structure field class with
3211 bt_field_class_structure_append_member(), the member's
3212 initial user attributes is an empty \bt_map_val. Therefore you can
3214 bt_field_class_structure_member_borrow_user_attributes() and fill it
3215 directly instead of setting a new one with this function.
3218 Structure field class member of which to set the user attributes to
3219 \bt_p{user_attributes}.
3220 @param[in] user_attributes
3221 New user attributes of \bt_p{member}.
3223 @bt_pre_not_null{member}
3225 @bt_pre_not_null{user_attributes}
3226 @bt_pre_is_map_val{user_attributes}
3228 @sa bt_field_class_structure_member_borrow_user_attributes() —
3229 Borrows the user attributes of a structure field class member.
3231 extern void bt_field_class_structure_member_set_user_attributes(
3232 bt_field_class_structure_member
*member
,
3233 const bt_value
*user_attributes
);
3237 Borrows the user attributes of the \bt_struct_fc member
3240 See the \ref api-tir-fc-struct-prop-members "members" property.
3243 When you append a member to a structure field class with
3244 bt_field_class_structure_append_member(), the member's
3245 initial user attributes is an empty \bt_map_val.
3248 Structure field class member from which to borrow the user
3252 User attributes of \bt_p{member} (a \bt_map_val).
3254 @bt_pre_not_null{member}
3256 @sa bt_field_class_structure_member_set_user_attributes() —
3257 Sets the user attributes of a structure field class member.
3258 @sa bt_field_class_structure_member_borrow_user_attributes_const() —
3259 \c const version of this function.
3262 bt_field_class_structure_member_borrow_user_attributes(
3263 bt_field_class_structure_member
*member
);
3267 Borrows the user attributes of the \bt_struct_fc member
3268 \bt_p{member} (\c const version).
3270 See bt_field_class_structure_member_borrow_user_attributes().
3272 extern const bt_value
*
3273 bt_field_class_structure_member_borrow_user_attributes_const(
3274 const bt_field_class_structure_member
*member
);
3279 @name Option field class
3285 Borrows the optional field class from the \bt_opt_fc
3288 See the \ref api-tir-fc-opt-prop-fc "optional field class" property.
3290 @param[in] field_class
3291 Option field class from which to borrow the optional field class.
3294 Optional field class of \bt_p{field_class}.
3296 @bt_pre_not_null{field_class}
3297 @bt_pre_is_opt_fc{field_class}
3299 @sa bt_field_class_option_borrow_field_class_const() —
3300 \c const version of this function.
3302 extern bt_field_class
*bt_field_class_option_borrow_field_class(
3303 bt_field_class
*field_class
);
3307 Borrows the optional field class from the \bt_opt_fc
3308 \bt_p{field_class} (\c const version).
3310 See bt_field_class_option_borrow_field_class().
3312 extern const bt_field_class
*
3313 bt_field_class_option_borrow_field_class_const(
3314 const bt_field_class
*field_class
);
3319 @name Option field class without a selector field
3325 Creates an \bt_opt_fc (without a selector field) having the optional
3326 field class \bt_p{optional_field_class} from the trace class
3329 On success, the returned option field class has the following property
3337 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
3338 <td>\bt_p{optional_field_class}
3340 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3341 <td>Empty \bt_map_val
3344 @param[in] trace_class
3345 Trace class from which to create an option field class.
3346 @param[in] optional_field_class
3347 Class of the optional fields of the instances of the option field
3351 New option field class reference, or \c NULL on memory error.
3353 @bt_pre_not_null{trace_class}
3354 @bt_pre_not_null{optional_field_class}
3355 @bt_pre_fc_not_in_tc{optional_field_class}
3357 @bt_post_success_frozen{optional_field_class}
3359 extern bt_field_class
*bt_field_class_option_without_selector_create(
3360 bt_trace_class
*trace_class
,
3361 bt_field_class
*optional_field_class
);
3366 @name Option field class with a selector field
3372 Borrows the selector field path from the \bt_opt_fc (with a selector
3373 field) \bt_p{field_class}.
3375 See the \ref api-tir-fc-opt-prop-sel-fp "selector field path" property.
3377 This property is only available when a \bt_struct_fc containing
3378 (recursively) \bt_p{field_class} is passed to one of:
3380 - bt_stream_class_set_packet_context_field_class()
3381 - bt_stream_class_set_event_common_context_field_class()
3382 - bt_event_class_set_specific_context_field_class()
3383 - bt_event_class_set_payload_field_class()
3385 In the meantime, this function returns \c NULL.
3387 @param[in] field_class
3388 Option field class from which to borrow the selector field path.
3391 Selector field path of \bt_p{field_class}.
3393 @bt_pre_not_null{field_class}
3394 @bt_pre_is_opt_ws_fc{field_class}
3396 extern const bt_field_path
*
3397 bt_field_class_option_with_selector_field_borrow_selector_field_path_const(
3398 const bt_field_class
*field_class
);
3403 @name Option field class with a boolean selector field
3409 Creates an \bt_opt_fc (with a boolean selector field) having the
3410 optional field class \bt_p{optional_field_class} from the trace
3411 class \bt_p{trace_class}.
3413 On success, the returned option field class has the following property
3421 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
3422 <td>\bt_p{optional_field_class}
3424 <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
3426 \em None (this property becomes available when the returned field
3427 class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
3429 <td>\ref api-tir-fc-opt-prop-sel-rev "Selector is reversed?"
3432 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3433 <td>Empty \bt_map_val
3436 @param[in] trace_class
3437 Trace class from which to create an option field class.
3438 @param[in] optional_field_class
3439 Class of the optional fields of the instances of the option field
3441 @param[in] selector_field_class
3442 Linked selector field class of the option field class to create.
3445 New option field class reference, or \c NULL on memory error.
3447 @bt_pre_not_null{trace_class}
3448 @bt_pre_not_null{optional_field_class}
3449 @bt_pre_fc_not_in_tc{optional_field_class}
3450 @bt_pre_not_null{selector_field_class}
3452 \bt_p{selector_field_class} is a \bt_bool_fc.
3454 @bt_post_success_frozen{optional_field_class}
3455 @bt_post_success_frozen{selector_field_class}
3457 extern bt_field_class
*bt_field_class_option_with_selector_field_bool_create(
3458 bt_trace_class
*trace_class
,
3459 bt_field_class
*optional_field_class
,
3460 bt_field_class
*selector_field_class
);
3464 Sets whether or not the selector of the \bt_opt_fc (with a boolean
3465 selector field) \bt_p{field_class} is reversed.
3467 See the \ref api-tir-fc-opt-prop-sel-rev "selector is reversed?"
3470 @param[in] field_class
3471 Option field class of which to set whether or not its selector
3473 @param[in] selector_is_reversed
3474 #BT_TRUE to make \bt_p{field_class} have a reversed selector.
3476 @bt_pre_not_null{field_class}
3477 @bt_pre_hot{field_class}
3478 @bt_pre_is_opt_wbs_fc{field_class}
3480 @sa bt_field_class_option_with_selector_field_bool_selector_is_reversed() —
3481 Returns whether or not the selector of an option field class (with
3482 a boolean selector field) is reversed.
3485 bt_field_class_option_with_selector_field_bool_set_selector_is_reversed(
3486 bt_field_class
*field_class
, bt_bool selector_is_reversed
);
3490 Returns whether or not the selector of the
3491 \bt_opt_fc (with a boolean selector field) is reversed.
3493 See the \ref api-tir-fc-opt-prop-sel-rev "selector is reversed?"
3496 @param[in] field_class
3497 Option field class of which to get whether or not its selector is
3501 #BT_TRUE if the selector of \bt_p{field_class} is reversed.
3503 @bt_pre_not_null{field_class}
3504 @bt_pre_is_opt_wbs_fc{field_class}
3506 @sa bt_field_class_option_with_selector_field_bool_set_selector_is_reversed() —
3507 Sets whether or not the selector of an option field class (with
3508 a boolean selector field) is reversed.
3511 bt_field_class_option_with_selector_field_bool_selector_is_reversed(
3512 const bt_field_class
*field_class
);
3517 @name Option field class with an unsigned integer selector field
3523 Creates an \bt_opt_fc (with an unsigned integer selector field)
3524 having the optional field class \bt_p{optional_field_class} from the
3525 trace class \bt_p{trace_class}.
3527 On success, the returned option field class has the following property
3535 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
3536 <td>\bt_p{optional_field_class}
3538 <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
3540 \em None (this property becomes available when the returned field
3541 class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
3543 <td>\ref api-tir-fc-opt-prop-uint-rs "Selector's unsigned integer ranges"
3546 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3547 <td>Empty \bt_map_val
3550 @param[in] trace_class
3551 Trace class from which to create an option field class.
3552 @param[in] optional_field_class
3553 Class of the optional fields of the instances of the option field
3555 @param[in] selector_field_class
3556 Linked selector field class of the option field class to create.
3558 Selector's unsigned integer ranges of the option field class to
3562 New option field class reference, or \c NULL on memory error.
3564 @bt_pre_not_null{trace_class}
3565 @bt_pre_not_null{optional_field_class}
3566 @bt_pre_fc_not_in_tc{optional_field_class}
3567 @bt_pre_not_null{selector_field_class}
3569 \bt_p{selector_field_class} is a \bt_uint_fc.
3570 @bt_pre_not_null{ranges}
3572 \bt_p{ranges} contains one or more \bt_p_uint_rg.
3574 @bt_post_success_frozen{optional_field_class}
3575 @bt_post_success_frozen{selector_field_class}
3576 @bt_post_success_frozen{ranges}
3578 extern bt_field_class
*
3579 bt_field_class_option_with_selector_field_integer_unsigned_create(
3580 bt_trace_class
*trace_class
,
3581 bt_field_class
*optional_field_class
,
3582 bt_field_class
*selector_field_class
,
3583 const bt_integer_range_set_unsigned
*ranges
);
3587 Borrows the \bt_p_uint_rg from the \bt_opt_fc (with an unsigned
3588 integer selector field) \bt_p{field_class}.
3591 \ref api-tir-fc-opt-prop-uint-rs "selector's unsigned integer ranges"
3594 @param[in] field_class
3595 Option field class from which to borrow the unsigned integer ranges.
3598 Unsigned integer ranges of \bt_p{field_class}.
3600 @bt_pre_not_null{field_class}
3601 @bt_pre_is_opt_wuis_fc{field_class}
3603 extern const bt_integer_range_set_unsigned
*
3604 bt_field_class_option_with_selector_field_integer_unsigned_borrow_selector_ranges_const(
3605 const bt_field_class
*field_class
);
3610 @name Option field class with a signed integer selector field
3616 Creates an \bt_opt_fc (with a signed integer selector field)
3617 having the optional field class \bt_p{optional_field_class} from the
3618 trace class \bt_p{trace_class}.
3620 On success, the returned option field class has the following property
3628 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
3629 <td>\bt_p{optional_field_class}
3631 <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
3633 \em None (this property becomes available when the returned field
3634 class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
3636 <td>\ref api-tir-fc-opt-prop-sint-rs "Selector's signed integer ranges"
3639 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3640 <td>Empty \bt_map_val
3643 @param[in] trace_class
3644 Trace class from which to create an option field class.
3645 @param[in] optional_field_class
3646 Class of the optional fields of the instances of the option field
3648 @param[in] selector_field_class
3649 Linked selector field class of the option field class to create.
3651 Selector's signed integer ranges of the option field class to
3655 New option field class reference, or \c NULL on memory error.
3657 @bt_pre_not_null{trace_class}
3658 @bt_pre_not_null{optional_field_class}
3659 @bt_pre_fc_not_in_tc{optional_field_class}
3660 @bt_pre_not_null{selector_field_class}
3662 \bt_p{selector_field_class} is a \bt_uint_fc.
3663 @bt_pre_not_null{ranges}
3665 \bt_p{ranges} contains one or more \bt_p_uint_rg.
3667 @bt_post_success_frozen{optional_field_class}
3668 @bt_post_success_frozen{selector_field_class}
3669 @bt_post_success_frozen{ranges}
3671 extern bt_field_class
*
3672 bt_field_class_option_with_selector_field_integer_signed_create(
3673 bt_trace_class
*trace_class
,
3674 bt_field_class
*optional_field_class
,
3675 bt_field_class
*selector_field_class
,
3676 const bt_integer_range_set_signed
*ranges
);
3680 Borrows the \bt_p_sint_rg from the \bt_opt_fc (with a signed
3681 integer selector field) \bt_p{field_class}.
3684 \ref api-tir-fc-opt-prop-sint-rs "selector's signed integer ranges"
3687 @param[in] field_class
3688 Option field class from which to borrow the signed integer ranges.
3691 Signed integer ranges of \bt_p{field_class}.
3693 @bt_pre_not_null{field_class}
3694 @bt_pre_is_opt_wsis_fc{field_class}
3696 extern const bt_integer_range_set_signed
*
3697 bt_field_class_option_with_selector_field_integer_signed_borrow_selector_ranges_const(
3698 const bt_field_class
*field_class
);
3703 @name Variant field class
3709 Creates a \bt_var_fc from the trace class \bt_p{trace_class}.
3711 If \bt_p{selector_field_class} is not \c NULL, then the created variant
3712 field class has a linked selector field class.
3714 \ref api-tir-fc-link "Field classes with links to other field classes"
3717 On success, the returned variant field class has the following
3725 <td>\ref api-tir-fc-var-prop-sel-fp "Selector field path"
3727 \em None (if \bt_p{selector_field_class} is not \c NULL, this
3728 property becomes available when the returned field class becomes
3729 part of an \bt_ev_cls or of a \bt_stream_cls)
3731 <td>\ref api-tir-fc-var-prop-opts "Options"
3734 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3735 <td>Empty \bt_map_val
3738 @param[in] trace_class
3739 Trace class from which to create a variant field class.
3740 @param[in] selector_field_class
3742 Linked selector field class of the variant field class to create.
3748 New variant field class reference, or \c NULL on memory error.
3750 @bt_pre_not_null{trace_class}
3752 <strong>If \bt_p{selector_field_class} is not \c NULL</strong>,
3753 \bt_p{selector_field_class} is an \bt_int_fc.
3755 @bt_post_success_frozen{element_field_class}
3756 @bt_post_success_frozen{selector_field_class}
3758 extern bt_field_class
*bt_field_class_variant_create(
3759 bt_trace_class
*trace_class
,
3760 bt_field_class
*selector_field_class
);
3764 Returns the number of options contained in the \bt_var_fc
3767 See the \ref api-tir-fc-var-prop-opts "options" property.
3769 @param[in] field_class
3770 Variant field class of which to get the number of contained
3774 Number of contained options in \bt_p{field_class}.
3776 @bt_pre_not_null{field_class}
3777 @bt_pre_is_var_fc{field_class}
3779 extern uint64_t bt_field_class_variant_get_option_count(
3780 const bt_field_class
*field_class
);
3784 Borrows the option at index \bt_p{index} from the
3785 \bt_var_fc \bt_p{field_class}.
3787 See the \ref api-tir-fc-var-prop-opts "options" property.
3789 @param[in] field_class
3790 Variant field class from which to borrow the option at
3793 Index of the option to borrow from \bt_p{field_class}.
3797 \em Borrowed reference of the option of
3798 \bt_p{field_class} at index \bt_p{index}.
3800 The returned pointer remains valid as long as \bt_p{field_class}
3804 @bt_pre_not_null{field_class}
3805 @bt_pre_is_var_fc{field_class}
3807 \bt_p{index} is less than the number of options in
3808 \bt_p{field_class} (as returned by
3809 bt_field_class_variant_get_option_count()).
3811 @sa bt_field_class_variant_get_option_count() —
3812 Returns the number of options contained in a variant field class.
3813 @sa bt_field_class_variant_borrow_option_by_index_const() —
3814 \c const version of this function.
3816 extern bt_field_class_variant_option
*
3817 bt_field_class_variant_borrow_option_by_index(
3818 bt_field_class
*field_class
, uint64_t index
);
3822 Borrows the option at index \bt_p{index} from the
3823 \bt_var_fc \bt_p{field_class} (\c const version).
3825 See bt_field_class_variant_borrow_option_by_index().
3827 extern const bt_field_class_variant_option
*
3828 bt_field_class_variant_borrow_option_by_index_const(
3829 const bt_field_class
*field_class
, uint64_t index
);
3833 Borrows the option having the name \bt_p{name} from the
3834 \bt_var_fc \bt_p{field_class}.
3836 See the \ref api-tir-fc-var-prop-opts "options" property.
3838 If there's no option having the name \bt_p{name} in
3839 \bt_p{field_class}, this function returns \c NULL.
3841 @param[in] field_class
3842 Variant field class from which to borrow the option having the
3845 Name of the option to borrow from \bt_p{field_class}.
3849 \em Borrowed reference of the option of
3850 \bt_p{field_class} having the name \bt_p{name}, or \c NULL
3853 The returned pointer remains valid as long as \bt_p{field_class}
3857 @bt_pre_not_null{field_class}
3858 @bt_pre_is_var_fc{field_class}
3859 @bt_pre_not_null{name}
3861 @sa bt_field_class_variant_borrow_option_by_name_const() —
3862 \c const version of this function.
3864 extern bt_field_class_variant_option
*
3865 bt_field_class_variant_borrow_option_by_name(
3866 bt_field_class
*field_class
, const char *name
);
3870 Borrows the option having the name \bt_p{name} from the
3871 \bt_var_fc \bt_p{field_class} (\c const version).
3873 See bt_field_class_variant_borrow_option_by_name().
3875 extern const bt_field_class_variant_option
*
3876 bt_field_class_variant_borrow_option_by_name_const(
3877 const bt_field_class
*field_class
, const char *name
);
3882 @name Variant field class option
3887 @typedef struct bt_field_class_variant_option bt_field_class_variant_option;
3890 Variant field class option.
3895 Returns the name of the \bt_var_fc option \bt_p{option}.
3897 See the \ref api-tir-fc-var-prop-opts "options" property.
3900 Variant field class option of which to get the name.
3904 Name of \bt_p{option}.
3906 The returned pointer remains valid as long as \bt_p{option} exists.
3909 @bt_pre_not_null{option}
3911 extern const char *bt_field_class_variant_option_get_name(
3912 const bt_field_class_variant_option
*option
);
3916 Borrows the field class from the \bt_var_fc option
3919 See the \ref api-tir-fc-var-prop-opts "options" property.
3922 Variant field class option from which to borrow the field class.
3925 Field class of \bt_p{option}.
3927 @bt_pre_not_null{option}
3929 @sa bt_field_class_variant_option_borrow_field_class_const() —
3930 \c const version of this function.
3932 extern bt_field_class
*bt_field_class_variant_option_borrow_field_class(
3933 bt_field_class_variant_option
*option
);
3937 Borrows the field class from the \bt_var_fc option
3938 \bt_p{option} (\c const version).
3940 See bt_field_class_variant_option_borrow_field_class().
3942 extern const bt_field_class
*
3943 bt_field_class_variant_option_borrow_field_class_const(
3944 const bt_field_class_variant_option
*option
);
3948 Sets the user attributes of the \bt_var_fc option \bt_p{option}
3949 to \bt_p{user_attributes}.
3951 See the \ref api-tir-fc-var-prop-opts "options" property.
3954 When you append an option to a variant field class with
3955 bt_field_class_variant_without_selector_append_option(),
3956 bt_field_class_variant_with_selector_field_integer_unsigned_append_option(),
3958 bt_field_class_variant_with_selector_field_integer_signed_append_option(),
3959 the option's initial user attributes is an empty \bt_map_val.
3960 Therefore you can borrow it with
3961 bt_field_class_variant_option_borrow_user_attributes() and fill it
3962 directly instead of setting a new one with this function.
3965 Variant field class option of which to set the user attributes to
3966 \bt_p{user_attributes}.
3967 @param[in] user_attributes
3968 New user attributes of \bt_p{option}.
3970 @bt_pre_not_null{option}
3972 @bt_pre_not_null{user_attributes}
3973 @bt_pre_is_map_val{user_attributes}
3975 @sa bt_field_class_variant_option_borrow_user_attributes() —
3976 Borrows the user attributes of a variant field class option.
3978 extern void bt_field_class_variant_option_set_user_attributes(
3979 bt_field_class_variant_option
*option
,
3980 const bt_value
*user_attributes
);
3984 Borrows the user attributes of the \bt_var_fc option \bt_p{option}.
3986 See the \ref api-tir-fc-var-prop-opts "options" property.
3989 When you append an option to a variant field class with
3990 bt_field_class_variant_without_selector_append_option(),
3991 bt_field_class_variant_with_selector_field_integer_unsigned_append_option(),
3993 bt_field_class_variant_with_selector_field_integer_signed_append_option(),
3994 the option's initial user attributes is an empty \bt_map_val.
3997 Variant field class option from which to borrow the user
4001 User attributes of \bt_p{option} (a \bt_map_val).
4003 @bt_pre_not_null{option}
4005 @sa bt_field_class_variant_option_set_user_attributes() —
4006 Sets the user attributes of a variant field class option.
4007 @sa bt_field_class_variant_option_borrow_user_attributes_const() —
4008 \c const version of this function.
4010 extern bt_value
*bt_field_class_variant_option_borrow_user_attributes(
4011 bt_field_class_variant_option
*option
);
4015 Borrows the user attributes of the \bt_var_fc option \bt_p{option}
4018 See bt_field_class_variant_option_borrow_user_attributes().
4020 extern const bt_value
*bt_field_class_variant_option_borrow_user_attributes_const(
4021 const bt_field_class_variant_option
*option
);
4026 @name Variant field class without a selector field
4033 bt_field_class_variant_without_selector_append_option().
4035 typedef enum bt_field_class_variant_without_selector_append_option_status
{
4040 BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
4046 BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
4047 } bt_field_class_variant_without_selector_append_option_status
;
4051 Appends an option to the \bt_var_fc (without a selector field)
4052 \bt_p{field_class} having the name \bt_p{name} and the
4053 field class \bt_p{option_field_class}.
4055 See the \ref api-tir-fc-var-prop-opts "options" property.
4057 @param[in] field_class
4058 Variant field class to which to append an option having
4059 the name \bt_p{name} and the field class \bt_p{option_field_class}.
4061 Name of the option to append to \bt_p{field_class} (copied).
4062 @param[in] option_field_class
4063 Field class of the option to append to \bt_p{field_class}.
4065 @retval #BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
4067 @retval #BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
4070 @bt_pre_not_null{field_class}
4071 @bt_pre_hot{field_class}
4072 @bt_pre_is_var_wos_fc{field_class}
4074 \bt_p{field_class} has no option with the name \bt_p{name}.
4075 @bt_pre_not_null{name}
4076 @bt_pre_not_null{option_field_class}
4077 @bt_pre_fc_not_in_tc{option_field_class}
4079 @bt_post_success_frozen{option_field_class}
4081 extern bt_field_class_variant_without_selector_append_option_status
4082 bt_field_class_variant_without_selector_append_option(
4083 bt_field_class
*field_class
, const char *name
,
4084 bt_field_class
*option_field_class
);
4089 @name Variant field class with a selector field
4096 bt_field_class_variant_with_selector_field_integer_unsigned_append_option()
4098 bt_field_class_variant_with_selector_field_integer_signed_append_option().
4100 typedef enum bt_field_class_variant_with_selector_field_integer_append_option_status
{
4105 BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
4111 BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
4112 } bt_field_class_variant_with_selector_field_integer_append_option_status
;
4116 Borrows the selector field path from the \bt_var_fc (with a selector
4117 field) \bt_p{field_class}.
4119 See the \ref api-tir-fc-var-prop-sel-fp "selector field path" property.
4121 This property is only available when a \bt_struct_fc containing
4122 (recursively) \bt_p{field_class} is passed to one of:
4124 - bt_stream_class_set_packet_context_field_class()
4125 - bt_stream_class_set_event_common_context_field_class()
4126 - bt_event_class_set_specific_context_field_class()
4127 - bt_event_class_set_payload_field_class()
4129 In the meantime, this function returns \c NULL.
4131 @param[in] field_class
4132 Variant field class from which to borrow the selector field path.
4135 Selector field path of \bt_p{field_class}.
4137 @bt_pre_not_null{field_class}
4138 @bt_pre_is_var_ws_fc{field_class}
4140 extern const bt_field_path
*
4141 bt_field_class_variant_with_selector_field_borrow_selector_field_path_const(
4142 const bt_field_class
*field_class
);
4147 @name Variant field class with an unsigned integer selector field
4153 Appends an option to the \bt_var_fc (with an unsigned integer
4154 selector field) \bt_p{field_class} having the name \bt_p{name},
4155 the field class \bt_p{option_field_class}, and the
4156 \bt_p_uint_rg \bt_p{ranges}.
4158 See the \ref api-tir-fc-var-prop-opts "options" property.
4160 @param[in] field_class
4161 Variant field class to which to append an option having
4162 the name \bt_p{name}, the field class \bt_p{option_field_class},
4163 and the unsigned integer ranges \bt_p{ranges}.
4165 Name of the option to append to \bt_p{field_class} (copied).
4166 @param[in] option_field_class
4167 Field class of the option to append to \bt_p{field_class}.
4169 Unsigned integer ranges of the option to append to
4172 @retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
4174 @retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
4177 @bt_pre_not_null{field_class}
4178 @bt_pre_hot{field_class}
4179 @bt_pre_is_var_wuis_fc{field_class}
4181 \bt_p{field_class} has no option with the name \bt_p{name}.
4182 @bt_pre_not_null{name}
4183 @bt_pre_not_null{option_field_class}
4184 @bt_pre_fc_not_in_tc{option_field_class}
4185 @bt_pre_not_null{Ĺ—anges}
4187 \bt_p{ranges} contains one or more unsigned integer ranges.
4189 The unsigned integer ranges in \bt_p{ranges} do not overlap
4190 any unsigned integer range of any existing option in
4193 @bt_post_success_frozen{option_field_class}
4195 extern bt_field_class_variant_with_selector_field_integer_append_option_status
4196 bt_field_class_variant_with_selector_field_integer_unsigned_append_option(
4197 bt_field_class
*field_class
, const char *name
,
4198 bt_field_class
*option_field_class
,
4199 const bt_integer_range_set_unsigned
*ranges
);
4203 Borrows the option at index \bt_p{index} from the
4204 \bt_var_fc (with an unsigned integer selector field)
4207 See the \ref api-tir-fc-var-prop-opts "options" property.
4209 @param[in] field_class
4210 Variant field class from which to borrow the option at
4213 Index of the option to borrow from \bt_p{field_class}.
4217 \em Borrowed reference of the option of
4218 \bt_p{field_class} at index \bt_p{index}.
4220 The returned pointer remains valid as long as \bt_p{field_class}
4224 @bt_pre_not_null{field_class}
4225 @bt_pre_is_var_wuis_fc{field_class}
4227 \bt_p{index} is less than the number of options in
4228 \bt_p{field_class} (as returned by
4229 bt_field_class_variant_get_option_count()).
4231 @sa bt_field_class_variant_get_option_count() —
4232 Returns the number of options contained in a variant field class.
4234 extern const bt_field_class_variant_with_selector_field_integer_unsigned_option
*
4235 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(
4236 const bt_field_class
*field_class
, uint64_t index
);
4240 Borrows the option having the name \bt_p{name} from the
4241 \bt_var_fc (with an unsigned integer selector field)
4244 See the \ref api-tir-fc-var-prop-opts "options" property.
4246 If there's no option having the name \bt_p{name} in
4247 \bt_p{field_class}, this function returns \c NULL.
4249 @param[in] field_class
4250 Variant field class from which to borrow the option having the
4253 Name of the option to borrow from \bt_p{field_class}.
4257 \em Borrowed reference of the option of
4258 \bt_p{field_class} having the name \bt_p{name}, or \c NULL
4261 The returned pointer remains valid as long as \bt_p{field_class}
4265 @bt_pre_not_null{field_class}
4266 @bt_pre_is_var_wuis_fc{field_class}
4267 @bt_pre_not_null{name}
4269 @sa bt_field_class_variant_borrow_option_by_name_const() —
4270 Borrows an option by name from a variant field class.
4272 extern const bt_field_class_variant_with_selector_field_integer_unsigned_option
*
4273 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const(
4274 const bt_field_class
*field_class
, const char *name
);
4279 @name Variant field class (with an unsigned integer selector field) option
4284 @typedef struct bt_field_class_variant_with_selector_field_integer_unsigned_option bt_field_class_variant_with_selector_field_integer_unsigned_option;
4287 Variant field class (with an unsigned integer selector field) option.
4292 Borrows the \bt_p_uint_rg from the \bt_var_fc (with an unsigned
4293 integer selector field) option \bt_p{option}.
4295 See the \ref api-tir-fc-var-prop-opts "options" property.
4298 Variant field class option from which to borrow the
4299 unsigned integer ranges.
4302 Unsigned integer ranges of \bt_p{option}.
4304 @bt_pre_not_null{option}
4306 extern const bt_integer_range_set_unsigned
*
4307 bt_field_class_variant_with_selector_field_integer_unsigned_option_borrow_ranges_const(
4308 const bt_field_class_variant_with_selector_field_integer_unsigned_option
*option
);
4312 \ref api-fund-c-typing "Upcasts" the \bt_var_fc (with an
4313 unsigned integer selector field) option \bt_p{option} to the
4314 common #bt_field_class_variant_option type.
4316 See the \ref api-tir-fc-var-prop-opts "options" property.
4320 Variant field class option to upcast.
4326 \bt_p{option} as a common variant field class option.
4329 const bt_field_class_variant_option
*
4330 bt_field_class_variant_with_selector_field_integer_unsigned_option_as_option_const(
4331 const bt_field_class_variant_with_selector_field_integer_unsigned_option
*option
)
4333 return __BT_UPCAST_CONST(bt_field_class_variant_option
, option
);
4339 @name Variant field class with a signed integer selector field
4345 Appends an option to the \bt_var_fc (with a signed integer
4346 selector field) \bt_p{field_class} having the name \bt_p{name},
4347 the field class \bt_p{option_field_class}, and the
4348 \bt_p_sint_rg \bt_p{ranges}.
4350 See the \ref api-tir-fc-var-prop-opts "options" property.
4352 @param[in] field_class
4353 Variant field class to which to append an option having
4354 the name \bt_p{name} and the field class \bt_p{option_field_class},
4355 and the signed integer ranges \bt_p{ranges}.
4357 Name of the option to append to \bt_p{field_class} (copied).
4358 @param[in] option_field_class
4359 Field class of the option to append to \bt_p{field_class}.
4361 Signed integer ranges of the option to append to
4364 @retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
4366 @retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
4369 @bt_pre_not_null{field_class}
4370 @bt_pre_hot{field_class}
4371 @bt_pre_is_var_wsis_fc{field_class}
4373 \bt_p{field_class} has no option with the name \bt_p{name}.
4374 @bt_pre_not_null{name}
4375 @bt_pre_not_null{option_field_class}
4376 @bt_pre_fc_not_in_tc{option_field_class}
4377 @bt_pre_not_null{Ĺ—anges}
4379 \bt_p{ranges} contains one or more signed integer ranges.
4381 The signed integer ranges in \bt_p{ranges} do not overlap with
4382 any signed integer range of any existing option in
4385 @bt_post_success_frozen{option_field_class}
4387 extern bt_field_class_variant_with_selector_field_integer_append_option_status
4388 bt_field_class_variant_with_selector_field_integer_signed_append_option(
4389 bt_field_class
*field_class
, const char *name
,
4390 bt_field_class
*option_field_class
,
4391 const bt_integer_range_set_signed
*ranges
);
4395 Borrows the option at index \bt_p{index} from the
4396 \bt_var_fc (with a signed integer selector field)
4399 See the \ref api-tir-fc-var-prop-opts "options" property.
4401 @param[in] field_class
4402 Variant field class from which to borrow the option at
4405 Index of the option to borrow from \bt_p{field_class}.
4409 \em Borrowed reference of the option of
4410 \bt_p{field_class} at index \bt_p{index}.
4412 The returned pointer remains valid as long as \bt_p{field_class}
4416 @bt_pre_not_null{field_class}
4417 @bt_pre_is_var_wsis_fc{field_class}
4419 \bt_p{index} is less than the number of options in
4420 \bt_p{field_class} (as returned by
4421 bt_field_class_variant_get_option_count()).
4423 @sa bt_field_class_variant_get_option_count() —
4424 Returns the number of options contained in a variant field class.
4426 extern const bt_field_class_variant_with_selector_field_integer_signed_option
*
4427 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(
4428 const bt_field_class
*field_class
, uint64_t index
);
4432 Borrows the option having the name \bt_p{name} from the
4433 \bt_var_fc (with a signed integer selector field)
4436 See the \ref api-tir-fc-var-prop-opts "options" property.
4438 If there's no option having the name \bt_p{name} in
4439 \bt_p{field_class}, this function returns \c NULL.
4441 @param[in] field_class
4442 Variant field class from which to borrow the option having the
4445 Name of the option to borrow from \bt_p{field_class}.
4449 \em Borrowed reference of the option of
4450 \bt_p{field_class} having the name \bt_p{name}, or \c NULL
4453 The returned pointer remains valid as long as \bt_p{field_class}
4457 @bt_pre_not_null{field_class}
4458 @bt_pre_is_var_wsis_fc{field_class}
4459 @bt_pre_not_null{name}
4461 @sa bt_field_class_variant_borrow_option_by_name_const() —
4462 Borrows an option by name from a variant field class.
4464 extern const bt_field_class_variant_with_selector_field_integer_signed_option
*
4465 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const(
4466 const bt_field_class
*field_class
, const char *name
);
4471 @name Variant field class (with a signed integer selector field) option
4476 @typedef struct bt_field_class_variant_with_selector_field_integer_signed_option bt_field_class_variant_with_selector_field_integer_signed_option;
4479 Variant field class (with a signed integer selector field) option.
4484 Borrows the \bt_p_sint_rg from the \bt_var_fc (with a signed
4485 integer selector field) option \bt_p{option}.
4487 See the \ref api-tir-fc-var-prop-opts "options" property.
4490 Variant field class option from which to borrow the
4491 signed integer ranges.
4494 Signed integer ranges of \bt_p{option}.
4496 @bt_pre_not_null{option}
4498 extern const bt_integer_range_set_signed
*
4499 bt_field_class_variant_with_selector_field_integer_signed_option_borrow_ranges_const(
4500 const bt_field_class_variant_with_selector_field_integer_signed_option
*option
);
4504 \ref api-fund-c-typing "Upcasts" the \bt_var_fc (with a signed
4505 integer selector field) option \bt_p{option} to the
4506 common #bt_field_class_variant_option type.
4508 See the \ref api-tir-fc-var-prop-opts "options" property.
4512 Variant field class option to upcast.
4518 \bt_p{option} as a common variant field class option.
4521 const bt_field_class_variant_option
*
4522 bt_field_class_variant_with_selector_field_integer_signed_option_as_option_const(
4523 const bt_field_class_variant_with_selector_field_integer_signed_option
*option
)
4525 return __BT_UPCAST_CONST(bt_field_class_variant_option
, option
);
4531 @name Reference count
4537 Increments the \ref api-fund-shared-object "reference count" of
4538 the field class \bt_p{field_class}.
4540 @param[in] field_class
4542 Field class of which to increment the reference count.
4547 @sa bt_field_class_put_ref() —
4548 Decrements the reference count of a field class.
4550 extern void bt_field_class_get_ref(const bt_field_class
*field_class
);
4554 Decrements the \ref api-fund-shared-object "reference count" of
4555 the field class \bt_p{field_class}.
4557 @param[in] field_class
4559 Field class of which to decrement the reference count.
4564 @sa bt_field_class_get_ref() —
4565 Increments the reference count of a field class.
4567 extern void bt_field_class_put_ref(const bt_field_class
*field_class
);
4571 Decrements the reference count of the field class
4572 \bt_p{_field_class}, and then sets \bt_p{_field_class} to \c NULL.
4576 Field class of which to decrement the reference count.
4578 Can contain \c NULL.
4581 @bt_pre_assign_expr{_field_class}
4583 #define BT_FIELD_CLASS_PUT_REF_AND_RESET(_field_class) \
4585 bt_field_class_put_ref(_field_class); \
4586 (_field_class) = NULL; \
4591 Decrements the reference count of the field class \bt_p{_dst}, sets
4592 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
4594 This macro effectively moves a field class reference from the expression
4595 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
4596 \bt_p{_dst} reference.
4600 Destination expression.
4602 Can contain \c NULL.
4608 Can contain \c NULL.
4611 @bt_pre_assign_expr{_dst}
4612 @bt_pre_assign_expr{_src}
4614 #define BT_FIELD_CLASS_MOVE_REF(_dst, _src) \
4616 bt_field_class_put_ref(_dst); \
4629 #endif /* BABELTRACE2_TRACE_IR_FIELD_CLASS_H */