2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_TRACE_IR_FIELD_CLASS_H
8 #define BABELTRACE2_TRACE_IR_FIELD_CLASS_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
19 #include <babeltrace2/types.h>
26 @defgroup api-tir-fc Field classes
30 Classes of \bt_p_field.
32 <strong><em>Field classes</em></strong> are the classes of \bt_p_field:
34 @image html field-class-zoom.png
36 Field classes are \ref api-tir "trace IR" metadata objects.
38 There are many types of field classes. They can be divided into two main
44 Classes of fields which contain a simple value.
46 The scalar field classes are:
48 - \ref api-tir-fc-bool "Boolean"
49 - \ref api-tir-fc-ba "Bit array"
50 - \ref api-tir-fc-int "Integer" (unsigned and signed)
51 - \ref api-tir-fc-enum "Enumeration" (unsigned and signed)
52 - \ref api-tir-fc-real "Real" (single-precision and double-precision)
53 - \ref api-tir-fc-string "String"
54 - \ref api-tir-fc-blob "BLOB" (static and dynamic)
59 Classes of fields which contain other fields.
61 The container field classes are:
63 - \ref api-tir-fc-array "Array" (static and dynamic)
64 - \ref api-tir-fc-struct "Structure"
65 - \ref api-tir-fc-opt "Option"
66 - \ref api-tir-fc-var "Variant"
70 @image html fc-to-field.png "Fields (green) are instances of field classes (orange)."
72 Some field classes conceptually inherit other field classes, eventually
73 making an inheritance hierarchy. For example, a \bt_sarray_fc
74 \em is an array field class. Therefore, a static array field class has
75 any property that an array field class has.
77 The complete field class inheritance hierarchy is:
79 @image html all-field-classes.png
81 In the illustration above:
83 - You can create any field class with a dark background with
84 a dedicated <code>bt_field_class_*_create()</code> function.
86 - A field class with a pale background is an \em abstract field class:
87 you cannot create it, but it has properties, therefore there are
88 functions which apply to it.
90 For example, bt_field_class_integer_set_preferred_display_base()
91 applies to any \bt_int_fc.
93 Field classes are \ref api-fund-shared-object "shared objects": get a
94 new reference with bt_field_class_get_ref() and put an existing
95 reference with bt_field_class_put_ref().
97 Some library functions \ref api-fund-freezing "freeze" field classes on
98 success. The documentation of those functions indicate this
101 All the field class types share the same C type, #bt_field_class.
103 Get the type enumerator of a field class with bt_field_class_get_type().
104 Get whether or not a field class type conceptually \em is a given type
105 with the inline bt_field_class_type_is() function.
107 The following table shows the available type enumerators and creation
108 functions for each type of \em concrete (non-abstract) field class:
114 <th>Creation function(s)
116 <td><em>\ref api-tir-fc-bool "Boolean"</em>
117 <td>#BT_FIELD_CLASS_TYPE_BOOL
118 <td>bt_field_class_bool_create()
120 <td><em>\ref api-tir-fc-ba "Bit array"</em>
121 <td>#BT_FIELD_CLASS_TYPE_BIT_ARRAY
122 <td>bt_field_class_bit_array_create()
124 <td><em>Unsigned \ref api-tir-fc-int "integer"</em>
125 <td>#BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER
126 <td>bt_field_class_integer_unsigned_create()
128 <td><em>Signed \ref api-tir-fc-int "integer"</em>
129 <td>#BT_FIELD_CLASS_TYPE_SIGNED_INTEGER
130 <td>bt_field_class_integer_signed_create()
132 <td><em>Unsigned \ref api-tir-fc-enum "enumeration"</em>
133 <td>#BT_FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION
134 <td>bt_field_class_enumeration_unsigned_create()
136 <td><em>Signed \ref api-tir-fc-enum "enumeration"</em>
137 <td>#BT_FIELD_CLASS_TYPE_SIGNED_ENUMERATION
138 <td>bt_field_class_enumeration_signed_create()
140 <td><em>Single-precision \ref api-tir-fc-real "real"</em>
141 <td>#BT_FIELD_CLASS_TYPE_SINGLE_PRECISION_REAL
142 <td>bt_field_class_real_single_precision_create()
144 <td><em>Double-precision \ref api-tir-fc-real "real"</em>
145 <td>#BT_FIELD_CLASS_TYPE_DOUBLE_PRECISION_REAL
146 <td>bt_field_class_real_double_precision_create()
148 <td><em>\ref api-tir-fc-string "String"</em>
149 <td>#BT_FIELD_CLASS_TYPE_STRING
150 <td>bt_field_class_string_create()
152 <td><em>Static \ref api-tir-fc-blob "BLOB"</em>
153 <td>#BT_FIELD_CLASS_TYPE_STATIC_BLOB
154 <td>bt_field_class_blob_static_create()
157 <em>Dynamic \ref api-tir-fc-blob "BLOB"
158 (instances without a linked length field)</em>
159 <td>#BT_FIELD_CLASS_TYPE_DYNAMIC_BLOB_WITHOUT_LENGTH_FIELD
160 <td>bt_field_class_blob_dynamic_without_length_field_location_create()
163 <em>Dynamic \ref api-tir-fc-blob "BLOB"
164 (instances with a linked length field)</em>
165 <td>#BT_FIELD_CLASS_TYPE_DYNAMIC_BLOB_WITH_LENGTH_FIELD
166 <td>bt_field_class_blob_dynamic_with_length_field_location_create()
168 <td><em>Static \ref api-tir-fc-array "array"</em>
169 <td>#BT_FIELD_CLASS_TYPE_STATIC_ARRAY
170 <td>bt_field_class_array_static_create()
173 <em>Dynamic \ref api-tir-fc-array "array"
174 (instances without a linked length field)</em>
175 <td>#BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD
177 - bt_field_class_array_dynamic_create()
178 - bt_field_class_array_dynamic_without_length_field_location_create()
181 <em>Dynamic \ref api-tir-fc-array "array"
182 (instances with a linked length field)</em>
183 <td>#BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD
185 - bt_field_class_array_dynamic_create()
186 - bt_field_class_array_dynamic_with_length_field_location_create()
188 <td><em>\ref api-tir-fc-struct "Structure"</em>
189 <td>#BT_FIELD_CLASS_TYPE_STRUCTURE
190 <td>bt_field_class_structure_create()
193 <em>\ref api-tir-fc-opt "Option"
194 (instances without a linked selector field)</em>
195 <td>#BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD
197 - bt_field_class_option_without_selector_create()
198 - bt_field_class_option_without_selector_field_location_create()
201 <em>\ref api-tir-fc-opt "Option"
202 (instances with a linked boolean selector field)</em>
203 <td>#BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD
205 - bt_field_class_option_with_selector_field_bool_create()
206 - bt_field_class_option_with_selector_field_location_bool_create()
209 <em>\ref api-tir-fc-opt "Option"
210 (instances with a linked unsigned integer selector field)</em>
211 <td>#BT_FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
213 - bt_field_class_option_with_selector_field_integer_unsigned_create()
214 - bt_field_class_option_with_selector_field_location_integer_unsigned_create()
217 <em>\ref api-tir-fc-opt "Option"
218 (instances with a linked signed integer selector field)</em>
219 <td>#BT_FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD
221 - bt_field_class_option_with_selector_field_integer_signed_create()
222 - bt_field_class_option_with_selector_field_location_integer_signed_create()
225 <em>\ref api-tir-fc-var "Variant"
226 (instances without a linked selector field)</em>
227 <td>#BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD
229 - bt_field_class_variant_create()
230 - bt_field_class_variant_without_selector_field_location_create()
233 <em>\ref api-tir-fc-var "Variant"
234 (instances with a linked unsigned integer selector field)</em>
235 <td>#BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
237 - bt_field_class_variant_create()
238 - bt_field_class_variant_with_selector_field_location_integer_unsigned_create()
241 <em>\ref api-tir-fc-var "Variant"
242 (instances with a linked signed integer selector field)</em>
243 <td>#BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD
245 - bt_field_class_variant_create()
246 - bt_field_class_variant_with_selector_field_location_integer_signed_create()
249 You need a \bt_trace_cls to create a field class: create one from a
250 \bt_self_comp with bt_trace_class_create().
252 Outside the field class API, you can use field classes at four
253 locations, called <em>scopes</em>, within the trace IR API:
255 - To set the packet context field class of a \bt_stream_cls with
256 bt_stream_class_set_packet_context_field_class().
258 - To set the event common context field class of a stream class with
259 bt_stream_class_set_event_common_context_field_class().
261 - To set the specific context field class of an \bt_ev_cls with
262 bt_event_class_set_specific_context_field_class().
264 - To set the payload field class of an event class with
265 bt_event_class_set_payload_field_class().
267 When you call one of the four functions above:
269 - The passed field class must be a \bt_struct_fc.
271 - You must \em not have already called any of the four functions above
272 with the passed field class or with any of its contained field
275 - If an instance of any of the field classes recursively contained in
276 the passed field class has a
277 \ref api-tir-fc-link "link to an anterior field", it must
278 honor the field link rules.
280 Once you have called one of the four functions above, the passed field
281 class becomes \ref api-fund-freezing "frozen".
283 <h1>Common field class property</h1>
285 A field class has the following common property:
289 \anchor api-tir-fc-prop-user-attrs
290 \bt_dt_opt User attributes
293 User attributes of the field class.
295 User attributes are custom attributes attached to a field class.
297 Use bt_field_class_set_user_attributes(),
298 bt_field_class_borrow_user_attributes(), and
299 bt_field_class_borrow_user_attributes_const().
303 <h1>\anchor api-tir-fc-bool Boolean field class</h1>
305 @image html fc-bool.png
307 A <strong><em>boolean field class</em></strong> is the class
310 A boolean field contains a boolean value (#BT_TRUE or #BT_FALSE).
312 Create a boolean field class with bt_field_class_bool_create().
314 A boolean field class has no specific properties.
316 <h1>\anchor api-tir-fc-ba Bit array field class</h1>
318 @image html fc-ba.png
320 A <strong><em>bit array field class</em></strong> is the class
323 A bit array field contains a fixed-length array of bits.
325 Create a bit array field class with bt_field_class_bit_array_create().
327 A bit array field class has the following property:
331 \anchor api-tir-fc-ba-prop-len
335 Number of bits contained in the instances (bit array fields) of
336 the bit array field class.
338 As of \bt_name_version_min_maj, the maximum length of a bit array
341 You cannot change the length once the bit array field class is
344 Get a bit array field class's length with
345 bt_field_class_bit_array_get_length().
349 \anchor api-tir-fc-ba-prop-flags
351 (only available when the field class was created from a
352 \bt_trace_cls which was created
353 from a \bt_comp which belongs to a trace processing \bt_graph
354 with the effective \bt_mip version 1)
357 Set of flags of the bit array field class.
359 A bit array field class flag is a label (string) and an
360 \bt_uint_rs, a set of bit index ranges. In the value of an
361 instance (a \bt_ba_field) returned by
362 bt_field_bit_array_get_value_as_integer(), the least significant
363 bit's index is 0.
365 The integer ranges of a given flag or of multiple flags of
366 the same bit array field class can overlap. For example,
367 a bit array field class can have those two flags:
369 - <code>GALLERY</code>: [1, 4], [8, 14]
370 - <code>LUNCH</code>: [3, 6]
372 In that case, the bit indexes 2 and 12 correspond to the
373 label <code>GALLERY</code>, the bit index 5 to the label
374 <code>LUNCH</code>, and the bit index 3 to the labels
375 \c GALLERY \em and <code>LUNCH</code>.
377 Given some bit flag field value (as an integer), a flag is said to
378 be <strong><em>active</em></strong> when <em>at least one</em> of
379 its bit indexes is the index of a set bit of the value. For example,
380 given the 8-bit bit array field value
383 [true, false, true, true, false, true, false, true]
386 where the first element is the first bit of the bit array field (the
387 value as an integer being 0xad):
389 - A flag targeting bits 1, 3, and 6 would be active because
392 - A flag targeting bits 1 and 4 wouldn't be active because both
395 Two flags of the same bit array field class cannot have the
398 Add a flag to a bit array field class with
399 bt_field_class_bit_array_add_flag().
401 Get the number of flags in a bit array field class with
402 bt_field_class_bit_array_get_flag_count().
404 Borrow a flag from a bit array field class with
405 bt_field_class_bit_array_borrow_flag_by_index_const()
407 bt_field_class_bit_array_borrow_flag_by_label_const().
409 A bit array field class flag is a
410 \ref api-fund-unique-object "unique object": it
411 belongs to the bit array field class which contains it.
413 The type of a bit array field class flag is
414 #bt_field_class_bit_array_flag.
416 Get the label of a bit array field class flag with
417 bt_field_class_bit_array_flag_get_label().
419 Borrow the bit index range set of a bit array field class flag
420 with bt_field_class_bit_array_flag_borrow_index_ranges_const().
422 Get the labels of all the active flags of a bit array field class
423 for the set bits of some integral value with
424 bt_field_class_bit_array_get_active_flag_labels_for_value_as_integer().
428 <h1>\anchor api-tir-fc-int Integer field classes</h1>
430 @image html fc-int.png
432 <strong><em>Integer field classes</em></strong> are classes
435 Integer fields contain integral values.
437 An integer field class is an \em abstract field class: you cannot create
438 one. The concrete integer field classes are:
441 <dt>Unsigned integer field class</dt>
443 Its instances (unsigned integer fields) contain an unsigned integral
446 Create with bt_field_class_integer_unsigned_create().
449 <dt>Signed integer field class</dt>
451 Its instances (signed integer fields) contain a signed integral
454 Create with bt_field_class_integer_signed_create().
458 Integer field classes have the following common properties:
462 \anchor api-tir-fc-int-prop-size
466 Expected range of values that the instances (integer fields)
467 of the integer field class can contain.
469 For example, if the field value range of an unsigned integer
470 field class is [0, 16383], then its unsigned integer fields
471 can only contain the values from 0 to 16383.
473 \bt_cp_sink_comp can benefit from this property to make some space
474 optimizations when writing trace data.
476 Use bt_field_class_integer_set_field_value_range() and
477 bt_field_class_integer_get_field_value_range().
481 \anchor api-tir-fc-int-prop-base
482 Preferred display base
485 Preferred base (2, 8, 10, or 16) to use when displaying the
486 instances (integer fields) of the integer field class.
488 Use bt_field_class_integer_set_preferred_display_base() and
489 bt_field_class_integer_get_preferred_display_base().
493 <h2>\anchor api-tir-fc-enum Enumeration field classes</h2>
495 @image html fc-enum.png
497 <strong><em>Enumeration field classes</em></strong> are classes
500 Enumeration field classes \em are \bt_p_int_fc: they have the integer
501 field classes properties.
503 Enumeration fields \em are integer fields: they contain integral values.
505 Enumeration field classes associate labels (strings) to specific
506 ranges of integral values. This association is called an enumeration
507 field class <em>mapping</em>.
509 For example, if an enumeration field class maps the label \c SUGAR to
510 the integer ranges [1, 19] and [25, 31], then an instance
511 (enumeration field) of this field class with the value 15 or 28 has the
512 label <code>SUGAR</code>.
514 An enumeration field class is an \em abstract field class: you cannot
515 create one. The concrete enumeration field classes are:
518 <dt>Unsigned enumeration field class</dt>
520 Its instances (unsigned enumeration fields) contain an unsigned
523 Create with bt_field_class_enumeration_unsigned_create().
526 <dt>Signed enumeration field class</dt>
528 Its instances (signed enumeration fields) contain a signed value
531 Create with bt_field_class_enumeration_signed_create().
535 Enumeration field classes have the following common property:
539 \anchor api-tir-fc-enum-prop-mappings
543 Set of mappings of the enumeration field class.
545 An enumeration field class mapping is a label (string) and an
548 The integer ranges of a given mapping or of multiple mappings of
549 the same enumeration field class can overlap. For example,
550 an enumeration field class can have those two mappings:
552 - <code>CALORIES</code>: [1, 11], [15, 37]
553 - <code>SODIUM</code>: [7, 13]
555 In that case, the values 2 and 30 correspond to the label
556 <code>CALORIES</code>, the value 12 to the label
557 <code>SODIUM</code>, and the value 10 to the labels
558 \c CALORIES \em and <code>SODIUM</code>.
560 Two mappings of the same enumeration field class cannot have the
563 Add a mapping to an enumeration field class with
564 bt_field_class_enumeration_unsigned_add_mapping() or
565 bt_field_class_enumeration_signed_add_mapping().
567 Get the number of mappings in an enumeration field class with
568 bt_field_class_enumeration_get_mapping_count().
570 Borrow a mapping from an enumeration field class with
571 bt_field_class_enumeration_unsigned_borrow_mapping_by_index_const(),
572 bt_field_class_enumeration_signed_borrow_mapping_by_index_const(),
573 bt_field_class_enumeration_unsigned_borrow_mapping_by_label_const(),
575 bt_field_class_enumeration_signed_borrow_mapping_by_label_const().
577 An enumeration field class mapping is a
578 \ref api-fund-unique-object "unique object": it
579 belongs to the enumeration field class which contains it.
581 There are two enumeration field class mapping types, depending on
582 the field class's type:
583 #bt_field_class_enumeration_unsigned_mapping and
584 #bt_field_class_enumeration_signed_mapping.
586 There is also the #bt_field_class_enumeration_mapping type for
587 common properties and operations (for example,
588 bt_field_class_enumeration_mapping_get_label()).
589 \ref api-fund-c-typing "Upcast" a specific enumeration field class
590 mapping to the #bt_field_class_enumeration_mapping type with
591 bt_field_class_enumeration_unsigned_mapping_as_mapping_const() or
592 bt_field_class_enumeration_signed_mapping_as_mapping_const().
594 Get all the enumeration field class labels mapped to a given integer
596 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value()
598 bt_field_class_enumeration_signed_get_mapping_labels_for_value().
602 <h1>\anchor api-tir-fc-real Real field classes</h1>
604 @image html fc-real.png
606 <strong><em>Real field classes</em></strong> are classes
610 <a href="https://en.wikipedia.org/wiki/Real_number">real</a>
611 values (\c float or \c double types).
613 A real field class is an \em abstract field class: you cannot create
614 one. The concrete real field classes are:
617 <dt>Single-precision real field class</dt>
619 Its instances (single-precision real fields) contain a \c float
622 Create with bt_field_class_real_single_precision_create().
625 <dt>Double-precision real field class</dt>
627 Its instances (double-precision real fields) contain a \c double
630 Create with bt_field_class_real_double_precision_create().
634 Real field classes have no specific properties.
636 <h1>\anchor api-tir-fc-string String field class</h1>
638 @image html fc-string.png
640 A <strong><em>string field class</em></strong> is the class
641 of \bt_p_string_field.
643 A string field contains an UTF-8 string value.
645 Create a string field class with bt_field_class_string_create().
647 A string field class has no specific properties.
649 <h1>\anchor api-tir-fc-blob BLOB field classes</h1>
651 @image html fc-blob.png
653 <strong><em>BLOB field classes</em></strong> are
654 classes of \bt_p_blob_field.
656 BLOB fields contain zero or more bytes of binary data.
659 BLOB field classes are only available when the \bt_trace_cls from
660 which you create them was created from a \bt_comp which belongs
661 to a trace processing \bt_graph with the effective \bt_mip
664 A BLOB field class is an \em abstract field class: you cannot create
665 one. The concrete BLOB field classes are:
668 <dt>Static BLOB field class</dt>
670 Its instances (static BLOB fields) contain a fixed number of bytes.
672 Create with bt_field_class_blob_static_create().
674 A static BLOB field class has the following specific property:
678 \anchor api-tir-fc-sblob-prop-len
682 Number of bytes contained in the instances (static BLOB
683 fields) of the static BLOB field class.
685 You cannot change the length once the static BLOB field class is
688 Get a static BLOB field class's length with
689 bt_field_class_blob_static_get_length().
694 <dt>Dynamic BLOB field class</dt>
696 Its instances (dynamic BLOB fields) contain a variable number
699 There are two types of dynamic BLOB field classes: instances
700 without or with a linked length field. See
701 \ref api-tir-fc-link "Fields with links to other fields"
704 @image html dblob-link.png "A dynamic blob field linked to an unsigned integer length field."
707 bt_field_class_blob_dynamic_without_length_field_location_create()
708 or bt_field_class_blob_dynamic_with_length_field_location_create().
710 The class of a dynamic BLOB field with a linked length field has
711 the following specific property:
715 \anchor api-tir-fc-dblob-prop-len-fl
716 Length field location
719 \bt_c_field_loc to locate the linked length field of an
722 Get a dynamic BLOB field class's length field location with
723 bt_field_class_blob_dynamic_with_length_field_borrow_length_field_location_const().
729 BLOB field classes have the following common property:
733 \anchor api-tir-fc-blob-prop-media-type
737 <a href="https://datatracker.ietf.org/doc/html/rfc2046">IANA media type</a>
738 of instances of the BLOB field class.
740 Use bt_field_class_blob_set_media_type() and
741 bt_field_class_blob_get_media_type().
745 <h1>\anchor api-tir-fc-array Array field classes</h1>
747 @image html fc-array.png
749 <strong><em>Array field classes</em></strong> are classes
750 of \bt_p_array_field.
752 Array fields contain zero or more fields which have the same class.
754 An array field class is an \em abstract field class: you cannot create
755 one. The concrete array field classes are:
758 <dt>Static array field class</dt>
760 Its instances (static array fields) contain a fixed number of
763 Create with bt_field_class_array_static_create().
765 A static array field class has the following specific property:
769 \anchor api-tir-fc-sarray-prop-len
773 Number of fields contained in the instances (static array
774 fields) of the static array field class.
776 You cannot change the length once the static array field class
779 Get a static array field class's length with
780 bt_field_class_array_static_get_length().
785 <dt>Dynamic array field class</dt>
787 Its instances (dynamic array fields) contain a variable number
790 There are two types of dynamic array field classes: instances
791 without or with a linked length field. See
792 \ref api-tir-fc-link "Fields with links to other fields"
795 @image html darray-link.png "A dynamic array field linked to an unsigned integer length field."
797 Create with, depending on the effective \bt_mip (MIP) version of the
798 trace processing \bt_graph:
802 <dd>bt_field_class_array_dynamic_create().</dt>
806 bt_field_class_array_dynamic_without_length_field_location_create()
808 bt_field_class_array_dynamic_with_length_field_location_create().
812 The class of a dynamic array field with a linked length field has
813 one of the following specific properties, depending on the
814 effective MIP version of the trace processing graph:
818 \anchor api-tir-fc-darray-prop-len-fp
819 MIP 0: Length field path
822 \bt_c_field_path to locate the linked length field of
825 Borrow a dynamic array field class's length field path with
826 bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const().
830 \anchor api-tir-fc-darray-prop-len-fl
831 MIP 1: Length field location
834 \bt_c_field_loc to locate the linked length field of an
837 Borrow a dynamic array field class's length field location with
838 bt_field_class_array_dynamic_with_length_field_borrow_length_field_location_const().
844 Array field classes have the following common property:
848 \anchor api-tir-fc-array-prop-elem-fc
852 Class of the fields contained in the instances (array fields) of the
855 You cannot change the element field class once the array field class
858 Borrow an array field class's element field class with
859 bt_field_class_array_borrow_element_field_class() and
860 bt_field_class_array_borrow_element_field_class_const().
864 <h1>\anchor api-tir-fc-struct Structure field class</h1>
866 @image html fc-struct.png
868 A <strong><em>structure field class</em></strong> is the class
869 of a \bt_struct_field.
871 A structure field contains an ordered list of zero or more members. Each
872 structure field member is the instance of a structure field class
873 member. A structure field class member has a name, a field class,
876 Create a structure field class with bt_field_class_structure_create().
878 A structure field class has the following specific property:
882 \anchor api-tir-fc-struct-prop-members
886 Ordered list of members (zero or more) of the structure field class.
890 - A name, unique amongst all the member names of the same
891 structure field class.
895 The instances (structure fields) of a structure field class have
896 members which are instances of the corresponding structure field
899 Append a member to a structure field class with
900 bt_field_class_structure_append_member().
902 Borrow a member from a structure field class with
903 bt_field_class_structure_borrow_member_by_index(),
904 bt_field_class_structure_borrow_member_by_name(),
905 bt_field_class_structure_borrow_member_by_index_const(), and
906 bt_field_class_structure_borrow_member_by_name_const().
908 A structure field class member is a
909 \ref api-fund-unique-object "unique object": it
910 belongs to the structure field class which contains it.
912 The type of a structure field class member is
913 #bt_field_class_structure_member.
915 Get a structure field class member's name with
916 bt_field_class_structure_member_get_name().
918 Borrow a structure field class member's field class with
919 bt_field_class_structure_member_borrow_field_class() and
920 bt_field_class_structure_member_borrow_field_class_const().
922 Set a structure field class member's user attributes with
923 bt_field_class_structure_member_set_user_attributes().
925 Borrow a structure field class member's user attributes with
926 bt_field_class_structure_member_borrow_user_attributes() and
927 bt_field_class_structure_member_borrow_user_attributes_const().
931 <h1>\anchor api-tir-fc-opt Option field classes</h1>
933 @image html fc-opt.png
935 <strong><em>Option field classes</em></strong> are classes
938 An option field either does or doesn't \em contain a field, called its
941 An option field class is an \em abstract field class: you cannot create
942 one. An instance of an option field class either has a linked selector
943 field (see \ref api-tir-fc-link "Fields with links to other fields")
944 or none. Therefore, the concrete option field classes are:
947 <dt>Option field class (instances without a linked selector field)</dt>
949 Create with, depending on the effective \bt_mip (MIP) version
950 of the trace processing \bt_graph:
954 <dd>bt_field_class_option_without_selector_create()</dt>
957 <dd>bt_field_class_option_without_selector_field_location_create()</dd>
960 The class of an option field without a linked selector field has no
964 <dt>Option field class (instances with a linked boolean selector field)</dt>
966 The linked selector field of an option field class's instance
967 (an option field) is a \bt_bool_field.
969 @image html opt-link.png "Option field class with a boolean selector field."
971 Create with, depending on the effective \bt_mip (MIP) version:
975 <dd>bt_field_class_option_with_selector_field_bool_create()</dt>
978 <dd>bt_field_class_option_with_selector_field_location_bool_create()</dd>
981 The class of an option field with a linked boolean selector field
982 has the following specific property:
986 \anchor api-tir-fc-opt-prop-sel-rev
987 Selector is reversed?
990 Whether or not the linked boolean selector field make the
991 option field class's instance (an option field) \em contain a
992 field when it's #BT_TRUE or when it's #BT_FALSE.
994 If this property is #BT_TRUE, then if the linked selector field
995 has the value #BT_FALSE, the option field contains a field.
998 bt_field_class_option_with_selector_field_bool_set_selector_is_reversed()
1000 bt_field_class_option_with_selector_field_bool_selector_is_reversed().
1005 <dt>Option field class (instances with a linked unsigned integer selector field)</dt>
1007 The linked selector field of an option field class's instance
1008 (an option field) is an \bt_uint_field.
1010 Create with, depending on the effective \bt_mip (MIP) version
1011 of the trace processing \bt_graph:
1015 <dd>bt_field_class_option_with_selector_field_integer_unsigned_create()</dt>
1018 <dd>bt_field_class_option_with_selector_field_location_integer_unsigned_create()</dd>
1021 Pass an \bt_uint_rs on creation to set which values of the selector
1022 field can make the option field contain a field.
1024 The class of an option field with a linked unsigned integer selector
1025 field has the following specific property:
1029 \anchor api-tir-fc-opt-prop-uint-rs
1030 Selector's unsigned integer ranges
1033 If the linked unsigned integer selector field of an option
1034 field class's instance (an option field) has a value which
1035 intersects with the selector's unsigned integer ranges, then
1036 the option field \em contains a field.
1038 You cannot change the selector's unsigned integer ranges once
1039 the option field class is created.
1041 Borrow the selector's unsigned integer ranges from such an
1042 option field class with
1043 bt_field_class_option_with_selector_field_integer_unsigned_borrow_selector_ranges_const().
1048 <dt>Option field class (instances with a linked signed integer selector field)</dt>
1050 The linked selector field of an option field class's instance
1051 (an option field) is a \bt_sint_field.
1053 Create with, depending on the effective \bt_mip (MIP) version of
1054 the trace processing \bt_graph:
1058 <dd>bt_field_class_option_with_selector_field_integer_signed_create()</dt>
1061 <dd>bt_field_class_option_with_selector_field_location_integer_signed_create()</dd>
1064 Pass a \bt_sint_rs on creation to set which values of the selector
1065 field can make the option field contain a field.
1067 The class of an option field class with a linked signed integer
1068 selector field has the following specific property:
1072 \anchor api-tir-fc-opt-prop-sint-rs
1073 Selector's signed integer ranges
1076 If the linked signed integer selector field of an option
1077 field class's instance (an option field) has a value which
1078 intersects with the selector's signed integer ranges, then
1079 the option field \em contains a field.
1081 You cannot change the selector's signed integer ranges once
1082 the option field class is created.
1084 Borrow the selector's signed integer ranges from such an
1085 option field class with
1086 bt_field_class_option_with_selector_field_integer_signed_borrow_selector_ranges_const().
1092 The classes of option fields with a linked selector field have one of
1093 the following common properties, depending on the effective
1094 \bt_mip (MIP) version of the trace processing \bt_graph:
1098 \anchor api-tir-fc-opt-prop-sel-fp
1099 MIP 0: Selector field path
1102 \bt_c_field_path to locate the linked selector field of an instance.
1104 Borrow such an option field class's selector field path with
1105 bt_field_class_option_with_selector_field_borrow_selector_field_path_const().
1109 \anchor api-tir-fc-opt-prop-sel-fl
1110 MIP 1: Selector field location
1113 \bt_c_field_loc to locate the linked selector field of an instance.
1115 Borrow such an option field class's selector field location with
1116 bt_field_class_option_with_selector_field_borrow_selector_field_location_const().
1120 Option field classes have the following common property:
1124 \anchor api-tir-fc-opt-prop-fc
1125 Optional field class
1128 Class of the optional field of an instance (option field) of the
1131 You cannot change the optional field class once the option field
1134 Borrow an option field class's optional field class with
1135 bt_field_class_option_borrow_field_class() and
1136 bt_field_class_option_borrow_field_class_const().
1140 <h1>\anchor api-tir-fc-var Variant field classes</h1>
1142 @image html fc-var.png
1144 <strong><em>Variant field classes</em></strong> are classes
1147 A variant field contains a field amongst one or more possible fields.
1149 Variant field classes contain one or more options. Each variant field
1150 class option has a name, a field class, user attributes, and integer
1151 ranges, depending on the exact type.
1153 A variant field class is an \em abstract field class: you cannot create
1154 one. An instance of a variant field class either has a linked selector
1155 field (see \ref api-tir-fc-link "Fields with links to other fields")
1156 or none. Therefore, the concrete variant field classes are:
1159 <dt>Variant field class (instances without a linked selector field)</dt>
1161 Create with, depending on the effective \bt_mip (MIP) version
1162 of the trace processing \bt_graph:
1167 bt_field_class_variant_create(), passing \c NULL as
1168 the selector field class.
1172 <dd>bt_field_class_variant_without_selector_field_location_create().</dd>
1175 Append an option to such a variant field class with
1176 bt_field_class_variant_without_selector_append_option().
1178 The class of a variant field without a linked selector field has no
1179 specific properties.
1182 <dt>Variant field class (instances with a linked unsigned selector field)</dt>
1184 The linked selector field of a variant field class's instance
1185 (a variant field) is an \bt_uint_field.
1187 @image html var-link.png "A variant field linked to an unsigned integer selector field."
1189 Create with, depending on the effective \bt_mip (MIP) version of the
1190 trace processing \bt_graph:
1195 bt_field_class_variant_create(), passing an unsigned integer
1196 field class as the selector field class.
1200 <dd>bt_field_class_variant_with_selector_field_location_integer_unsigned_create().</dd>
1203 Append an option to such a variant field class with
1204 bt_field_class_variant_with_selector_field_integer_unsigned_append_option().
1206 Pass an \bt_uint_rs when you append an option to set which values of
1207 the selector field can make the variant field have a given
1210 Borrow such a variant field class's option with
1211 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const()
1213 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const().
1216 <dt>Variant field class (instances with a linked signed selector field)</dt>
1218 The linked selector field of a variant field class's instance
1219 (a variant field) is a \bt_sint_field.
1221 Create with, depending on the effective \bt_mip (MIP) version of the
1222 trace processing \bt_graph:
1227 bt_field_class_variant_create(), passing an signed integer
1228 field class as the selector field class.
1232 <dd>bt_field_class_variant_with_selector_field_location_integer_signed_create().</dd>
1235 Append an option to such a variant field class with
1236 bt_field_class_variant_with_selector_field_integer_signed_append_option().
1238 Pass a \bt_sint_rs when you append an option to set which values of
1239 the selector field can make the variant field have a given
1242 Borrow such a variant field class's option with
1243 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const()
1245 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const().
1249 The classes of variant fields with a linked selector field have one of
1250 the following common properties, depending on the effective
1251 \bt_mip (MIP) version of the trace processing \bt_graph:
1255 \anchor api-tir-fc-var-prop-sel-fp
1256 MIP 0: Selector field path
1259 \bt_c_field_path to locate the linked selector field of an instance.
1261 Borrow such a variant field class's selector field path with
1262 bt_field_class_variant_with_selector_field_borrow_selector_field_path_const().
1266 \anchor api-tir-fc-var-prop-sel-fl
1267 MIP 1: Selector field location
1270 \bt_c_field_loc to locate the linked selector field of an instance.
1272 Borrow such a variant field class's selector field location with
1273 bt_field_class_variant_with_selector_field_borrow_selector_field_location_const().
1277 Variant field classes have the following common property:
1281 \anchor api-tir-fc-var-prop-opts
1285 Options of the variant field class.
1289 - A name, unique amongst all the option names of the same
1290 variant field class.
1292 The name is optional when the effective \bt_mip version of the
1293 trace processing \bt_graph is 1.
1299 If an instance of the variant field class is linked to a selector
1300 field, then each option also has an \bt_int_rs. In that case, the
1301 ranges of a given option cannot overlap any range of any other
1304 A variant field class must contain at least one option.
1306 Depending on whether or not an instance of the variant field class
1307 has a linked selector field, append an option to a variant field
1308 class with bt_field_class_variant_without_selector_append_option(),
1309 bt_field_class_variant_with_selector_field_integer_unsigned_append_option(),
1311 bt_field_class_variant_with_selector_field_integer_signed_append_option().
1313 Get the number of options contained in a variant field class
1314 with bt_field_class_variant_get_option_count().
1316 A variant field class option is a
1317 \ref api-fund-unique-object "unique object": it
1318 belongs to the variant field class which contains it.
1320 Borrow any variant field class's option with
1321 bt_field_class_variant_borrow_option_by_index(),
1322 bt_field_class_variant_borrow_option_by_name(),
1323 bt_field_class_variant_borrow_option_by_index_const(), and
1324 bt_field_class_variant_borrow_option_by_name_const().
1326 Those functions return the common #bt_field_class_variant_option
1327 type. Get the name of a variant field class option with
1328 bt_field_class_variant_option_get_name(). Borrow a variant field
1329 class option's field class with
1330 bt_field_class_variant_option_borrow_field_class() and
1331 bt_field_class_variant_option_borrow_field_class_const().
1333 Borrow the option of the class of a variant field with a linked
1335 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(),
1336 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const(),
1337 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(), or
1338 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const(),
1339 depending on the selector field class's type.
1341 Those functions return the
1342 #bt_field_class_variant_with_selector_field_integer_unsigned_option or
1343 #bt_field_class_variant_with_selector_field_integer_signed_option type.
1344 \ref api-fund-c-typing "Upcast" those types to the
1345 #bt_field_class_variant_option type with
1346 bt_field_class_variant_with_selector_field_integer_unsigned_option_as_option_const()
1348 bt_field_class_variant_with_selector_field_integer_signed_option_as_option_const().
1350 Borrow the option's ranges from the class of a variant field with a
1351 linked selector field with
1352 bt_field_class_variant_with_selector_field_integer_unsigned_option_borrow_ranges_const()
1354 bt_field_class_variant_with_selector_field_integer_signed_option_borrow_ranges_const().
1356 Set a variant field class option's user attributes with
1357 bt_field_class_variant_option_set_user_attributes().
1359 Borrow a variant field class option's user attributes with
1360 bt_field_class_variant_option_borrow_user_attributes() and
1361 bt_field_class_variant_option_borrow_user_attributes_const().
1365 <h1>\anchor api-tir-fc-link Fields with links to other fields</h1>
1367 An instance of a \bt_dblob_fc, a \bt_darray_fc, a \bt_opt_fc, or a
1368 \bt_var_fc \em may have a link to another, anterior field within the
1369 same \bt_pkt or \bt_ev.
1371 This feature exists so that the linked field can contain the value of a
1372 dynamic property of the "dependent" field. Those properties are:
1375 <dt>\bt_c_dblob_field</dt>
1377 The linked field, a \bt_uint_field, contains the \b length (number
1378 of bytes) of the dynamic BLOB field.
1381 <dt>\bt_c_darray_field</dt>
1383 The linked field, a \bt_uint_field, contains the \b length (number
1384 of elements) of the dynamic array field.
1387 <dt>\bt_c_opt_field</dt>
1389 The linked field, either a \bt_bool_field or an \bt_int_field,
1390 indicates whether or not the option field has a field.
1393 <dt>\bt_c_var_field</dt>
1395 The linked field, an \bt_int_field, indicates the variant field's
1396 current selected field.
1400 Having a linked field is <em>optional</em>: you always set the field
1401 properties with a dedicated function anyway. For example, even if a
1402 dynamic array field is linked to an anterior length field, you must
1403 still set its integral length with bt_field_array_dynamic_set_length().
1404 In that case, the value of the linked length field \em must match what
1405 you pass to bt_field_array_dynamic_set_length().
1407 The purpose of this feature is to eventually save space when a
1408 \bt_sink_comp writes trace files: if, for example, the trace format can
1409 convey that an anterior, existing field represents the length of a
1410 dynamic array field, then the sink component doesn't need to write the
1411 dynamic array field's length twice. This is the case of the
1412 <a href="https://diamon.org/ctf/">Common Trace Format</a>, for example.
1414 @image html darray-link.png "A dynamic array field linked to an unsigned integer length field."
1416 How exactly you link a dependent field to another field at the field
1417 class level depends on the effective \bt_mip (MIP) version of the trace
1418 processing \bt_graph:
1421 <dt>MIP 0: \bt_c_field_path API
1423 Pass the class of the linked field when you create the class of the
1426 For example, pass the unsigned integer length field class to
1427 bt_field_class_array_dynamic_create() to create a class of
1428 \bt_darray_field with a linked length field.
1431 bt_stream_class_set_packet_context_field_class(),
1432 bt_stream_class_set_event_common_context_field_class(),
1433 bt_event_class_set_specific_context_field_class(), or
1434 bt_event_class_set_payload_field_class() with a field class
1435 containing a dependent field class with the class a linked field,
1436 the path to the linked field becomes available in the dependent
1437 field class. The functions to borrow said field path are:
1439 - bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const()
1440 - bt_field_class_option_with_selector_field_borrow_selector_field_path_const()
1441 - bt_field_class_variant_with_selector_field_borrow_selector_field_path_const()
1444 <dt>MIP 1: \bt_c_field_loc API
1446 Pass the field location when you create the class of the
1449 For example, pass the length field location to
1450 bt_field_class_array_dynamic_with_length_field_location_create() to
1451 create a class of \bt_darray_field with a linked length field.
1453 The functions to borrow the field location of a field class are:
1455 - bt_field_class_blob_dynamic_with_length_field_borrow_length_field_location_const()
1456 - bt_field_class_array_dynamic_with_length_field_borrow_length_field_location_const()
1457 - bt_field_class_option_with_selector_field_borrow_selector_field_location_const()
1458 - bt_field_class_variant_with_selector_field_borrow_selector_field_location_const()
1462 Both \bt_p_field_path (MIP 0 API) and \bt_p_field_loc (MIP 1
1463 API) indicate how to reach the linked field of a dependent field from
1464 some specific root <em>scope</em> (the starting point). The available
1468 <dt>#BT_FIELD_PATH_SCOPE_PACKET_CONTEXT</dt>
1469 <dt>#BT_FIELD_LOCATION_SCOPE_PACKET_CONTEXT</dt>
1471 Context field of the current \bt_pkt.
1473 See bt_packet_borrow_context_field_const().
1476 <dt>#BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT</dt>
1477 <dt>#BT_FIELD_LOCATION_SCOPE_EVENT_COMMON_CONTEXT</dt>
1479 Common context field of the current \bt_ev.
1481 See bt_event_borrow_common_context_field_const().
1484 <dt>#BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT</dt>
1485 <dt>#BT_FIELD_LOCATION_SCOPE_EVENT_SPECIFIC_CONTEXT</dt>
1487 Specific context field of the current event.
1489 See bt_event_borrow_specific_context_field_const().
1492 <dt>#BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD</dt>
1493 <dt>#BT_FIELD_LOCATION_SCOPE_EVENT_PAYLOAD</dt>
1495 Payload field of the current event.
1497 See bt_event_borrow_payload_field_const().
1501 The difference between a field path and a field location is that a field
1502 path works with \bt_struct_field member \em indexes while a field
1503 location works with structure field member <em>names</em>. The latter is
1504 more versatile because many fields may be candidates for the
1505 length/selector field of a dependent field (when they're all part of the
1506 same \bt_var_field).
1508 The rules regarding the dependent field \bt_var{A} vs. the linked
1509 field \bt_var{B} are:
1511 - If \bt_var{A} is within some packet context field, then \bt_var{B}
1512 must also be in the same packet context field.
1514 See bt_stream_class_set_packet_context_field_class().
1516 - If \bt_var{A} is within some common event context field, then
1517 \bt_var{B} must be in one of:
1519 - The same common event context field.
1520 - The context field of the same packet.
1522 See bt_stream_class_set_event_common_context_field_class().
1524 - If \bt_var{A} is within some specific event context field, then
1525 \bt_var{B} must be in one of:
1527 - The same specific event context field.
1528 - The common context field of the same event.
1529 - The context field of the same packet.
1531 See bt_event_class_set_specific_context_field_class().
1533 - If \bt_var{A} is within some event payload field, then \bt_var{B} must
1536 - The same event payload field.
1537 - The specific context field of the same event.
1538 - The common context field of the same event.
1539 - The context field of the same packet.
1541 See bt_event_class_set_payload_field_class().
1543 - If both \bt_var{A} and \bt_var{B} are in the same scope, then:
1545 - The lowest common ancestor field of \bt_var{A} and \bt_var{B} must
1546 be a structure field.
1548 - \bt_var{B} must precede \bt_var{A}.
1550 Considering that the members of a structure field are ordered,
1551 then \bt_var{B} must be part of a member that's before the member
1552 which contains \bt_var{A} in their lowest common ancestor
1555 - <strong>Under MIP 0</strong>, the path from the lowest common
1556 ancestor structure field of \bt_var{A} and \bt_var{B} to \bt_var{A}
1557 and to \bt_var{B} must only contain structure fields.
1559 - <strong>Under MIP 1</strong>, the path from the lowest common
1560 ancestor structure field of \bt_var{A} and \bt_var{B} to \bt_var{A}
1561 and to \bt_var{B} must only contain structure and variant fields.
1563 - If \bt_var{A} is in a different scope than \bt_var{B}, then:
1565 - <strong>Under MIP 0</strong>, the path from the root scope of
1566 \bt_var{B} to \bt_var{B} must only contain structure fields.
1568 - <strong>Under MIP 1</strong>, the path from the root scope of
1569 \bt_var{B} to \bt_var{B} must only contain structure and variant
1579 @typedef struct bt_field_class bt_field_class;
1594 Field class type enumerators.
1596 typedef enum bt_field_class_type
{
1601 BT_FIELD_CLASS_TYPE_BOOL
= 1ULL << 0,
1607 BT_FIELD_CLASS_TYPE_BIT_ARRAY
= 1ULL << 1,
1613 No field class has this type: use it with
1614 bt_field_class_type_is().
1616 BT_FIELD_CLASS_TYPE_INTEGER
= 1ULL << 2,
1622 This type conceptually inherits #BT_FIELD_CLASS_TYPE_INTEGER.
1624 BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER
= (1ULL << 3) | BT_FIELD_CLASS_TYPE_INTEGER
,
1630 This type conceptually inherits #BT_FIELD_CLASS_TYPE_INTEGER.
1632 BT_FIELD_CLASS_TYPE_SIGNED_INTEGER
= (1ULL << 4) | BT_FIELD_CLASS_TYPE_INTEGER
,
1638 This type conceptually inherits #BT_FIELD_CLASS_TYPE_INTEGER.
1640 No field class has this type: use it with
1641 bt_field_class_type_is().
1643 BT_FIELD_CLASS_TYPE_ENUMERATION
= 1ULL << 5,
1649 This type conceptually inherits #BT_FIELD_CLASS_TYPE_ENUMERATION
1650 and #BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER.
1652 BT_FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION
= BT_FIELD_CLASS_TYPE_ENUMERATION
| BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER
,
1658 This type conceptually inherits #BT_FIELD_CLASS_TYPE_ENUMERATION
1659 and #BT_FIELD_CLASS_TYPE_SIGNED_INTEGER.
1661 BT_FIELD_CLASS_TYPE_SIGNED_ENUMERATION
= BT_FIELD_CLASS_TYPE_ENUMERATION
| BT_FIELD_CLASS_TYPE_SIGNED_INTEGER
,
1667 No field class has this type: use it with
1668 bt_field_class_type_is().
1670 BT_FIELD_CLASS_TYPE_REAL
= 1ULL << 6,
1674 Single-precision \bt_real_fc.
1676 This type conceptually inherits #BT_FIELD_CLASS_TYPE_REAL.
1678 BT_FIELD_CLASS_TYPE_SINGLE_PRECISION_REAL
= (1ULL << 7) | BT_FIELD_CLASS_TYPE_REAL
,
1682 Double-precision \bt_real_fc.
1684 This type conceptually inherits #BT_FIELD_CLASS_TYPE_REAL.
1686 BT_FIELD_CLASS_TYPE_DOUBLE_PRECISION_REAL
= (1ULL << 8) | BT_FIELD_CLASS_TYPE_REAL
,
1692 BT_FIELD_CLASS_TYPE_STRING
= 1ULL << 9,
1698 No field class has this type: use it with
1699 bt_field_class_type_is().
1701 BT_FIELD_CLASS_TYPE_BLOB
= (1ULL << 29),
1707 This type conceptually inherits #BT_FIELD_CLASS_TYPE_BLOB.
1709 BT_FIELD_CLASS_TYPE_STATIC_BLOB
= (1ULL << 30) | BT_FIELD_CLASS_TYPE_BLOB
,
1715 This type conceptually inherits #BT_FIELD_CLASS_TYPE_BLOB.
1717 No field class has this type: use it with
1718 bt_field_class_type_is().
1720 BT_FIELD_CLASS_TYPE_DYNAMIC_BLOB
= (1ULL << 31) | BT_FIELD_CLASS_TYPE_BLOB
,
1724 \bt_c_dblob_fc (instances without a linked length field).
1726 This type conceptually inherits
1727 #BT_FIELD_CLASS_TYPE_DYNAMIC_BLOB.
1729 BT_FIELD_CLASS_TYPE_DYNAMIC_BLOB_WITHOUT_LENGTH_FIELD
= (1ULL << 32) | BT_FIELD_CLASS_TYPE_DYNAMIC_BLOB
,
1733 \bt_c_dblob_fc (instances with a linked length field).
1735 This type conceptually inherits
1736 #BT_FIELD_CLASS_TYPE_DYNAMIC_BLOB.
1738 BT_FIELD_CLASS_TYPE_DYNAMIC_BLOB_WITH_LENGTH_FIELD
= (1ULL << 33) | BT_FIELD_CLASS_TYPE_DYNAMIC_BLOB
,
1744 BT_FIELD_CLASS_TYPE_STRUCTURE
= 1ULL << 10,
1750 No field class has this type: use it with
1751 bt_field_class_type_is().
1753 BT_FIELD_CLASS_TYPE_ARRAY
= 1ULL << 11,
1759 This type conceptually inherits #BT_FIELD_CLASS_TYPE_ARRAY.
1761 BT_FIELD_CLASS_TYPE_STATIC_ARRAY
= (1ULL << 12) | BT_FIELD_CLASS_TYPE_ARRAY
,
1767 This type conceptually inherits #BT_FIELD_CLASS_TYPE_ARRAY.
1769 No field class has this type: use it with
1770 bt_field_class_type_is().
1772 BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY
= (1ULL << 13) | BT_FIELD_CLASS_TYPE_ARRAY
,
1776 \bt_c_darray_fc (instances without a linked length field).
1778 This type conceptually inherits
1779 #BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY.
1781 BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD
= (1ULL << 14) | BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY
,
1785 \bt_c_darray_fc (instances with a linked length field).
1787 This type conceptually inherits
1788 #BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY.
1790 BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD
= (1ULL << 15) | BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY
,
1796 No field class has this type: use it with
1797 bt_field_class_type_is().
1799 BT_FIELD_CLASS_TYPE_OPTION
= 1ULL << 16,
1803 \bt_c_opt_fc (instances without a linked selector field).
1805 BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD
= (1ULL << 17) | BT_FIELD_CLASS_TYPE_OPTION
,
1809 \bt_c_opt_fc (instances with a linked selector field).
1811 This type conceptually inherits #BT_FIELD_CLASS_TYPE_OPTION.
1813 No field class has this type: use it with
1814 bt_field_class_type_is().
1816 BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD
= (1ULL << 18) | BT_FIELD_CLASS_TYPE_OPTION
,
1820 \bt_c_opt_fc (instances with a linked boolean selector field).
1822 This type conceptually inherits
1823 #BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD.
1825 BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD
= (1ULL << 19) | BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD
,
1829 \bt_c_opt_fc (instances with a linked integer selector field).
1831 This type conceptually inherits
1832 #BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD.
1834 No field class has this type: use it with
1835 bt_field_class_type_is().
1837 BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD
= (1ULL << 20) | BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD
,
1841 \bt_c_opt_fc (instances with a linked unsigned integer selector field).
1843 This type conceptually inherits
1844 #BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD.
1846 BT_FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
= (1ULL << 21) | BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD
,
1850 \bt_c_opt_fc (instances with a linked signed integer selector field).
1852 This type conceptually inherits
1853 #BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD.
1855 BT_FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD
= (1ULL << 22) | BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD
,
1861 No field class has this type: use it with
1862 bt_field_class_type_is().
1864 BT_FIELD_CLASS_TYPE_VARIANT
= 1ULL << 23,
1868 \bt_c_var_fc (instances without a linked selector field).
1870 BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD
= (1ULL << 24) | BT_FIELD_CLASS_TYPE_VARIANT
,
1874 \bt_c_var_fc (instances with a linked selector field).
1876 This type conceptually inherits
1877 #BT_FIELD_CLASS_TYPE_VARIANT.
1879 No field class has this type: use it with
1880 bt_field_class_type_is().
1882 BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD
= (1ULL << 25) | BT_FIELD_CLASS_TYPE_VARIANT
,
1886 \bt_c_var_fc (instances with a linked integer selector field).
1888 This type conceptually inherits
1889 #BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD.
1891 No field class has this type: use it with
1892 bt_field_class_type_is().
1894 BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD
= (1ULL << 26) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD
,
1898 \bt_c_opt_fc (instances with a linked unsigned integer selector field).
1900 This type conceptually inherits
1901 #BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD.
1903 BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
= (1ULL << 27) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD
,
1907 \bt_c_opt_fc (instances with a linked signed integer selector field).
1909 This type conceptually inherits
1910 #BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD.
1912 BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD
= (1ULL << 28) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD
,
1915 * Make sure the enumeration type is a 64-bit integer in case
1916 * the project needs field class types in the future.
1918 * This is not part of the API.
1920 __BT_FIELD_CLASS_TYPE_BIG_VALUE
= 1ULL << 62,
1921 } bt_field_class_type
;
1925 Returns the type enumerator of the field class \bt_p{field_class}.
1927 @param[in] field_class
1928 Field class of which to get the type enumerator
1931 Type enumerator of \bt_p{field_class}.
1933 @bt_pre_not_null{field_class}
1935 @sa bt_field_class_type_is() —
1936 Returns whether or not the type of a field class conceptually is a
1939 extern bt_field_class_type
bt_field_class_get_type(
1940 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
1944 Returns whether or not the field class type \bt_p{type} conceptually
1945 \em is the field class type \bt_p{other_type}.
1947 For example, an \bt_uint_fc conceptually \em is an integer field class,
1951 bt_field_class_type_is(BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER, BT_FIELD_CLASS_TYPE_INTEGER)
1957 Field class type to check against \bt_p{other_type}.
1958 @param[in] other_type
1959 Field class type against which to check \bt_p{type}.
1962 #BT_TRUE if \bt_p{type} conceptually \em is \bt_p{other_type}.
1964 @sa bt_field_class_get_type() —
1965 Returns the type enumerator of a field class.
1968 bt_bool
bt_field_class_type_is(const bt_field_class_type type
,
1969 const bt_field_class_type other_type
) __BT_NOEXCEPT
1971 return (type
& other_type
) == other_type
;
1977 @name Common property
1983 Sets the user attributes of the field class \bt_p{field_class} to
1984 \bt_p{user_attributes}.
1986 See the \ref api-tir-fc-prop-user-attrs "user attributes" property.
1989 When you create a field class with one of the
1990 <code>bt_field_class_*_create()</code> functions, the field class's
1991 initial user attributes is an empty \bt_map_val. Therefore you can
1992 borrow it with bt_field_class_borrow_user_attributes() and fill it
1993 directly instead of setting a new one with this function.
1995 @param[in] field_class
1996 Field class of which to set the user attributes to
1997 \bt_p{user_attributes}.
1998 @param[in] user_attributes
1999 New user attributes of \bt_p{field_class}.
2001 @bt_pre_not_null{field_class}
2002 @bt_pre_hot{field_class}
2003 @bt_pre_not_null{user_attributes}
2004 @bt_pre_is_map_val{user_attributes}
2006 @sa bt_field_class_borrow_user_attributes() —
2007 Borrows the user attributes of a field class.
2009 extern void bt_field_class_set_user_attributes(
2010 bt_field_class
*field_class
,
2011 const bt_value
*user_attributes
) __BT_NOEXCEPT
;
2015 Borrows the user attributes of the field class \bt_p{field_class}.
2017 See the \ref api-tir-fc-prop-user-attrs "user attributes" property.
2020 When you create a field class with one of the
2021 <code>bt_field_class_*_create()</code> functions, the field class's
2022 initial user attributes is an empty \bt_map_val.
2024 @param[in] field_class
2025 Field class from which to borrow the user attributes.
2028 User attributes of \bt_p{field_class} (a \bt_map_val).
2030 @bt_pre_not_null{field_class}
2032 @sa bt_field_class_set_user_attributes() —
2033 Sets the user attributes of a field class.
2034 @sa bt_field_class_borrow_user_attributes_const() —
2035 \c const version of this function.
2037 extern bt_value
*bt_field_class_borrow_user_attributes(
2038 bt_field_class
*field_class
) __BT_NOEXCEPT
;
2042 Borrows the user attributes of the field class \bt_p{field_class}
2045 See bt_field_class_borrow_user_attributes().
2047 extern const bt_value
*bt_field_class_borrow_user_attributes_const(
2048 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
2053 @name Boolean field class
2059 Creates a \bt_bool_fc from the trace class \bt_p{trace_class}.
2061 On success, the returned boolean field class has the following
2069 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2070 <td>Empty \bt_map_val
2073 @param[in] trace_class
2074 Trace class from which to create a boolean field class.
2077 New boolean field class reference, or \c NULL on memory error.
2079 @bt_pre_not_null{trace_class}
2081 extern bt_field_class
*bt_field_class_bool_create(
2082 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
2089 @name Bit array field class
2095 Creates a \bt_ba_fc with the length \bt_p{length} from the trace
2096 class \bt_p{trace_class}.
2098 On success, the returned bit array field class has the following
2106 <td>\ref api-tir-fc-ba-prop-len "Length"
2110 \bt_mip version 1:
2111 \ref api-tir-fc-ba-prop-flags "flags"
2114 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2115 <td>Empty \bt_map_val
2118 @param[in] trace_class
2119 Trace class from which to create a bit array field class.
2121 Length (number of bits) of the instances of the bit array field
2125 New bit array field class reference, or \c NULL on memory error.
2127 @bt_pre_not_null{trace_class}
2129 0 < \bt_p{length} ≤ 64.
2131 extern bt_field_class
*bt_field_class_bit_array_create(
2132 bt_trace_class
*trace_class
, uint64_t length
) __BT_NOEXCEPT
;
2136 Returns the length of the \bt_ba_fc \bt_p{field_class}.
2138 See the \ref api-tir-fc-ba-prop-len "length" property.
2140 @param[in] field_class
2141 Bit array field class of which to get the length.
2144 Length of \bt_p{field_class}.
2146 @bt_pre_not_null{field_class}
2147 @bt_pre_is_ba_fc{field_class}
2149 extern uint64_t bt_field_class_bit_array_get_length(
2150 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
2154 Status codes for bt_field_class_bit_array_add_flag().
2156 typedef enum bt_field_class_bit_array_add_flag_status
{
2161 BT_FIELD_CLASS_BIT_ARRAY_ADD_FLAG_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2167 BT_FIELD_CLASS_BIT_ARRAY_ADD_FLAG_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2169 } bt_field_class_bit_array_add_flag_status
;
2173 Adds a flag to the \bt_ba_fc \bt_p{field_class} having the
2174 label \bt_p{label} and the bit index ranges \bt_p{index_ranges}.
2176 See the \ref api-tir-fc-ba-prop-flags "flags" property.
2178 @param[in] field_class
2179 Bit array field class to which to add a flag having
2180 the label \bt_p{label} and the bit index ranges \bt_p{index_ranges}.
2182 Label of the flag to add to \bt_p{field_class} (copied).
2184 Bit index ranges of the flag to add to \bt_p{field_class}.
2186 @retval #BT_FIELD_CLASS_BIT_ARRAY_ADD_FLAG_STATUS_OK
2188 @retval #BT_FIELD_CLASS_BIT_ARRAY_ADD_FLAG_STATUS_MEMORY_ERROR
2191 @bt_pre_not_null{field_class}
2192 @bt_pre_hot{field_class}
2193 @bt_pre_is_ba_fc{field_class}
2194 @bt_pre_fc_with_mip{field_class, 1}
2195 @bt_pre_not_null{label}
2197 \bt_p{field_class} has no flag with the label \bt_p{label}.
2198 @bt_pre_not_null{ranges}
2200 \bt_p{index_ranges} contains one or more unsigned integer ranges.
2202 No \link bt_integer_range_unsigned_get_upper() upper value\endlink
2203 of any range in \bt_p{index_ranges} is greater than or
2205 \link bt_field_class_bit_array_get_length() length\endlink of
2208 extern bt_field_class_bit_array_add_flag_status
2209 bt_field_class_bit_array_add_flag(
2210 bt_field_class
*field_class
, const char *label
,
2211 const bt_integer_range_set_unsigned
*index_ranges
) __BT_NOEXCEPT
;
2215 Returns the number of flags contained in the \bt_ba_fc
2218 See the \ref api-tir-fc-ba-prop-flags "flags" property.
2220 @param[in] field_class
2221 Bit array field class of which to get the number of contained
2225 Number of contained flags in \bt_p{field_class}.
2227 @bt_pre_not_null{field_class}
2228 @bt_pre_is_ba_fc{field_class}
2229 @bt_pre_fc_with_mip{field_class, 1}
2231 extern uint64_t bt_field_class_bit_array_get_flag_count(
2232 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
2236 Borrows the flag at index \bt_p{index} from the
2237 \bt_ba_fc \bt_p{field_class}.
2239 See the \ref api-tir-fc-ba-prop-flags "flags" property.
2241 @param[in] field_class
2242 Bit array field class from which to borrow the flag at
2245 Index of the flag to borrow from \bt_p{field_class}.
2249 \em Borrowed reference of the flag of
2250 \bt_p{field_class} at index \bt_p{index}.
2252 The returned pointer remains valid as long as \bt_p{field_class}
2256 @bt_pre_not_null{field_class}
2257 @bt_pre_is_ba_fc{field_class}
2258 @bt_pre_fc_with_mip{field_class, 1}
2260 \bt_p{index} is less than the
2261 \link bt_field_class_bit_array_get_flag_count() number of flags\endlink
2262 in \bt_p{field_class}.
2264 @sa bt_field_class_bit_array_get_flag_count() —
2265 Returns the number of flags contained in a
2266 bit array field class.
2268 extern const bt_field_class_bit_array_flag
*
2269 bt_field_class_bit_array_borrow_flag_by_index_const(
2270 const bt_field_class
*field_class
, uint64_t index
) __BT_NOEXCEPT
;
2274 Borrows the flag having the label \bt_p{label} from the
2275 \bt_ba_fc \bt_p{field_class}.
2277 See the \ref api-tir-fc-ba-prop-flags "flags" property.
2279 If there's no flag having the label \bt_p{label} in
2280 \bt_p{field_class}, this function returns \c NULL.
2282 @param[in] field_class
2283 Bit array field class from which to borrow the flag
2284 having the label \bt_p{label}.
2286 Label of the flag to borrow from \bt_p{field_class}.
2290 \em Borrowed reference of the flag of
2291 \bt_p{field_class} having the label \bt_p{label}, or \c NULL
2294 The returned pointer remains valid as long as \bt_p{field_class}
2298 @bt_pre_not_null{field_class}
2299 @bt_pre_is_ba_fc{field_class}
2300 @bt_pre_fc_with_mip{field_class, 1}
2301 @bt_pre_not_null{label}
2303 extern const bt_field_class_bit_array_flag
*
2304 bt_field_class_bit_array_borrow_flag_by_label_const(
2305 const bt_field_class
*field_class
, const char *label
) __BT_NOEXCEPT
;
2309 Array of \c const \bt_ba_fc flag labels.
2311 Returned by bt_field_class_bit_array_get_active_flag_labels_for_value_as_integer().
2313 typedef char const * const *bt_field_class_bit_array_flag_label_array
;
2318 bt_field_class_bit_array_get_active_flag_labels_for_value_as_integer().
2320 typedef enum bt_field_class_bit_array_get_active_flag_labels_for_value_as_integer_status
{
2325 BT_FIELD_CLASS_BIT_ARRAY_GET_ACTIVE_FLAG_LABELS_FOR_VALUE_AS_INTEGER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2331 BT_FIELD_CLASS_BIT_ARRAY_GET_ACTIVE_FLAG_LABELS_FOR_VALUE_AS_INTEGER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2332 } bt_field_class_bit_array_get_active_flag_labels_for_value_as_integer_status
;
2336 Returns the labels of all the active flags of the
2337 \bt_ba_fc \bt_p{field_class} for the set bits of
2338 \bt_p{value_as_integer} (a bit array field value as an integer).
2340 See the \ref api-tir-fc-ba-prop-flags "flags" property.
2342 This function sets \bt_p{*labels} to the resulting array and
2343 \bt_p{*count} to the number of labels in \bt_p{*labels}.
2345 On success, if there's no active flags for \bt_p{value_as_integer},
2348 @param[in] field_class
2349 Bit array field class from which to get the labels of the
2350 active flags for \bt_p{value_as_integer}.
2351 @param[in] value_as_integer
2353 Bits, as an integer, for which to get the labels of the active flags
2354 of \bt_p{field_class}.
2356 In this integral value, the index of the least significant bit
2361 <strong>On success</strong>, \bt_p{*labels}
2362 is an array of labels of the active flags of \bt_p{field_class}
2365 The number of labels in \bt_p{*labels} is \bt_p{*count}.
2367 The array is owned by \bt_p{field_class} and remains valid as long
2370 - \bt_p{field_class} is not modified.
2371 - You don't call this function again with \bt_p{field_class}.
2374 <strong>On success</strong>, \bt_p{*count} is the number of labels
2375 in \bt_p{*labels} (can be 0).
2377 @retval #BT_FIELD_CLASS_BIT_ARRAY_GET_ACTIVE_FLAG_LABELS_FOR_VALUE_AS_INTEGER_STATUS_OK
2379 @retval #BT_FIELD_CLASS_BIT_ARRAY_GET_ACTIVE_FLAG_LABELS_FOR_VALUE_AS_INTEGER_STATUS_MEMORY_ERROR
2382 @bt_pre_not_null{field_class}
2383 @bt_pre_is_ba_fc{field_class}
2384 @bt_pre_fc_with_mip{field_class, 1}
2385 @bt_pre_not_null{labels}
2386 @bt_pre_not_null{count}
2388 extern bt_field_class_bit_array_get_active_flag_labels_for_value_as_integer_status
2389 bt_field_class_bit_array_get_active_flag_labels_for_value_as_integer(
2390 const bt_field_class
*field_class
, uint64_t value_as_integer
,
2391 bt_field_class_bit_array_flag_label_array
*labels
,
2392 uint64_t *count
) __BT_NOEXCEPT
;
2396 Returns the label of the \bt_ba_fc flag \bt_p{flag}.
2398 See the \ref api-tir-fc-ba-prop-flags "flags" property.
2401 Bit array field class flag of which to get the label.
2405 Label of \bt_p{flag}.
2407 The returned pointer remains valid as long as \bt_p{flag} exists.
2410 @bt_pre_not_null{flag}
2412 extern const char *bt_field_class_bit_array_flag_get_label(
2413 const bt_field_class_bit_array_flag
*flag
) __BT_NOEXCEPT
;
2417 Borrows the bit index ranges from the \bt_ba_fc flag \bt_p{flag}.
2419 See the \ref api-tir-fc-ba-prop-flags "flags" property.
2422 Bit array field class flag from which to borrow the
2426 Bit index ranges of \bt_p{flag}.
2428 @bt_pre_not_null{flag}
2430 extern const bt_integer_range_set_unsigned
*
2431 bt_field_class_bit_array_flag_borrow_index_ranges_const(
2432 const bt_field_class_bit_array_flag
*flag
) __BT_NOEXCEPT
;
2439 @name Integer field class
2445 Sets the field value range of the \bt_int_fc \bt_p{field_class}
2448 See the \ref api-tir-fc-int-prop-size "field value range" property.
2450 @param[in] field_class
2451 Integer field class of which to set the field value range to
2458 <dt>Unsigned integer field class</dt>
2459 <dd>[0, 2<sup><em>N</em></sup> − 1]</dd>
2461 <dt>Signed integer field class</dt>
2462 <dd>[−2<sup><em>N</em> − 1</sup>, 2<sup><em>N</em> − 1</sup> − 1]</dd>
2466 @bt_pre_not_null{field_class}
2467 @bt_pre_hot{field_class}
2468 @bt_pre_is_int_fc{field_class}
2472 @sa bt_field_class_integer_get_field_value_range() —
2473 Returns the field value range of an integer field class.
2475 extern void bt_field_class_integer_set_field_value_range(
2476 bt_field_class
*field_class
, uint64_t n
) __BT_NOEXCEPT
;
2480 Returns the field value range of the \bt_int_fc \bt_p{field_class}.
2482 See the \ref api-tir-fc-int-prop-size "field value range" property.
2484 @param[in] field_class
2485 Integer field class of which to get the field value range.
2489 Field value range of \bt_p{field_class}, that is, \em N in:
2492 <dt>Unsigned integer field class</dt>
2493 <dd>[0, 2<sup><em>N</em></sup> − 1]</dd>
2495 <dt>Signed integer field class</dt>
2496 <dd>[−2<sup><em>N</em></sup>, 2<sup><em>N</em></sup> − 1]</dd>
2500 @bt_pre_not_null{field_class}
2501 @bt_pre_is_int_fc{field_class}
2503 @sa bt_field_class_integer_set_field_value_range() —
2504 Sets the field value range of an integer field class.
2506 extern uint64_t bt_field_class_integer_get_field_value_range(
2507 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
2511 Integer field class preferred display bases.
2513 typedef enum bt_field_class_integer_preferred_display_base
{
2518 BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_BINARY
= 2,
2524 BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_OCTAL
= 8,
2530 BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
= 10,
2536 BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_HEXADECIMAL
= 16,
2537 } bt_field_class_integer_preferred_display_base
;
2541 Sets the preferred display base of the \bt_int_fc \bt_p{field_class}
2542 to \bt_p{preferred_display_base}.
2544 See the \ref api-tir-fc-int-prop-base "preferred display base" property.
2546 @param[in] field_class
2547 Integer field class of which to set the preferred display base to
2548 \bt_p{preferred_display_base}.
2549 @param[in] preferred_display_base
2550 New preferred display base of \bt_p{field_class}.
2552 @bt_pre_not_null{field_class}
2553 @bt_pre_hot{field_class}
2554 @bt_pre_is_int_fc{field_class}
2556 @sa bt_field_class_integer_get_preferred_display_base() —
2557 Returns the preferred display base of an integer field class.
2559 extern void bt_field_class_integer_set_preferred_display_base(
2560 bt_field_class
*field_class
,
2561 bt_field_class_integer_preferred_display_base preferred_display_base
)
2566 Returns the preferred display base of the \bt_int_fc
2569 See the \ref api-tir-fc-int-prop-base "preferred display base" property.
2571 @param[in] field_class
2572 Integer field class of which to get the preferred display base.
2574 @retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_BINARY
2576 @retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_OCTAL
2578 @retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
2580 @retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_HEXADECIMAL
2583 @bt_pre_not_null{field_class}
2584 @bt_pre_is_int_fc{field_class}
2586 @sa bt_field_class_integer_set_preferred_display_base() —
2587 Sets the preferred display base of an integer field class.
2589 extern bt_field_class_integer_preferred_display_base
2590 bt_field_class_integer_get_preferred_display_base(
2591 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
2596 @name Unsigned integer field class
2602 Creates an \bt_uint_fc from the trace class \bt_p{trace_class}.
2604 On success, the returned unsigned integer field class has the following
2612 <td>\ref api-tir-fc-int-prop-size "Field value range"
2613 <td>[0, 2<sup>64</sup> − 1]
2615 <td>\ref api-tir-fc-int-prop-base "Preferred display base"
2616 <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
2618 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2619 <td>Empty \bt_map_val
2622 @param[in] trace_class
2623 Trace class from which to create an unsigned integer field class.
2626 New unsigned integer field class reference, or \c NULL on memory error.
2628 @bt_pre_not_null{trace_class}
2630 extern bt_field_class
*bt_field_class_integer_unsigned_create(
2631 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
2636 @name Signed integer field class
2642 Creates an \bt_sint_fc from the trace class \bt_p{trace_class}.
2644 On success, the returned signed integer field class has the following
2652 <td>\ref api-tir-fc-int-prop-size "Field value range"
2653 <td>[−2<sup>63</sup>, 2<sup>63</sup> − 1]
2655 <td>\ref api-tir-fc-int-prop-base "Preferred display base"
2656 <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
2658 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2659 <td>Empty \bt_map_val
2662 @param[in] trace_class
2663 Trace class from which to create a signed integer field class.
2666 New signed integer field class reference, or \c NULL on memory error.
2668 @bt_pre_not_null{trace_class}
2670 extern bt_field_class
*bt_field_class_integer_signed_create(
2671 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
2676 @name Single-precision real field class
2682 Creates a single-precision \bt_real_fc from the trace class
2685 On success, the returned single-precision real field class has the
2686 following property value:
2693 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2694 <td>Empty \bt_map_val
2697 @param[in] trace_class
2698 Trace class from which to create a single-preicision real
2702 New single-precision real field class reference, or \c NULL on
2705 @bt_pre_not_null{trace_class}
2707 extern bt_field_class
*bt_field_class_real_single_precision_create(
2708 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
2713 @name Double-precision real field class
2719 Creates a double-precision \bt_real_fc from the trace class
2722 On success, the returned double-precision real field class has the
2723 following property value:
2730 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2731 <td>Empty \bt_map_val
2734 @param[in] trace_class
2735 Trace class from which to create a double-preicision real
2739 New double-precision real field class reference, or \c NULL on
2742 @bt_pre_not_null{trace_class}
2744 extern bt_field_class
*bt_field_class_real_double_precision_create(
2745 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
2750 @name Enumeration field class
2756 Array of \c const \bt_enum_fc mapping labels.
2758 Returned by bt_field_class_enumeration_unsigned_get_mapping_labels_for_value()
2759 and bt_field_class_enumeration_signed_get_mapping_labels_for_value().
2761 typedef char const * const *bt_field_class_enumeration_mapping_label_array
;
2766 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value()
2768 bt_field_class_enumeration_signed_get_mapping_labels_for_value().
2770 typedef enum bt_field_class_enumeration_get_mapping_labels_for_value_status
{
2775 BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2781 BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2782 } bt_field_class_enumeration_get_mapping_labels_for_value_status
;
2786 Status codes for bt_field_class_enumeration_unsigned_add_mapping()
2787 and bt_field_class_enumeration_signed_add_mapping().
2789 typedef enum bt_field_class_enumeration_add_mapping_status
{
2794 BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK
= __BT_FUNC_STATUS_OK
,
2800 BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
2801 } bt_field_class_enumeration_add_mapping_status
;
2806 @name Enumeration field class mapping
2811 @typedef struct bt_field_class_enumeration_mapping bt_field_class_enumeration_mapping;
2814 Enumeration field class mapping.
2819 Returns the number of mappings contained in the \bt_enum_fc
2822 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2824 @param[in] field_class
2825 Enumeration field class of which to get the number of contained
2829 Number of contained mappings in \bt_p{field_class}.
2831 @bt_pre_not_null{field_class}
2832 @bt_pre_is_enum_fc{field_class}
2834 extern uint64_t bt_field_class_enumeration_get_mapping_count(
2835 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
2839 Returns the label of the \bt_enum_fc mapping \bt_p{mapping}.
2841 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2844 Enumeration field class mapping of which to get the label.
2848 Label of \bt_p{mapping}.
2850 The returned pointer remains valid as long as \bt_p{mapping} exists.
2853 @bt_pre_not_null{mapping}
2855 extern const char *bt_field_class_enumeration_mapping_get_label(
2856 const bt_field_class_enumeration_mapping
*mapping
)
2862 @name Unsigned enumeration field class
2868 Creates an \bt_uenum_fc from the trace class \bt_p{trace_class}.
2870 On success, the returned unsigned enumeration field class has the
2871 following property values:
2878 <td>\ref api-tir-fc-int-prop-size "Field value range"
2879 <td>[0, 2<sup>64</sup> − 1]
2881 <td>\ref api-tir-fc-int-prop-base "Preferred display base"
2882 <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
2884 <td>\ref api-tir-fc-enum-prop-mappings "Mappings"
2887 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
2888 <td>Empty \bt_map_val
2891 @param[in] trace_class
2892 Trace class from which to create an unsigned enumeration field
2896 New unsigned enumeration field class reference, or \c NULL on memory
2899 @bt_pre_not_null{trace_class}
2901 extern bt_field_class
*bt_field_class_enumeration_unsigned_create(
2902 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
2906 Adds a mapping to the \bt_uenum_fc \bt_p{field_class} having the
2907 label \bt_p{label} and the unsigned integer ranges \bt_p{ranges}.
2909 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2911 @param[in] field_class
2912 Unsigned enumeration field class to which to add a mapping having
2913 the label \bt_p{label} and the integer ranges \bt_p{ranges}.
2915 Label of the mapping to add to \bt_p{field_class} (copied).
2917 Unsigned integer ranges of the mapping to add to
2920 @retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK
2922 @retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR
2925 @bt_pre_not_null{field_class}
2926 @bt_pre_hot{field_class}
2927 @bt_pre_is_uenum_fc{field_class}
2928 @bt_pre_not_null{label}
2930 \bt_p{field_class} has no mapping with the label \bt_p{label}.
2931 @bt_pre_not_null{ranges}
2933 \bt_p{ranges} contains one or more unsigned integer ranges.
2935 extern bt_field_class_enumeration_add_mapping_status
2936 bt_field_class_enumeration_unsigned_add_mapping(
2937 bt_field_class
*field_class
, const char *label
,
2938 const bt_integer_range_set_unsigned
*ranges
) __BT_NOEXCEPT
;
2942 Borrows the mapping at index \bt_p{index} from the
2943 \bt_uenum_fc \bt_p{field_class}.
2945 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2947 @param[in] field_class
2948 Unsigned enumeration field class from which to borrow the mapping at
2951 Index of the mapping to borrow from \bt_p{field_class}.
2955 \em Borrowed reference of the mapping of
2956 \bt_p{field_class} at index \bt_p{index}.
2958 The returned pointer remains valid as long as \bt_p{field_class}
2962 @bt_pre_not_null{field_class}
2963 @bt_pre_is_uenum_fc{field_class}
2965 \bt_p{index} is less than the number of mappings in
2966 \bt_p{field_class} (as returned by
2967 bt_field_class_enumeration_get_mapping_count()).
2969 @sa bt_field_class_enumeration_get_mapping_count() —
2970 Returns the number of mappings contained in an
2971 enumeration field class.
2973 extern const bt_field_class_enumeration_unsigned_mapping
*
2974 bt_field_class_enumeration_unsigned_borrow_mapping_by_index_const(
2975 const bt_field_class
*field_class
, uint64_t index
)
2980 Borrows the mapping having the label \bt_p{label} from the
2981 \bt_uenum_fc \bt_p{field_class}.
2983 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
2985 If there's no mapping having the label \bt_p{label} in
2986 \bt_p{field_class}, this function returns \c NULL.
2988 @param[in] field_class
2989 Unsigned enumeration field class from which to borrow the mapping
2990 having the label \bt_p{label}.
2992 Label of the mapping to borrow from \bt_p{field_class}.
2996 \em Borrowed reference of the mapping of
2997 \bt_p{field_class} having the label \bt_p{label}, or \c NULL
3000 The returned pointer remains valid as long as \bt_p{field_class}
3004 @bt_pre_not_null{field_class}
3005 @bt_pre_is_uenum_fc{field_class}
3006 @bt_pre_not_null{label}
3008 extern const bt_field_class_enumeration_unsigned_mapping
*
3009 bt_field_class_enumeration_unsigned_borrow_mapping_by_label_const(
3010 const bt_field_class
*field_class
, const char *label
)
3015 Returns an array of all the labels of the mappings of the
3016 \bt_uenum_fc \bt_p{field_class} of which the \bt_p_uint_rg contain
3017 the integral value \bt_p{value}.
3019 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
3021 This function sets \bt_p{*labels} to the resulting array and
3022 \bt_p{*count} to the number of labels in \bt_p{*labels}.
3024 On success, if there's no mapping ranges containing the value
3025 \bt_p{value}, \bt_p{*count} is 0.
3027 @param[in] field_class
3028 Unsigned enumeration field class from which to get the labels of the
3029 mappings of which the ranges contain \bt_p{value}.
3031 Value for which to get the mapped labels in \bt_p{field_class}.
3034 <strong>On success</strong>, \bt_p{*labels}
3035 is an array of labels of the mappings of \bt_p{field_class}
3036 containing \bt_p{value}.
3038 The number of labels in \bt_p{*labels} is \bt_p{*count}.
3040 The array is owned by \bt_p{field_class} and remains valid as long
3043 - \bt_p{field_class} is not modified.
3044 - You don't call this function again with \bt_p{field_class}.
3047 <strong>On success</strong>, \bt_p{*count} is the number of labels
3048 in \bt_p{*labels} (can be 0).
3050 @retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK
3052 @retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR
3055 @bt_pre_not_null{field_class}
3056 @bt_pre_is_uenum_fc{field_class}
3057 @bt_pre_not_null{labels}
3058 @bt_pre_not_null{count}
3060 extern bt_field_class_enumeration_get_mapping_labels_for_value_status
3061 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value(
3062 const bt_field_class
*field_class
, uint64_t value
,
3063 bt_field_class_enumeration_mapping_label_array
*labels
,
3064 uint64_t *count
) __BT_NOEXCEPT
;
3069 @name Unsigned enumeration field class mapping
3074 @typedef struct bt_field_class_enumeration_unsigned_mapping bt_field_class_enumeration_unsigned_mapping;
3077 Unsigned enumeration field class mapping.
3082 Borrows the \bt_p_uint_rg from the \bt_uenum_fc mapping
3085 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
3088 Unsigned enumeration field class mapping from which to borrow the
3089 unsigned integer ranges.
3092 Unsigned integer ranges of \bt_p{mapping}.
3094 @bt_pre_not_null{mapping}
3096 extern const bt_integer_range_set_unsigned
*
3097 bt_field_class_enumeration_unsigned_mapping_borrow_ranges_const(
3098 const bt_field_class_enumeration_unsigned_mapping
*mapping
)
3103 \ref api-fund-c-typing "Upcasts" the \bt_uenum_fc mapping
3104 \bt_p{mapping} to the common #bt_field_class_enumeration_mapping
3107 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
3111 Unsigned enumeration field class mapping to upcast.
3117 \bt_p{mapping} as a common enumeration field class mapping.
3120 const bt_field_class_enumeration_mapping
*
3121 bt_field_class_enumeration_unsigned_mapping_as_mapping_const(
3122 const bt_field_class_enumeration_unsigned_mapping
*mapping
)
3125 return __BT_UPCAST_CONST(bt_field_class_enumeration_mapping
, mapping
);
3131 @name Signed enumeration field class
3137 Creates a \bt_senum_fc from the trace class \bt_p{trace_class}.
3139 On success, the returned signed enumeration field class has the
3140 following property values:
3147 <td>\ref api-tir-fc-int-prop-size "Field value range"
3148 <td>[−2<sup>63</sup>, 2<sup>63</sup> − 1]
3150 <td>\ref api-tir-fc-int-prop-base "Preferred display base"
3151 <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
3153 <td>\ref api-tir-fc-enum-prop-mappings "Mappings"
3156 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3157 <td>Empty \bt_map_val
3160 @param[in] trace_class
3161 Trace class from which to create a signed enumeration field
3165 New signed enumeration field class reference, or \c NULL on memory
3168 @bt_pre_not_null{trace_class}
3170 extern bt_field_class
*bt_field_class_enumeration_signed_create(
3171 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
3175 Adds a mapping to the \bt_senum_fc \bt_p{field_class} having the
3176 label \bt_p{label} and the \bt_p_sint_rg \bt_p{ranges}.
3178 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
3180 @param[in] field_class
3181 Signed enumeration field class to which to add a mapping having
3182 the label \bt_p{label} and the integer ranges \bt_p{ranges}.
3184 Label of the mapping to add to \bt_p{field_class} (copied).
3186 Signed integer ranges of the mapping to add to
3189 @retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK
3191 @retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR
3194 @bt_pre_not_null{field_class}
3195 @bt_pre_hot{field_class}
3196 @bt_pre_is_senum_fc{field_class}
3197 @bt_pre_not_null{label}
3199 \bt_p{field_class} has no mapping with the label \bt_p{label}.
3200 @bt_pre_not_null{ranges}
3202 \bt_p{ranges} contains one or more signed integer ranges.
3204 extern bt_field_class_enumeration_add_mapping_status
3205 bt_field_class_enumeration_signed_add_mapping(
3206 bt_field_class
*field_class
, const char *label
,
3207 const bt_integer_range_set_signed
*ranges
) __BT_NOEXCEPT
;
3211 Borrows the mapping at index \bt_p{index} from the
3212 \bt_senum_fc \bt_p{field_class}.
3214 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
3216 @param[in] field_class
3217 Signed enumeration field class from which to borrow the mapping at
3220 Index of the mapping to borrow from \bt_p{field_class}.
3224 \em Borrowed reference of the mapping of
3225 \bt_p{field_class} at index \bt_p{index}.
3227 The returned pointer remains valid as long as \bt_p{field_class}
3231 @bt_pre_not_null{field_class}
3232 @bt_pre_is_senum_fc{field_class}
3234 \bt_p{index} is less than the number of mappings in
3235 \bt_p{field_class} (as returned by
3236 bt_field_class_enumeration_get_mapping_count()).
3238 @sa bt_field_class_enumeration_get_mapping_count() —
3239 Returns the number of mappings contained in an
3240 enumeration field class.
3242 extern const bt_field_class_enumeration_signed_mapping
*
3243 bt_field_class_enumeration_signed_borrow_mapping_by_index_const(
3244 const bt_field_class
*field_class
, uint64_t index
)
3249 Borrows the mapping having the label \bt_p{label} from the
3250 \bt_senum_fc \bt_p{field_class}.
3252 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
3254 If there's no mapping having the label \bt_p{label} in
3255 \bt_p{field_class}, this function returns \c NULL.
3257 @param[in] field_class
3258 Signed enumeration field class from which to borrow the mapping
3259 having the label \bt_p{label}.
3261 Label of the mapping to borrow from \bt_p{field_class}.
3265 \em Borrowed reference of the mapping of
3266 \bt_p{field_class} having the label \bt_p{label}, or \c NULL
3269 The returned pointer remains valid as long as \bt_p{field_class}
3273 @bt_pre_not_null{field_class}
3274 @bt_pre_is_senum_fc{field_class}
3275 @bt_pre_not_null{label}
3277 extern const bt_field_class_enumeration_signed_mapping
*
3278 bt_field_class_enumeration_signed_borrow_mapping_by_label_const(
3279 const bt_field_class
*field_class
, const char *label
)
3284 Returns an array of all the labels of the mappings of the
3285 \bt_senum_fc \bt_p{field_class} of which the \bt_p_sint_rg contain
3286 the integral value \bt_p{value}.
3288 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
3290 This function sets \bt_p{*labels} to the resulting array and
3291 \bt_p{*count} to the number of labels in \bt_p{*labels}.
3293 On success, if there's no mapping ranges containing the value
3294 \bt_p{value}, \bt_p{*count} is 0.
3296 @param[in] field_class
3297 Signed enumeration field class from which to get the labels of the
3298 mappings of which the ranges contain \bt_p{value}.
3300 Value for which to get the mapped labels in \bt_p{field_class}.
3303 <strong>On success</strong>, \bt_p{*labels}
3304 is an array of labels of the mappings of \bt_p{field_class}
3305 containing \bt_p{value}.
3307 The number of labels in \bt_p{*labels} is \bt_p{*count}.
3309 The array is owned by \bt_p{field_class} and remains valid as long
3312 - \bt_p{field_class} is not modified.
3313 - You don't call this function again with \bt_p{field_class}.
3316 <strong>On success</strong>, \bt_p{*count} is the number of labels
3317 in \bt_p{*labels} (can be 0).
3319 @retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK
3321 @retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR
3324 @bt_pre_not_null{field_class}
3325 @bt_pre_is_senum_fc{field_class}
3326 @bt_pre_not_null{labels}
3327 @bt_pre_not_null{count}
3329 extern bt_field_class_enumeration_get_mapping_labels_for_value_status
3330 bt_field_class_enumeration_signed_get_mapping_labels_for_value(
3331 const bt_field_class
*field_class
, int64_t value
,
3332 bt_field_class_enumeration_mapping_label_array
*labels
,
3333 uint64_t *count
) __BT_NOEXCEPT
;
3338 @name Signed enumeration field class mapping
3343 @typedef struct bt_field_class_enumeration_signed_mapping bt_field_class_enumeration_signed_mapping;
3346 Signed enumeration field class mapping.
3351 Borrows the \bt_p_sint_rg from the \bt_senum_fc mapping
3354 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
3357 Signed enumeration field class mapping from which to borrow the
3358 signed integer ranges.
3361 Signed integer ranges of \bt_p{mapping}.
3363 @bt_pre_not_null{mapping}
3365 extern const bt_integer_range_set_signed
*
3366 bt_field_class_enumeration_signed_mapping_borrow_ranges_const(
3367 const bt_field_class_enumeration_signed_mapping
*mapping
)
3372 \ref api-fund-c-typing "Upcasts" the \bt_senum_fc mapping
3373 \bt_p{mapping} to the common #bt_field_class_enumeration_mapping
3376 See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
3380 Signed enumeration field class mapping to upcast.
3386 \bt_p{mapping} as a common enumeration field class mapping.
3389 const bt_field_class_enumeration_mapping
*
3390 bt_field_class_enumeration_signed_mapping_as_mapping_const(
3391 const bt_field_class_enumeration_signed_mapping
*mapping
)
3394 return __BT_UPCAST_CONST(bt_field_class_enumeration_mapping
, mapping
);
3400 @name String field class
3406 Creates a \bt_string_fc from the trace class \bt_p{trace_class}.
3408 On success, the returned string field class has the following property
3416 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3417 <td>Empty \bt_map_val
3420 @param[in] trace_class
3421 Trace class from which to create a string field class.
3424 New string field class reference, or \c NULL on memory error.
3426 @bt_pre_not_null{trace_class}
3428 extern bt_field_class
*bt_field_class_string_create(
3429 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
3434 @name BLOB field class
3440 Creates a \bt_sblob_fc having the length \bt_p{length} from the
3441 trace class \bt_p{trace_class}.
3443 On success, the returned static BLOB field class has the following
3451 <td>\ref api-tir-fc-sarray-prop-len "Length"
3454 <td>\ref api-tir-fc-blob-prop-media-type "Media type"
3455 <td><code>application/octet-stream</code>
3457 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3458 <td>Empty \bt_map_val
3461 @param[in] trace_class
3462 Trace class from which to create a static BLOB field class.
3464 Length (number of bytes) of the instances of the static BLOB
3465 field class to create.
3468 New static BLOB field class reference, or \c NULL on memory error.
3470 @bt_pre_not_null{trace_class}
3471 @bt_pre_tc_with_mip{trace_class, 1}
3473 @sa bt_field_class_blob_dynamic_without_length_field_location_create() —
3474 Creates a class of dynamic BLOB field without a linked length field.
3475 @sa bt_field_class_blob_dynamic_with_length_field_location_create() —
3476 Creates a class of dynamic BLOB field with a linked length field.
3478 extern bt_field_class
*bt_field_class_blob_static_create(
3479 bt_trace_class
*trace_class
, uint64_t length
) __BT_NOEXCEPT
;
3483 Creates a \bt_dblob_fc (instances without a linked length field)
3484 from the trace class \bt_p{trace_class}.
3486 On success, the returned dynamic BLOB field class has the following
3494 <td>\ref api-tir-fc-dblob-prop-len-fl "Length field location"
3498 <td>\ref api-tir-fc-blob-prop-media-type "Media type"
3499 <td><code>application/octet-stream</code>
3501 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3502 <td>Empty \bt_map_val
3505 @param[in] trace_class
3506 Trace class from which to create a dynamic BLOB field class.
3509 New dynamic BLOB field class reference (without a length field),
3510 or \c NULL on memory error.
3512 @bt_pre_not_null{trace_class}
3513 @bt_pre_tc_with_mip{trace_class, 1}
3515 @sa bt_field_class_blob_dynamic_with_length_field_location_create() —
3516 Creates a class of dynamic BLOB field with a linked length field.
3518 extern bt_field_class
*
3519 bt_field_class_blob_dynamic_without_length_field_location_create(
3520 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
3524 Creates a \bt_dblob_fc (instances with a linked length field)
3525 having the length \bt_field_loc \bt_p{length_field_location} from
3526 the trace class \bt_p{trace_class}.
3528 On success, the returned dynamic BLOB field class has the following
3536 <td>\ref api-tir-fc-dblob-prop-len-fl "Length field location"
3538 \bt_p{length_field_location}.
3540 See \ref api-tir-fc-link "Fields with links to other fields"
3543 <td>\ref api-tir-fc-blob-prop-media-type "Media type"
3544 <td><code>application/octet-stream</code>
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 a dynamic BLOB field class.
3552 @param[in] length_field_location
3553 Length field location of the dynamic BLOB field class to create.
3556 New dynamic BLOB field class reference (instances with a linked
3557 length field), or \c NULL on memory error.
3559 @bt_pre_not_null{trace_class}
3560 @bt_pre_tc_with_mip{trace_class, 1}
3561 @bt_pre_not_null{length_field_location}
3563 @sa bt_field_class_blob_dynamic_without_length_field_location_create() —
3564 Creates a class of dynamic BLOB field without a linked
3567 extern bt_field_class
*
3568 bt_field_class_blob_dynamic_with_length_field_location_create(
3569 bt_trace_class
*trace_class
,
3570 const bt_field_location
*length_field_location
) __BT_NOEXCEPT
;
3574 Returns the length of the \bt_sblob_fc \bt_p{field_class}.
3576 See the \ref api-tir-fc-sblob-prop-len "length" property.
3578 @param[in] field_class
3579 Static BLOB field class of which to get the length (number of bytes
3583 Length of \bt_p{field_class}.
3585 @bt_pre_not_null{field_class}
3586 @bt_pre_is_sblob_fc{field_class}
3587 @bt_pre_fc_with_mip{field_class, 1}
3589 extern uint64_t bt_field_class_blob_static_get_length(
3590 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
3594 Borrows the length field location from the \bt_dblob_fc (instances
3595 with a linked length field) \bt_p{field_class}.
3597 See the \ref api-tir-fc-dblob-prop-len-fl "length field location"
3600 @param[in] field_class
3601 Dynamic BLOB field class from which to borrow the length
3605 Length field location of \bt_p{field_class}.
3607 @bt_pre_not_null{field_class}
3608 @bt_pre_is_dblob_wl_fc{field_class}
3609 @bt_pre_fc_with_mip{field_class, 1}
3611 extern const bt_field_location
*
3612 bt_field_class_blob_dynamic_with_length_field_borrow_length_field_location_const(
3613 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
3617 Status codes for bt_field_class_blob_set_media_type().
3619 typedef enum bt_field_class_blob_set_media_type_status
{
3624 BT_FIELD_CLASS_BLOB_SET_MEDIA_TYPE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
3630 BT_FIELD_CLASS_BLOB_SET_MEDIA_TYPE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
3631 } bt_field_class_blob_set_media_type_status
;
3635 Sets the IANA media type of the \bt_blob_fc \bt_p{field_class}
3636 to a copy of \bt_p{media_type}.
3638 See the \ref api-tir-fc-blob-prop-media-type "media type" property.
3640 @param[in] field_class
3641 BLOB field class of which to set the media type to a copy of
3643 @param[in] media_type
3644 New media type of \bt_p{field_class} (copied).
3646 @retval #BT_FIELD_CLASS_BLOB_SET_MEDIA_TYPE_STATUS_OK
3648 @retval #BT_FIELD_CLASS_BLOB_SET_MEDIA_TYPE_STATUS_MEMORY_ERROR
3651 @bt_pre_not_null{field_class}
3652 @bt_pre_hot{field_class}
3653 @bt_pre_is_blob_fc{field_class}
3654 @bt_pre_fc_with_mip{field_class, 1}
3656 @sa bt_field_class_blob_get_media_type() —
3657 Returns the IANA media type of BLOB field class.
3659 extern bt_field_class_blob_set_media_type_status
3660 bt_field_class_blob_set_media_type(bt_field_class
*field_class
,
3661 const char *media_type
) __BT_NOEXCEPT
;
3665 Returns the IANA media type of the \bt_blob_fc \bt_p{field_class}.
3667 See the \ref api-tir-fc-blob-prop-media-type "media type" property.
3669 If \bt_p{field_class} has no media type, this function returns \c NULL.
3671 @param[in] field_class
3672 BLOB field class of which to get the media type.
3676 Media type of \bt_p{field_class}, or \c NULL if none.
3678 The returned pointer remains valid as long as \bt_p{field_class}
3682 @bt_pre_not_null{field_class}
3683 @bt_pre_is_blob_fc{field_class}
3684 @bt_pre_fc_with_mip{field_class, 1}
3686 @sa bt_field_class_blob_set_media_type() —
3687 Sets the media type of a BLOB field class.
3689 extern const char *bt_field_class_blob_get_media_type(
3690 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
3695 @name Array field class
3701 Borrows the element field class from the \bt_array_fc
3704 See the \ref api-tir-fc-array-prop-elem-fc "element field class"
3707 @param[in] field_class
3708 Array field class from which to borrow the element field class.
3711 Element field class of \bt_p{field_class}.
3713 @bt_pre_not_null{field_class}
3714 @bt_pre_is_array_fc{field_class}
3716 @sa bt_field_class_array_borrow_element_field_class_const() —
3717 \c const version of this function.
3719 extern bt_field_class
*bt_field_class_array_borrow_element_field_class(
3720 bt_field_class
*field_class
) __BT_NOEXCEPT
;
3724 Borrows the element field class from the \bt_array_fc
3725 \bt_p{field_class} (\c const version).
3727 See bt_field_class_array_borrow_element_field_class().
3729 extern const bt_field_class
*
3730 bt_field_class_array_borrow_element_field_class_const(
3731 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
3736 @name Static array field class
3742 Creates a \bt_sarray_fc having the element field class
3743 \bt_p{element_field_class} and the length \bt_p{length} from the
3744 trace class \bt_p{trace_class}.
3746 On success, the returned static array field class has the following
3754 <td>\ref api-tir-fc-array-prop-elem-fc "Element field class"
3755 <td>\bt_p{element_field_class}
3757 <td>\ref api-tir-fc-sarray-prop-len "Length"
3760 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3761 <td>Empty \bt_map_val
3764 @param[in] trace_class
3765 Trace class from which to create a static array field class.
3766 @param[in] element_field_class
3767 Class of the element fields of the instances of the static array
3768 field class to create.
3770 Length of the instances of the static array field class to create.
3773 New static array field class reference, or \c NULL on memory error.
3775 @bt_pre_not_null{trace_class}
3776 @bt_pre_not_null{element_field_class}
3777 @bt_pre_fc_not_in_tc{element_field_class}
3779 @bt_post_success_frozen{element_field_class}
3781 extern bt_field_class
*bt_field_class_array_static_create(
3782 bt_trace_class
*trace_class
,
3783 bt_field_class
*element_field_class
, uint64_t length
)
3788 Returns the length of the \bt_sarray_fc \bt_p{field_class}.
3790 See the \ref api-tir-fc-sarray-prop-len "length" property.
3792 @param[in] field_class
3793 Static array field class of which to get the length.
3796 Length of \bt_p{field_class}.
3798 @bt_pre_not_null{field_class}
3799 @bt_pre_is_sarray_fc{field_class}
3801 extern uint64_t bt_field_class_array_static_get_length(
3802 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
3807 @name Dynamic array field class
3813 Creates a \bt_darray_fc having the element field class
3814 \bt_p{element_field_class} from the trace class \bt_p{trace_class}.
3818 This function is only available when \bt_p{trace_class} was created
3819 from a \bt_self_comp which belongs to a trace processing \bt_graph
3820 with the effective \bt_mip version 0.
3822 To create a dynamic array field class from a trace class which was
3823 created from a self component which belongs to a trace processing
3824 graph with the effective MIP version 1, use
3825 bt_field_class_array_dynamic_without_length_field_location_create()
3826 or bt_field_class_array_dynamic_with_length_field_location_create().
3829 If \bt_p{length_field_class} is not \c NULL, then an instance of
3830 the created dynamic array field class has a linked length field.
3831 See \ref api-tir-fc-link "Fields with links to other fields"
3834 On success, the returned dynamic array field class has the following
3842 <td>\ref api-tir-fc-array-prop-elem-fc "Element field class"
3843 <td>\bt_p{element_field_class}
3845 <td>\ref api-tir-fc-darray-prop-len-fp "Length field path"
3847 \em None (if \bt_p{length_field_class} is not \c NULL, this
3848 property becomes available when the returned field class becomes
3849 part of an \bt_ev_cls or of a \bt_stream_cls)
3851 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3852 <td>Empty \bt_map_val
3855 @param[in] trace_class
3856 Trace class from which to create a dynamic array field class.
3857 @param[in] element_field_class
3858 Class of the element fields of the instances of the dynamic array
3859 field class to create.
3860 @param[in] length_field_class
3862 Class of a linked length field of an instance of the dynamic array
3863 field class to create.
3869 New dynamic array field class reference, or \c NULL on memory error.
3871 @bt_pre_not_null{trace_class}
3872 @bt_pre_tc_with_mip{trace_class, 0}
3873 @bt_pre_not_null{element_field_class}
3874 @bt_pre_fc_not_in_tc{element_field_class}
3876 <strong>If \bt_p{length_field_class} is not \c NULL</strong>,
3877 \bt_p{length_field_class} is an \bt_uint_fc.
3879 @bt_post_success_frozen{element_field_class}
3880 @bt_post_success_frozen{length_field_class}
3882 @sa bt_field_class_array_dynamic_without_length_field_location_create() —
3883 Creates a class of dynamic array field without a linked length field
3884 (\bt_mip version 1).
3885 @sa bt_field_class_array_dynamic_with_length_field_location_create() —
3886 Creates a class of dynamic array field with a linked length field
3887 (\bt_mip version 1).
3889 extern bt_field_class
*bt_field_class_array_dynamic_create(
3890 bt_trace_class
*trace_class
,
3891 bt_field_class
*element_field_class
,
3892 bt_field_class
*length_field_class
) __BT_NOEXCEPT
;
3896 Creates a \bt_darray_fc (instances without a linked length field)
3897 having the element field class \bt_p{element_field_class} from the
3898 trace class \bt_p{trace_class}.
3900 On success, the returned dynamic array field class has the following
3908 <td>\ref api-tir-fc-array-prop-elem-fc "Element field class"
3909 <td>\bt_p{element_field_class}
3911 <td>\ref api-tir-fc-darray-prop-len-fl "Length field location"
3915 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3916 <td>Empty \bt_map_val
3919 @param[in] trace_class
3920 Trace class from which to create a dynamic array field class.
3921 @param[in] element_field_class
3922 Class of the element fields of the instances of the dynamic array
3923 field class to create.
3926 New dynamic array field class reference (without a length field),
3927 or \c NULL on memory error.
3929 @bt_pre_not_null{trace_class}
3930 @bt_pre_tc_with_mip{trace_class, 1}
3931 @bt_pre_not_null{element_field_class}
3932 @bt_pre_fc_not_in_tc{element_field_class}
3934 @bt_post_success_frozen{element_field_class}
3936 @sa bt_field_class_array_dynamic_with_length_field_location_create() —
3937 Creates a class of dynamic array field with a linked length field.
3939 extern bt_field_class
*bt_field_class_array_dynamic_without_length_field_location_create(
3940 bt_trace_class
*trace_class
,
3941 bt_field_class
*element_field_class
);
3946 @name Dynamic array field class: instances with linked length field
3952 Creates a \bt_darray_fc (instances with a linked length field)
3953 having the element field class \bt_p{element_field_class} and the
3954 length \bt_field_loc \bt_p{length_field_location} from the
3955 trace class \bt_p{trace_class}.
3957 On success, the returned dynamic array field class has the following
3965 <td>\ref api-tir-fc-array-prop-elem-fc "Element field class"
3966 <td>\bt_p{element_field_class}
3968 <td>\ref api-tir-fc-darray-prop-len-fl "Length field location"
3970 \bt_p{length_field_location}.
3972 See \ref api-tir-fc-link "Fields with links to other fields"
3975 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
3976 <td>Empty \bt_map_val
3979 @param[in] trace_class
3980 Trace class from which to create a dynamic array field class.
3981 @param[in] element_field_class
3982 Class of the element fields of the instances of the dynamic array
3983 field class to create.
3984 @param[in] length_field_location
3985 Length field location of the dynamic array field class to create.
3988 New dynamic array field class reference (instances with a linked
3989 length field), or \c NULL on memory error.
3991 @bt_pre_not_null{trace_class}
3992 @bt_pre_tc_with_mip{trace_class, 1}
3993 @bt_pre_not_null{element_field_class}
3994 @bt_pre_fc_not_in_tc{element_field_class}
3995 @bt_pre_not_null{length_field_location}
3997 @bt_post_success_frozen{element_field_class}
3999 @sa bt_field_class_array_dynamic_without_length_field_location_create() —
4000 Creates a class of dynamic array field without a linked
4003 extern bt_field_class
*bt_field_class_array_dynamic_with_length_field_location_create(
4004 bt_trace_class
*trace_class
,
4005 bt_field_class
*element_field_class
,
4006 const bt_field_location
*length_field_location
);
4010 Borrows the length field path from the \bt_darray_fc (instances with
4011 a linked length field) \bt_p{field_class}.
4013 See the \ref api-tir-fc-darray-prop-len-fp "length field path" property.
4015 This property is only available when all the following are true:
4017 - \bt_p{field_class} was created with
4018 bt_field_class_array_dynamic_create() with \bt_p{length_field_class}
4019 set to an \bt_uint_fc (not \c NULL).
4021 - A \bt_struct_fc containing (recursively) \bt_p{field_class} is passed
4024 - bt_stream_class_set_packet_context_field_class()
4025 - bt_stream_class_set_event_common_context_field_class()
4026 - bt_event_class_set_specific_context_field_class()
4027 - bt_event_class_set_payload_field_class()
4029 In the meantime, this function returns \c NULL.
4031 @param[in] field_class
4032 Dynamic array field class from which to borrow the length
4036 Length field path of \bt_p{field_class}.
4038 @bt_pre_not_null{field_class}
4039 @bt_pre_is_darray_wl_fc{field_class}
4040 @bt_pre_fc_with_mip{field_class, 0}
4042 extern const bt_field_path
*
4043 bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const(
4044 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
4048 Borrows the length field location from the \bt_darray_fc (instances
4049 with a linked length field) \bt_p{field_class}.
4051 See the \ref api-tir-fc-darray-prop-len-fl "length field location"
4054 This property is only available when \bt_p{field_class} was created
4055 with bt_field_class_array_dynamic_with_length_field_location_create().
4057 @param[in] field_class
4058 Dynamic array field class from which to borrow the length
4062 Length field location of \bt_p{field_class}.
4064 @bt_pre_not_null{field_class}
4065 @bt_pre_is_darray_wl_fc{field_class}
4066 @bt_pre_fc_with_mip{field_class, 1}
4068 extern const bt_field_location
*
4069 bt_field_class_array_dynamic_with_length_field_borrow_length_field_location_const(
4070 const bt_field_class
*field_class
);
4075 @name Structure field class
4081 Creates a \bt_struct_fc from the trace class \bt_p{trace_class}.
4083 On success, the returned structure field class has the following
4091 <td>\ref api-tir-fc-struct-prop-members "Members"
4094 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
4095 <td>Empty \bt_map_val
4098 @param[in] trace_class
4099 Trace class from which to create a structure field class.
4102 New structure field class reference, or \c NULL on memory error.
4104 @bt_pre_not_null{trace_class}
4106 extern bt_field_class
*bt_field_class_structure_create(
4107 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
4111 Status codes for bt_field_class_structure_append_member().
4113 typedef enum bt_field_class_structure_append_member_status
{
4118 BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
4124 BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
4125 } bt_field_class_structure_append_member_status
;
4129 Appends a member to the \bt_struct_fc \bt_p{field_class} having the
4130 name \bt_p{name} and the field class \bt_p{member_field_class}.
4132 See the \ref api-tir-fc-struct-prop-members "members" property.
4134 @param[in] field_class
4135 Structure field class to which to append a member having
4136 the name \bt_p{name} and the field class \bt_p{member_field_class}.
4138 Name of the member to append to \bt_p{field_class} (copied).
4139 @param[in] member_field_class
4140 Field class of the member to append to \bt_p{field_class}.
4142 @retval #BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_OK
4144 @retval #BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_MEMORY_ERROR
4147 @bt_pre_not_null{field_class}
4148 @bt_pre_hot{field_class}
4149 @bt_pre_is_struct_fc{field_class}
4151 \bt_p{field_class} has no member with the name \bt_p{name}.
4152 @bt_pre_not_null{name}
4153 @bt_pre_not_null{member_field_class}
4154 @bt_pre_fc_not_in_tc{member_field_class}
4156 @bt_post_success_frozen{member_field_class}
4158 extern bt_field_class_structure_append_member_status
4159 bt_field_class_structure_append_member(
4160 bt_field_class
*field_class
,
4161 const char *name
, bt_field_class
*member_field_class
)
4166 Returns the number of members contained in the \bt_struct_fc
4169 See the \ref api-tir-fc-struct-prop-members "members" property.
4171 @param[in] field_class
4172 Structure field class of which to get the number of contained
4176 Number of contained members in \bt_p{field_class}.
4178 @bt_pre_not_null{field_class}
4179 @bt_pre_is_struct_fc{field_class}
4181 extern uint64_t bt_field_class_structure_get_member_count(
4182 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
4186 Borrows the member at index \bt_p{index} from the
4187 \bt_struct_fc \bt_p{field_class}.
4189 See the \ref api-tir-fc-struct-prop-members "members" property.
4191 @param[in] field_class
4192 Structure field class from which to borrow the member at
4195 Index of the member to borrow from \bt_p{field_class}.
4199 \em Borrowed reference of the member of
4200 \bt_p{field_class} at index \bt_p{index}.
4202 The returned pointer remains valid as long as \bt_p{field_class}
4206 @bt_pre_not_null{field_class}
4207 @bt_pre_is_struct_fc{field_class}
4209 \bt_p{index} is less than the number of members in
4210 \bt_p{field_class} (as returned by
4211 bt_field_class_structure_get_member_count()).
4213 @sa bt_field_class_structure_get_member_count() —
4214 Returns the number of members contained in a structure field class.
4215 @sa bt_field_class_structure_borrow_member_by_index_const() —
4216 \c const version of this function.
4218 extern bt_field_class_structure_member
*
4219 bt_field_class_structure_borrow_member_by_index(
4220 bt_field_class
*field_class
, uint64_t index
) __BT_NOEXCEPT
;
4224 Borrows the member at index \bt_p{index} from the
4225 \bt_struct_fc \bt_p{field_class} (\c const version).
4227 See bt_field_class_structure_borrow_member_by_index().
4229 extern const bt_field_class_structure_member
*
4230 bt_field_class_structure_borrow_member_by_index_const(
4231 const bt_field_class
*field_class
, uint64_t index
)
4236 Borrows the member having the name \bt_p{name} from the
4237 \bt_struct_fc \bt_p{field_class}.
4239 See the \ref api-tir-fc-struct-prop-members "members" property.
4241 If there's no member having the name \bt_p{name} in
4242 \bt_p{field_class}, this function returns \c NULL.
4244 @param[in] field_class
4245 Structure field class from which to borrow the member having the
4248 Name of the member to borrow from \bt_p{field_class}.
4252 \em Borrowed reference of the member of
4253 \bt_p{field_class} having the name \bt_p{name}, or \c NULL
4256 The returned pointer remains valid as long as \bt_p{field_class}
4260 @bt_pre_not_null{field_class}
4261 @bt_pre_is_struct_fc{field_class}
4262 @bt_pre_not_null{name}
4264 @sa bt_field_class_structure_borrow_member_by_name_const() —
4265 \c const version of this function.
4267 extern bt_field_class_structure_member
*
4268 bt_field_class_structure_borrow_member_by_name(
4269 bt_field_class
*field_class
, const char *name
) __BT_NOEXCEPT
;
4273 Borrows the member having the name \bt_p{name} from the
4274 \bt_struct_fc \bt_p{field_class} (\c const version).
4276 See bt_field_class_structure_borrow_member_by_name().
4278 extern const bt_field_class_structure_member
*
4279 bt_field_class_structure_borrow_member_by_name_const(
4280 const bt_field_class
*field_class
, const char *name
)
4286 @name Structure field class member
4291 @typedef struct bt_field_class_structure_member bt_field_class_structure_member;
4294 Structure field class member.
4299 Returns the name of the \bt_struct_fc member \bt_p{member}.
4301 See the \ref api-tir-fc-struct-prop-members "members" property.
4304 Structure field class member of which to get the name.
4308 Name of \bt_p{member}.
4310 The returned pointer remains valid as long as \bt_p{member} exists.
4313 @bt_pre_not_null{member}
4315 extern const char *bt_field_class_structure_member_get_name(
4316 const bt_field_class_structure_member
*member
) __BT_NOEXCEPT
;
4320 Borrows the field class from the \bt_struct_fc member
4323 See the \ref api-tir-fc-struct-prop-members "members" property.
4326 Structure field class member from which to borrow the field class.
4329 Field class of \bt_p{member}.
4331 @bt_pre_not_null{member}
4333 @sa bt_field_class_structure_member_borrow_field_class_const() —
4334 \c const version of this function.
4336 extern bt_field_class
*
4337 bt_field_class_structure_member_borrow_field_class(
4338 bt_field_class_structure_member
*member
) __BT_NOEXCEPT
;
4342 Borrows the field class from the \bt_struct_fc member
4343 \bt_p{member} (\c const version).
4345 See bt_field_class_structure_member_borrow_field_class().
4347 extern const bt_field_class
*
4348 bt_field_class_structure_member_borrow_field_class_const(
4349 const bt_field_class_structure_member
*member
) __BT_NOEXCEPT
;
4353 Sets the user attributes of the \bt_struct_fc member \bt_p{member}
4354 to \bt_p{user_attributes}.
4356 See the \ref api-tir-fc-struct-prop-members "members" property.
4359 When you append a member to a structure field class with
4360 bt_field_class_structure_append_member(), the member's
4361 initial user attributes is an empty \bt_map_val. Therefore you can
4363 bt_field_class_structure_member_borrow_user_attributes() and fill it
4364 directly instead of setting a new one with this function.
4367 Structure field class member of which to set the user attributes to
4368 \bt_p{user_attributes}.
4369 @param[in] user_attributes
4370 New user attributes of \bt_p{member}.
4372 @bt_pre_not_null{member}
4374 @bt_pre_not_null{user_attributes}
4375 @bt_pre_is_map_val{user_attributes}
4377 @sa bt_field_class_structure_member_borrow_user_attributes() —
4378 Borrows the user attributes of a structure field class member.
4380 extern void bt_field_class_structure_member_set_user_attributes(
4381 bt_field_class_structure_member
*member
,
4382 const bt_value
*user_attributes
) __BT_NOEXCEPT
;
4386 Borrows the user attributes of the \bt_struct_fc member
4389 See the \ref api-tir-fc-struct-prop-members "members" property.
4392 When you append a member to a structure field class with
4393 bt_field_class_structure_append_member(), the member's
4394 initial user attributes is an empty \bt_map_val.
4397 Structure field class member from which to borrow the user
4401 User attributes of \bt_p{member} (a \bt_map_val).
4403 @bt_pre_not_null{member}
4405 @sa bt_field_class_structure_member_set_user_attributes() —
4406 Sets the user attributes of a structure field class member.
4407 @sa bt_field_class_structure_member_borrow_user_attributes_const() —
4408 \c const version of this function.
4411 bt_field_class_structure_member_borrow_user_attributes(
4412 bt_field_class_structure_member
*member
) __BT_NOEXCEPT
;
4416 Borrows the user attributes of the \bt_struct_fc member
4417 \bt_p{member} (\c const version).
4419 See bt_field_class_structure_member_borrow_user_attributes().
4421 extern const bt_value
*
4422 bt_field_class_structure_member_borrow_user_attributes_const(
4423 const bt_field_class_structure_member
*member
) __BT_NOEXCEPT
;
4428 @name Option field class
4434 Borrows the optional field class from the \bt_opt_fc
4437 See the \ref api-tir-fc-opt-prop-fc "optional field class" property.
4439 @param[in] field_class
4440 Option field class from which to borrow the optional field class.
4443 Optional field class of \bt_p{field_class}.
4445 @bt_pre_not_null{field_class}
4446 @bt_pre_is_opt_fc{field_class}
4448 @sa bt_field_class_option_borrow_field_class_const() —
4449 \c const version of this function.
4451 extern bt_field_class
*bt_field_class_option_borrow_field_class(
4452 bt_field_class
*field_class
) __BT_NOEXCEPT
;
4456 Borrows the optional field class from the \bt_opt_fc
4457 \bt_p{field_class} (\c const version).
4459 See bt_field_class_option_borrow_field_class().
4461 extern const bt_field_class
*
4462 bt_field_class_option_borrow_field_class_const(
4463 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
4468 @name Option field class: instances without a linked selector field
4474 Creates an \bt_opt_fc (instances without a linked selector field)
4475 having the optional field class \bt_p{optional_field_class} from the
4476 trace class \bt_p{trace_class}.
4480 This function is only available when \bt_p{trace_class} was created
4481 from a \bt_self_comp which belongs to a trace processing \bt_graph
4482 with the effective \bt_mip version 0.
4484 To create a similar option field class from a trace class which was
4485 created from a self component which belongs to a trace processing
4486 graph with the effective MIP version 1, use
4487 bt_field_class_option_without_selector_field_location_create().
4490 On success, the returned option field class has the following property
4498 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
4499 <td>\bt_p{optional_field_class}
4501 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
4502 <td>Empty \bt_map_val
4505 @param[in] trace_class
4506 Trace class from which to create an option field class.
4507 @param[in] optional_field_class
4508 Class of the optional fields of the instances of the option field
4512 New option field class reference, or \c NULL on memory error.
4514 @bt_pre_not_null{trace_class}
4515 @bt_pre_tc_with_mip{trace_class, 0}
4516 @bt_pre_not_null{optional_field_class}
4517 @bt_pre_fc_not_in_tc{optional_field_class}
4519 @bt_post_success_frozen{optional_field_class}
4521 @sa bt_field_class_option_without_selector_field_location_create() —
4522 Creates a class of option field without a linked selector field
4523 (\bt_mip version 1).
4525 extern bt_field_class
*bt_field_class_option_without_selector_create(
4526 bt_trace_class
*trace_class
,
4527 bt_field_class
*optional_field_class
) __BT_NOEXCEPT
;
4531 Creates an \bt_opt_fc (instances without a linked selector
4532 field) having the optional field class \bt_p{optional_field_class}
4533 from the trace class \bt_p{trace_class}.
4535 On success, the returned option field class has the following property
4543 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
4544 <td>\bt_p{optional_field_class}
4546 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
4547 <td>Empty \bt_map_val
4550 @param[in] trace_class
4551 Trace class from which to create an option field class.
4552 @param[in] optional_field_class
4553 Class of the optional fields of the instances of the option field
4557 New option field class reference, or \c NULL on memory error.
4559 @bt_pre_not_null{trace_class}
4560 @bt_pre_tc_with_mip{trace_class, 1}
4561 @bt_pre_not_null{optional_field_class}
4562 @bt_pre_fc_not_in_tc{optional_field_class}
4564 @bt_post_success_frozen{optional_field_class}
4566 @sa bt_field_class_option_with_selector_field_location_bool_create() —
4567 Creates a class of option field with a linked boolean selector field.
4568 @sa bt_field_class_option_with_selector_field_location_integer_unsigned_create() —
4569 Creates a class of option field with a linked unsigned integer
4571 @sa bt_field_class_option_with_selector_field_location_integer_signed_create() —
4572 Creates a class of option field with a linked signed integer
4575 extern bt_field_class
*bt_field_class_option_without_selector_field_location_create(
4576 bt_trace_class
*trace_class
,
4577 bt_field_class
*optional_field_class
) __BT_NOEXCEPT
;
4582 @name Option field class: instances with a linked selector field
4588 Borrows the selector field path from the \bt_opt_fc (instances
4589 with a linked selector field) \bt_p{field_class}.
4591 See the \ref api-tir-fc-opt-prop-sel-fp "selector field path" property.
4593 This property is only available when all the following are true:
4595 - \bt_p{field_class} was created with
4596 bt_field_class_option_with_selector_field_bool_create(),
4597 bt_field_class_option_with_selector_field_integer_unsigned_create(),
4598 or bt_field_class_option_with_selector_field_integer_signed_create().
4600 - A \bt_struct_fc containing (recursively) \bt_p{field_class} is passed
4603 - bt_stream_class_set_packet_context_field_class()
4604 - bt_stream_class_set_event_common_context_field_class()
4605 - bt_event_class_set_specific_context_field_class()
4606 - bt_event_class_set_payload_field_class()
4608 In the meantime, this function returns \c NULL.
4610 @param[in] field_class
4611 Option field class from which to borrow the selector field path.
4614 Selector field path of \bt_p{field_class}.
4616 @bt_pre_not_null{field_class}
4617 @bt_pre_is_opt_ws_fc{field_class}
4618 @bt_pre_fc_with_mip{field_class, 0}
4620 extern const bt_field_path
*
4621 bt_field_class_option_with_selector_field_borrow_selector_field_path_const(
4622 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
4626 Borrows the selector field location from the \bt_opt_fc (instances
4627 with a linked selector field) \bt_p{field_class}.
4629 See the \ref api-tir-fc-opt-prop-sel-fl "selector field location"
4632 This property is only available when \bt_p{field_class} was created
4633 with bt_field_class_option_with_selector_field_location_bool_create(),
4636 @param[in] field_class
4637 Option field class from which to borrow the selector field location.
4640 Selector field location of \bt_p{field_class}.
4642 @bt_pre_not_null{field_class}
4643 @bt_pre_is_opt_ws_fc{field_class}
4644 @bt_pre_fc_with_mip{field_class, 1}
4646 extern const bt_field_location
*
4647 bt_field_class_option_with_selector_field_borrow_selector_field_location_const(
4648 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
4653 @name Option field class: instances with a linked boolean selector field
4659 Creates an \bt_opt_fc (instances with a linked boolean selector
4660 field) having the optional field class \bt_p{optional_field_class}
4661 from the trace class \bt_p{trace_class}.
4665 This function is only available when \bt_p{trace_class} was created
4666 from a \bt_self_comp which belongs to a trace processing \bt_graph
4667 with the effective \bt_mip version 0.
4669 To create a similar option field class from a trace class which was
4670 created from a self component which belongs to a trace processing
4671 graph with the effective MIP version 1, use
4672 bt_field_class_option_with_selector_field_location_bool_create().
4675 On success, the returned option field class has the following property
4683 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
4684 <td>\bt_p{optional_field_class}
4686 <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
4688 \em None (this property becomes available when the returned field
4689 class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
4691 <td>\ref api-tir-fc-opt-prop-sel-rev "Selector is reversed?"
4694 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
4695 <td>Empty \bt_map_val
4698 @param[in] trace_class
4699 Trace class from which to create an option field class.
4700 @param[in] optional_field_class
4701 Class of the optional fields of the instances of the option field
4703 @param[in] selector_field_class
4704 Class of a linked boolean selector field of an instance of the
4705 option field class to create.
4708 New option field class reference, or \c NULL on memory error.
4710 @bt_pre_not_null{trace_class}
4711 @bt_pre_tc_with_mip{trace_class, 0}
4712 @bt_pre_not_null{optional_field_class}
4713 @bt_pre_fc_not_in_tc{optional_field_class}
4714 @bt_pre_not_null{selector_field_class}
4716 \bt_p{selector_field_class} is a \bt_bool_fc.
4718 @bt_post_success_frozen{optional_field_class}
4719 @bt_post_success_frozen{selector_field_class}
4721 @sa bt_field_class_option_with_selector_field_location_bool_create() —
4722 Creates a class of option field with a linked boolean selector field
4723 (\bt_mip version 1).
4725 extern bt_field_class
*bt_field_class_option_with_selector_field_bool_create(
4726 bt_trace_class
*trace_class
,
4727 bt_field_class
*optional_field_class
,
4728 bt_field_class
*selector_field_class
) __BT_NOEXCEPT
;
4732 Creates an \bt_opt_fc (instances with a linked boolean selector
4733 field) having the optional field class \bt_p{optional_field_class}
4734 and the selector \bt_field_loc \bt_p{selector_field_location} from
4735 the trace class \bt_p{trace_class}.
4737 On success, the returned option field class has the following property
4745 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
4746 <td>\bt_p{optional_field_class}
4748 <td>\ref api-tir-fc-opt-prop-sel-fl "Selector field location"
4750 \bt_p{selector_field_location}.
4752 See \ref api-tir-fc-link "Fields with links to other fields"
4755 <td>\ref api-tir-fc-opt-prop-sel-rev "Selector is reversed?"
4758 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
4759 <td>Empty \bt_map_val
4762 @param[in] trace_class
4763 Trace class from which to create an option field class.
4764 @param[in] optional_field_class
4765 Class of the optional fields of the instances of the option field
4767 @param[in] selector_field_location
4768 Selector field location of the option field class to create.
4771 New option field class reference, or \c NULL on memory error.
4773 @bt_pre_not_null{trace_class}
4774 @bt_pre_tc_with_mip{trace_class, 1}
4775 @bt_pre_not_null{optional_field_class}
4776 @bt_pre_fc_not_in_tc{optional_field_class}
4777 @bt_pre_not_null{selector_field_location}
4779 @bt_post_success_frozen{optional_field_class}
4780 @bt_post_success_frozen{selector_field_class}
4782 @sa bt_field_class_option_without_selector_field_location_create() —
4783 Creates a class of option field without a linked selector field.
4784 @sa bt_field_class_option_with_selector_field_location_integer_unsigned_create() —
4785 Creates a class of option field with a linked unsigned integer
4787 @sa bt_field_class_option_with_selector_field_location_integer_signed_create() —
4788 Creates a class of option field with a linked signed integer
4791 extern bt_field_class
*bt_field_class_option_with_selector_field_location_bool_create(
4792 bt_trace_class
*trace_class
,
4793 bt_field_class
*optional_field_class
,
4794 const bt_field_location
*selector_field_location
) __BT_NOEXCEPT
;
4798 Sets whether or not the selector of the \bt_opt_fc (with a boolean
4799 selector field) \bt_p{field_class} is reversed.
4801 See the \ref api-tir-fc-opt-prop-sel-rev "selector is reversed?"
4804 @param[in] field_class
4805 Option field class of which to set whether or not its selector
4807 @param[in] selector_is_reversed
4808 #BT_TRUE to make \bt_p{field_class} have a reversed selector.
4810 @bt_pre_not_null{field_class}
4811 @bt_pre_hot{field_class}
4812 @bt_pre_is_opt_wbs_fc{field_class}
4814 @sa bt_field_class_option_with_selector_field_bool_selector_is_reversed() —
4815 Returns whether or not the selector of an option field class (with
4816 a boolean selector field) is reversed.
4819 bt_field_class_option_with_selector_field_bool_set_selector_is_reversed(
4820 bt_field_class
*field_class
, bt_bool selector_is_reversed
)
4825 Returns whether or not the selector of the
4826 \bt_opt_fc (with a boolean selector field) is reversed.
4828 See the \ref api-tir-fc-opt-prop-sel-rev "selector is reversed?"
4831 @param[in] field_class
4832 Option field class of which to get whether or not its selector is
4836 #BT_TRUE if the selector of \bt_p{field_class} is reversed.
4838 @bt_pre_not_null{field_class}
4839 @bt_pre_is_opt_wbs_fc{field_class}
4841 @sa bt_field_class_option_with_selector_field_bool_set_selector_is_reversed() —
4842 Sets whether or not the selector of an option field class (with
4843 a boolean selector field) is reversed.
4846 bt_field_class_option_with_selector_field_bool_selector_is_reversed(
4847 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
4852 @name Option field class: instances with a linked unsigned integer selector field
4858 Creates an \bt_opt_fc (instances with a linked unsigned integer
4859 selector field) having the optional field class
4860 \bt_p{optional_field_class} from the trace class \bt_p{trace_class}.
4864 This function is only available when \bt_p{trace_class} was created
4865 from a \bt_self_comp which belongs to a trace processing \bt_graph
4866 with the effective \bt_mip version 0.
4868 To create a similar option field class from a trace class which was
4869 created from a self component which belongs to a trace processing
4870 graph with the effective MIP version 1, use
4871 bt_field_class_option_with_selector_field_location_integer_unsigned_create().
4874 On success, the returned option field class has the following property
4882 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
4883 <td>\bt_p{optional_field_class}
4885 <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
4887 \em None (this property becomes available when the returned field
4888 class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
4890 <td>\ref api-tir-fc-opt-prop-uint-rs "Selector's unsigned integer ranges"
4893 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
4894 <td>Empty \bt_map_val
4897 @param[in] trace_class
4898 Trace class from which to create an option field class.
4899 @param[in] optional_field_class
4900 Class of the optional fields of the instances of the option field
4902 @param[in] selector_field_class
4903 Linked selector field class of the option field class to create.
4905 Selector's unsigned integer ranges of the option field class to
4909 New option field class reference, or \c NULL on memory error.
4911 @bt_pre_not_null{trace_class}
4912 @bt_pre_tc_with_mip{trace_class, 0}
4913 @bt_pre_not_null{optional_field_class}
4914 @bt_pre_fc_not_in_tc{optional_field_class}
4915 @bt_pre_not_null{selector_field_class}
4917 \bt_p{selector_field_class} is an \bt_uint_fc.
4918 @bt_pre_not_null{ranges}
4920 \bt_p{ranges} contains one or more \bt_p_uint_rg.
4922 @bt_post_success_frozen{optional_field_class}
4923 @bt_post_success_frozen{selector_field_class}
4924 @bt_post_success_frozen{ranges}
4926 @sa bt_field_class_option_with_selector_field_location_integer_unsigned_create() —
4927 Creates a class of option field with a linked unsigned integer
4928 selector field (\bt_mip version 1).
4930 extern bt_field_class
*
4931 bt_field_class_option_with_selector_field_integer_unsigned_create(
4932 bt_trace_class
*trace_class
,
4933 bt_field_class
*optional_field_class
,
4934 bt_field_class
*selector_field_class
,
4935 const bt_integer_range_set_unsigned
*ranges
)
4940 Creates an \bt_opt_fc (instances with a linked unsigned integer
4941 selector field) having the optional field class
4942 \bt_p{optional_field_class} and the selector \bt_field_loc
4943 \bt_p{selector_field_location} from the trace class
4946 On success, the returned option field class has the following property
4954 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
4955 <td>\bt_p{optional_field_class}
4957 <td>\ref api-tir-fc-opt-prop-sel-fl "Selector field location"
4959 \bt_p{selector_field_location}.
4961 See \ref api-tir-fc-link "Fields with links to other fields"
4964 <td>\ref api-tir-fc-opt-prop-uint-rs "Selector's unsigned integer ranges"
4967 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
4968 <td>Empty \bt_map_val
4971 @param[in] trace_class
4972 Trace class from which to create an option field class.
4973 @param[in] optional_field_class
4974 Class of the optional fields of the instances of the option field
4976 @param[in] selector_field_location
4977 Selector field location of the option field class to create.
4979 Selector's unsigned integer ranges of the option field class to
4983 New option field class reference, or \c NULL on memory error.
4985 @bt_pre_not_null{trace_class}
4986 @bt_pre_tc_with_mip{trace_class, 1}
4987 @bt_pre_not_null{optional_field_class}
4988 @bt_pre_fc_not_in_tc{optional_field_class}
4989 @bt_pre_not_null{selector_field_location}
4990 @bt_pre_not_null{ranges}
4992 \bt_p{ranges} contains one or more \bt_p_uint_rg.
4994 @bt_post_success_frozen{optional_field_class}
4995 @bt_post_success_frozen{ranges}
4997 @sa bt_field_class_option_without_selector_field_location_create() —
4998 Creates a class of option field without a linked selector field.
4999 @sa bt_field_class_option_with_selector_field_location_bool_create() —
5000 Creates a class of option field with a linked boolean selector field.
5001 @sa bt_field_class_option_with_selector_field_location_integer_signed_create() —
5002 Creates a class of option field with a linked signed integer
5005 extern bt_field_class
*
5006 bt_field_class_option_with_selector_field_location_integer_unsigned_create(
5007 bt_trace_class
*trace_class
,
5008 bt_field_class
*optional_field_class
,
5009 const bt_field_location
*selector_field_location
,
5010 const bt_integer_range_set_unsigned
*ranges
) __BT_NOEXCEPT
;
5014 Borrows the \bt_p_uint_rg from the \bt_opt_fc (with an unsigned
5015 integer selector field) \bt_p{field_class}.
5018 \ref api-tir-fc-opt-prop-uint-rs "selector's unsigned integer ranges"
5021 @param[in] field_class
5022 Option field class from which to borrow the unsigned integer ranges.
5025 Unsigned integer ranges of \bt_p{field_class}.
5027 @bt_pre_not_null{field_class}
5028 @bt_pre_is_opt_wuis_fc{field_class}
5030 extern const bt_integer_range_set_unsigned
*
5031 bt_field_class_option_with_selector_field_integer_unsigned_borrow_selector_ranges_const(
5032 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
5037 @name Option field class: instances with a linked signed integer selector field
5043 Creates an \bt_opt_fc (instances with a linked signed integer
5044 selector field) having the optional field class
5045 \bt_p{optional_field_class} from the trace class \bt_p{trace_class}.
5049 This function is only available when \bt_p{trace_class} was created
5050 from a \bt_self_comp which belongs to a trace processing \bt_graph
5051 with the effective \bt_mip version 0.
5053 To create a similar option field class from a trace class which was
5054 created from a self component which belongs to a trace processing
5055 graph with the effective MIP version 1, use
5056 bt_field_class_option_with_selector_field_location_integer_signed_create().
5059 On success, the returned option field class has the following property
5067 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
5068 <td>\bt_p{optional_field_class}
5070 <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
5072 \em None (this property becomes available when the returned field
5073 class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
5075 <td>\ref api-tir-fc-opt-prop-sint-rs "Selector's signed integer ranges"
5078 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
5079 <td>Empty \bt_map_val
5082 @param[in] trace_class
5083 Trace class from which to create an option field class.
5084 @param[in] optional_field_class
5085 Class of the optional fields of the instances of the option field
5087 @param[in] selector_field_class
5088 Linked selector field class of the option field class to create.
5090 Selector's signed integer ranges of the option field class to
5094 New option field class reference, or \c NULL on memory error.
5096 @bt_pre_not_null{trace_class}
5097 @bt_pre_tc_with_mip{trace_class, 0}
5098 @bt_pre_not_null{optional_field_class}
5099 @bt_pre_fc_not_in_tc{optional_field_class}
5100 @bt_pre_not_null{selector_field_class}
5102 \bt_p{selector_field_class} is an \bt_uint_fc.
5103 @bt_pre_not_null{ranges}
5105 \bt_p{ranges} contains one or more \bt_p_uint_rg.
5107 @bt_post_success_frozen{optional_field_class}
5108 @bt_post_success_frozen{selector_field_class}
5109 @bt_post_success_frozen{ranges}
5111 @sa bt_field_class_option_with_selector_field_location_integer_signed_create() —
5112 Creates an option field class with a linked signed integer
5113 selector field (\bt_mip version 1).
5115 extern bt_field_class
*
5116 bt_field_class_option_with_selector_field_integer_signed_create(
5117 bt_trace_class
*trace_class
,
5118 bt_field_class
*optional_field_class
,
5119 bt_field_class
*selector_field_class
,
5120 const bt_integer_range_set_signed
*ranges
) __BT_NOEXCEPT
;
5124 Creates an \bt_opt_fc (instances with a linked signed integer
5125 selector field) having the optional field class
5126 \bt_p{optional_field_class} and the selector \bt_field_loc
5127 \bt_p{selector_field_location} from the trace class
5130 On success, the returned option field class has the following property
5138 <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
5139 <td>\bt_p{optional_field_class}
5141 <td>\ref api-tir-fc-opt-prop-sel-fl "Selector field location"
5143 \bt_p{selector_field_location}.
5145 See \ref api-tir-fc-link "Fields with links to other fields"
5148 <td>\ref api-tir-fc-opt-prop-uint-rs "Selector's signed integer ranges"
5151 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
5152 <td>Empty \bt_map_val
5155 @param[in] trace_class
5156 Trace class from which to create an option field class.
5157 @param[in] optional_field_class
5158 Class of the optional fields of the instances of the option field
5160 @param[in] selector_field_location
5161 Selector field location of the option field class to create.
5163 Selector's signed integer ranges of the option field class to
5167 New option field class reference, or \c NULL on memory error.
5169 @bt_pre_not_null{trace_class}
5170 @bt_pre_tc_with_mip{trace_class, 1}
5171 @bt_pre_not_null{optional_field_class}
5172 @bt_pre_fc_not_in_tc{optional_field_class}
5173 @bt_pre_not_null{selector_field_location}
5174 @bt_pre_not_null{ranges}
5176 \bt_p{ranges} contains one or more \bt_p_uint_rg.
5178 @bt_post_success_frozen{optional_field_class}
5179 @bt_post_success_frozen{ranges}
5181 @sa bt_field_class_variant_without_selector_field_location_create() —
5182 Creates a class of option field without a linked selector field.
5183 @sa bt_field_class_option_with_selector_field_location_bool_create() —
5184 Creates a class of option field with a linked boolean selector field.
5185 @sa bt_field_class_option_with_selector_field_location_integer_unsigned_create() —
5186 Creates a class of option field with a linked unsigned integer
5189 extern bt_field_class
*
5190 bt_field_class_option_with_selector_field_location_integer_signed_create(
5191 bt_trace_class
*trace_class
,
5192 bt_field_class
*optional_field_class
,
5193 const bt_field_location
*selector_field_class
,
5194 const bt_integer_range_set_signed
*ranges
) __BT_NOEXCEPT
;
5198 Borrows the \bt_p_sint_rg from the \bt_opt_fc (with a signed
5199 integer selector field) \bt_p{field_class}.
5202 \ref api-tir-fc-opt-prop-sint-rs "selector's signed integer ranges"
5205 @param[in] field_class
5206 Option field class from which to borrow the signed integer ranges.
5209 Signed integer ranges of \bt_p{field_class}.
5211 @bt_pre_not_null{field_class}
5212 @bt_pre_is_opt_wsis_fc{field_class}
5214 extern const bt_integer_range_set_signed
*
5215 bt_field_class_option_with_selector_field_integer_signed_borrow_selector_ranges_const(
5216 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
5221 @name Variant field class
5227 Creates an empty \bt_var_fc from the trace class \bt_p{trace_class}.
5231 This function is only available when \bt_p{trace_class} was created
5232 from a \bt_self_comp which belongs to a trace processing \bt_graph
5233 with the effective \bt_mip version 0.
5235 To create a variant field class from a trace class which was
5236 created from a self component which belongs to a trace processing
5237 graph with the effective MIP version 1, use
5238 bt_field_class_variant_without_selector_field_location_create(),
5239 bt_field_class_variant_with_selector_field_location_integer_unsigned_create(),
5240 or bt_field_class_variant_with_selector_field_location_integer_signed_create().
5243 If \bt_p{selector_field_class} is not \c NULL, then an instance of
5244 the created variant field class has a linked selector field.
5245 See \ref api-tir-fc-link "Fields with links to other fields"
5248 On success, the returned variant field class has the following
5256 <td>\ref api-tir-fc-var-prop-sel-fp "Selector field path"
5258 \em None (if \bt_p{selector_field_class} is not \c NULL, this
5259 property becomes available when the returned field class becomes
5260 part of an \bt_ev_cls or of a \bt_stream_cls)
5262 <td>\ref api-tir-fc-var-prop-opts "Options"
5265 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
5266 <td>Empty \bt_map_val
5269 @param[in] trace_class
5270 Trace class from which to create a variant field class.
5271 @param[in] selector_field_class
5273 Class of a linked selector field of an instance of the variant field
5280 New variant field class reference, or \c NULL on memory error.
5282 @bt_pre_not_null{trace_class}
5283 @bt_pre_tc_with_mip{trace_class, 0}
5285 <strong>If \bt_p{selector_field_class} is not \c NULL</strong>,
5286 \bt_p{selector_field_class} is an \bt_int_fc.
5288 @bt_post_success_frozen{element_field_class}
5289 @bt_post_success_frozen{selector_field_class}
5291 @sa bt_field_class_variant_without_selector_field_location_create() —
5292 Creates a class of variant field without a linked selector field
5293 (\bt_mip version 1).
5294 @sa bt_field_class_variant_with_selector_field_location_integer_unsigned_create() —
5295 Creates a class of variant field with a linked unsigned integer
5296 selector field (\bt_mip version 1).
5297 @sa bt_field_class_variant_with_selector_field_location_integer_signed_create() —
5298 Creates a class of variant field with a linked signed integer
5299 selector field (\bt_mip version 1).
5301 extern bt_field_class
*bt_field_class_variant_create(
5302 bt_trace_class
*trace_class
,
5303 bt_field_class
*selector_field_class
) __BT_NOEXCEPT
;
5307 Returns the number of options contained in the \bt_var_fc
5310 See the \ref api-tir-fc-var-prop-opts "options" property.
5312 @param[in] field_class
5313 Variant field class of which to get the number of contained
5317 Number of contained options in \bt_p{field_class}.
5319 @bt_pre_not_null{field_class}
5320 @bt_pre_is_var_fc{field_class}
5322 extern uint64_t bt_field_class_variant_get_option_count(
5323 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
5327 Borrows the option at index \bt_p{index} from the
5328 \bt_var_fc \bt_p{field_class}.
5330 See the \ref api-tir-fc-var-prop-opts "options" property.
5332 @param[in] field_class
5333 Variant field class from which to borrow the option at
5336 Index of the option to borrow from \bt_p{field_class}.
5340 \em Borrowed reference of the option of
5341 \bt_p{field_class} at index \bt_p{index}.
5343 The returned pointer remains valid as long as \bt_p{field_class}
5347 @bt_pre_not_null{field_class}
5348 @bt_pre_is_var_fc{field_class}
5350 \bt_p{index} is less than the number of options in
5351 \bt_p{field_class} (as returned by
5352 bt_field_class_variant_get_option_count()).
5354 @sa bt_field_class_variant_get_option_count() —
5355 Returns the number of options contained in a variant field class.
5356 @sa bt_field_class_variant_borrow_option_by_index_const() —
5357 \c const version of this function.
5359 extern bt_field_class_variant_option
*
5360 bt_field_class_variant_borrow_option_by_index(
5361 bt_field_class
*field_class
, uint64_t index
) __BT_NOEXCEPT
;
5365 Borrows the option at index \bt_p{index} from the
5366 \bt_var_fc \bt_p{field_class} (\c const version).
5368 See bt_field_class_variant_borrow_option_by_index().
5370 extern const bt_field_class_variant_option
*
5371 bt_field_class_variant_borrow_option_by_index_const(
5372 const bt_field_class
*field_class
, uint64_t index
)
5377 Borrows the option having the name \bt_p{name} from the
5378 \bt_var_fc \bt_p{field_class}.
5380 See the \ref api-tir-fc-var-prop-opts "options" property.
5382 If there's no option having the name \bt_p{name} in
5383 \bt_p{field_class}, this function returns \c NULL.
5385 @param[in] field_class
5386 Variant field class from which to borrow the option having the
5389 Name of the option to borrow from \bt_p{field_class}.
5393 \em Borrowed reference of the option of
5394 \bt_p{field_class} having the name \bt_p{name}, or \c NULL
5397 The returned pointer remains valid as long as \bt_p{field_class}
5401 @bt_pre_not_null{field_class}
5402 @bt_pre_is_var_fc{field_class}
5403 @bt_pre_not_null{name}
5405 @sa bt_field_class_variant_borrow_option_by_name_const() —
5406 \c const version of this function.
5408 extern bt_field_class_variant_option
*
5409 bt_field_class_variant_borrow_option_by_name(
5410 bt_field_class
*field_class
, const char *name
) __BT_NOEXCEPT
;
5414 Borrows the option having the name \bt_p{name} from the
5415 \bt_var_fc \bt_p{field_class} (\c const version).
5417 See bt_field_class_variant_borrow_option_by_name().
5419 extern const bt_field_class_variant_option
*
5420 bt_field_class_variant_borrow_option_by_name_const(
5421 const bt_field_class
*field_class
, const char *name
)
5427 @name Variant field class option
5432 @typedef struct bt_field_class_variant_option bt_field_class_variant_option;
5435 Variant field class option.
5440 Returns the name of the \bt_var_fc option \bt_p{option}.
5442 See the \ref api-tir-fc-var-prop-opts "options" property.
5444 This function may return \c NULL when the following are true:
5446 - The variant field class containing \bt_p{option} was created from a
5447 \bt_trace_cls which was created from a \bt_comp which belongs
5448 to a trace processing \bt_graph with the effective
5449 \bt_mip version 1.
5451 - \bt_p{option} has no name.
5454 Variant field class option of which to get the name.
5458 Name of \bt_p{option}, or \c NULL if none
5459 (possible under MIP 1).
5461 The returned pointer remains valid as long as \bt_p{option} exists.
5464 @bt_pre_not_null{option}
5466 extern const char *bt_field_class_variant_option_get_name(
5467 const bt_field_class_variant_option
*option
) __BT_NOEXCEPT
;
5471 Borrows the field class from the \bt_var_fc option
5474 See the \ref api-tir-fc-var-prop-opts "options" property.
5477 Variant field class option from which to borrow the field class.
5480 Field class of \bt_p{option}.
5482 @bt_pre_not_null{option}
5484 @sa bt_field_class_variant_option_borrow_field_class_const() —
5485 \c const version of this function.
5487 extern bt_field_class
*bt_field_class_variant_option_borrow_field_class(
5488 bt_field_class_variant_option
*option
) __BT_NOEXCEPT
;
5492 Borrows the field class from the \bt_var_fc option
5493 \bt_p{option} (\c const version).
5495 See bt_field_class_variant_option_borrow_field_class().
5497 extern const bt_field_class
*
5498 bt_field_class_variant_option_borrow_field_class_const(
5499 const bt_field_class_variant_option
*option
) __BT_NOEXCEPT
;
5503 Sets the user attributes of the \bt_var_fc option \bt_p{option}
5504 to \bt_p{user_attributes}.
5506 See the \ref api-tir-fc-var-prop-opts "options" property.
5509 When you append an option to a variant field class with
5510 bt_field_class_variant_without_selector_append_option(),
5511 bt_field_class_variant_with_selector_field_integer_unsigned_append_option(),
5513 bt_field_class_variant_with_selector_field_integer_signed_append_option(),
5514 the option's initial user attributes is an empty \bt_map_val.
5515 Therefore you can borrow it with
5516 bt_field_class_variant_option_borrow_user_attributes() and fill it
5517 directly instead of setting a new one with this function.
5520 Variant field class option of which to set the user attributes to
5521 \bt_p{user_attributes}.
5522 @param[in] user_attributes
5523 New user attributes of \bt_p{option}.
5525 @bt_pre_not_null{option}
5527 @bt_pre_not_null{user_attributes}
5528 @bt_pre_is_map_val{user_attributes}
5530 @sa bt_field_class_variant_option_borrow_user_attributes() —
5531 Borrows the user attributes of a variant field class option.
5533 extern void bt_field_class_variant_option_set_user_attributes(
5534 bt_field_class_variant_option
*option
,
5535 const bt_value
*user_attributes
) __BT_NOEXCEPT
;
5539 Borrows the user attributes of the \bt_var_fc option \bt_p{option}.
5541 See the \ref api-tir-fc-var-prop-opts "options" property.
5544 When you append an option to a variant field class with
5545 bt_field_class_variant_without_selector_append_option(),
5546 bt_field_class_variant_with_selector_field_integer_unsigned_append_option(),
5548 bt_field_class_variant_with_selector_field_integer_signed_append_option(),
5549 the option's initial user attributes is an empty \bt_map_val.
5552 Variant field class option from which to borrow the user
5556 User attributes of \bt_p{option} (a \bt_map_val).
5558 @bt_pre_not_null{option}
5560 @sa bt_field_class_variant_option_set_user_attributes() —
5561 Sets the user attributes of a variant field class option.
5562 @sa bt_field_class_variant_option_borrow_user_attributes_const() —
5563 \c const version of this function.
5565 extern bt_value
*bt_field_class_variant_option_borrow_user_attributes(
5566 bt_field_class_variant_option
*option
) __BT_NOEXCEPT
;
5570 Borrows the user attributes of the \bt_var_fc option \bt_p{option}
5573 See bt_field_class_variant_option_borrow_user_attributes().
5575 extern const bt_value
*bt_field_class_variant_option_borrow_user_attributes_const(
5576 const bt_field_class_variant_option
*option
) __BT_NOEXCEPT
;
5581 @name Variant field class: instances without a linked selector field
5587 Creates an empty \bt_var_fc (instances without a linked
5588 selector field) from the trace class \bt_p{trace_class}.
5590 On success, the returned variant field class has the following
5598 <td>\ref api-tir-fc-var-prop-sel-fp "Selector field location"
5602 <td>\ref api-tir-fc-var-prop-opts "Options"
5605 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
5606 <td>Empty \bt_map_val
5609 @param[in] trace_class
5610 Trace class from which to create a variant field class.
5613 New option field class reference, or \c NULL on memory error.
5615 @bt_pre_not_null{trace_class}
5616 @bt_pre_tc_with_mip{trace_class, 1}
5618 @sa bt_field_class_variant_with_selector_field_location_integer_unsigned_create() —
5619 Creates a class of variant field with a linked unsigned integer
5621 @sa bt_field_class_variant_with_selector_field_location_integer_signed_create() —
5622 Creates a class of variant field with a linked signed integer
5625 extern bt_field_class
*bt_field_class_variant_without_selector_field_location_create(
5626 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
5631 bt_field_class_variant_without_selector_append_option().
5633 typedef enum bt_field_class_variant_without_selector_append_option_status
{
5638 BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
5644 BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
5645 } bt_field_class_variant_without_selector_append_option_status
;
5649 Appends an option to the \bt_var_fc (instances without a linked
5650 selector field) \bt_p{field_class} having the name \bt_p{name} and
5651 the field class \bt_p{option_field_class}.
5653 See the \ref api-tir-fc-var-prop-opts "options" property.
5655 @param[in] field_class
5656 Variant field class to which to append an option having
5657 the name \bt_p{name} and the field class \bt_p{option_field_class}.
5660 Name of the option to append to \bt_p{field_class} (copied).
5662 Can be \c NULL when the effective \bt_mip version of the trace
5663 processing \bt_graph is 1.
5665 @param[in] option_field_class
5666 Field class of the option to append to \bt_p{field_class}.
5668 @retval #BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
5670 @retval #BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
5673 @bt_pre_not_null{field_class}
5674 @bt_pre_hot{field_class}
5675 @bt_pre_is_var_wos_fc{field_class}
5677 <strong>If \bt_p{name} is not \c NULL</strong>, then
5678 \bt_p{field_class} has no option with the name \bt_p{name}.
5680 <strong>If \bt_p{field_class} was created from a
5681 \bt_trace_cls which was created from a \bt_comp which belongs
5682 to a trace processing \bt_graph with the effective \bt_mip
5683 version 0</strong>, then \bt_p{name} is \em not \c NULL.
5684 @bt_pre_not_null{option_field_class}
5685 @bt_pre_fc_not_in_tc{option_field_class}
5687 @bt_post_success_frozen{option_field_class}
5689 extern bt_field_class_variant_without_selector_append_option_status
5690 bt_field_class_variant_without_selector_append_option(
5691 bt_field_class
*field_class
, const char *name
,
5692 bt_field_class
*option_field_class
) __BT_NOEXCEPT
;
5697 @name Variant field class: instances with a linked selector field
5704 bt_field_class_variant_with_selector_field_integer_unsigned_append_option()
5706 bt_field_class_variant_with_selector_field_integer_signed_append_option().
5708 typedef enum bt_field_class_variant_with_selector_field_integer_append_option_status
{
5713 BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
5719 BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
5720 } bt_field_class_variant_with_selector_field_integer_append_option_status
;
5724 Borrows the selector field path from the \bt_var_fc (instances with
5725 a linked selector field) \bt_p{field_class}.
5727 See the \ref api-tir-fc-var-prop-sel-fp "selector field path" property.
5729 This property is only available when all the following are true:
5731 - \bt_p{field_class} was created with
5732 bt_field_class_variant_create() with \bt_p{selector_field_class}
5733 set to an \bt_int_fc (not \c NULL).
5735 - A \bt_struct_fc containing (recursively) \bt_p{field_class} is passed
5738 - bt_stream_class_set_packet_context_field_class()
5739 - bt_stream_class_set_event_common_context_field_class()
5740 - bt_event_class_set_specific_context_field_class()
5741 - bt_event_class_set_payload_field_class()
5743 In the meantime, this function returns \c NULL.
5745 @param[in] field_class
5746 Variant field class from which to borrow the selector field path.
5749 Selector field path of \bt_p{field_class}.
5751 @bt_pre_not_null{field_class}
5752 @bt_pre_is_var_ws_fc{field_class}
5753 @bt_pre_fc_with_mip{field_class, 0}
5755 extern const bt_field_path
*
5756 bt_field_class_variant_with_selector_field_borrow_selector_field_path_const(
5757 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
5761 Borrows the selector field location from the \bt_var_fc (instances
5762 with a linked selector field) \bt_p{field_class}.
5764 See the \ref api-tir-fc-var-prop-sel-fl "selector field location"
5767 This property is only available when \bt_p{field_class} was created with
5768 bt_field_class_variant_with_selector_field_location_integer_unsigned_create()
5770 bt_field_class_variant_with_selector_field_location_integer_signed_create().
5772 @param[in] field_class
5773 Option field class from which to borrow the selector field location.
5776 Selector field location of \bt_p{field_class}.
5778 @bt_pre_not_null{field_class}
5779 @bt_pre_is_var_ws_fc{field_class}
5780 @bt_pre_fc_with_mip{field_class, 1}
5782 extern const bt_field_location
*
5783 bt_field_class_variant_with_selector_field_borrow_selector_field_location_const(
5784 const bt_field_class
*field_class
);
5789 @name Variant field class: instances with a linked unsigned integer selector field
5795 Creates an empty \bt_var_fc (instances with a linked
5796 unsigned integer selector field) having the
5797 selector \bt_field_loc \bt_p{selector_field_location}
5798 from the trace class \bt_p{trace_class}.
5800 On success, the returned variant field class has the following
5808 <td>\ref api-tir-fc-var-prop-sel-fp "Selector field location"
5810 \bt_p{selector_field_location}.
5812 See \ref api-tir-fc-link "Fields with links to other fields"
5815 <td>\ref api-tir-fc-var-prop-opts "Options"
5818 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
5819 <td>Empty \bt_map_val
5822 @param[in] trace_class
5823 Trace class from which to create a variant field class.
5824 @param[in] selector_field_location
5825 Selector field location of the variant field class to create.
5828 New variant field class reference, or \c NULL on memory error.
5830 @bt_pre_not_null{trace_class}
5831 @bt_pre_tc_with_mip{trace_class, 1}
5832 @bt_pre_not_null{selector_field_location}
5834 @sa bt_field_class_variant_without_selector_field_location_create() —
5835 Creates a class of variant field without a linked selector field.
5836 @sa bt_field_class_option_with_selector_field_location_integer_signed_create() —
5837 Creates a class of variant field with a linked signed integer
5840 extern bt_field_class
*bt_field_class_variant_with_selector_field_location_integer_unsigned_create(
5841 bt_trace_class
*trace_class
,
5842 const bt_field_location
*selector_field_location
) __BT_NOEXCEPT
;
5846 Appends an option to the \bt_var_fc (instances with a linked
5847 unsigned integer selector field) \bt_p{field_class} having the name
5848 \bt_p{name}, the field class \bt_p{option_field_class}, and the
5849 \bt_p_uint_rg \bt_p{ranges}.
5851 See the \ref api-tir-fc-var-prop-opts "options" property.
5853 @param[in] field_class
5854 Variant field class to which to append an option having
5855 the name \bt_p{name}, the field class \bt_p{option_field_class},
5856 and the unsigned integer ranges \bt_p{ranges}.
5859 Name of the option to append to \bt_p{field_class} (copied).
5861 Can be \c NULL when the effective \bt_mip version of the trace
5862 processing \bt_graph is 1.
5864 @param[in] option_field_class
5865 Field class of the option to append to \bt_p{field_class}.
5867 Unsigned integer ranges of the option to append to
5870 @retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
5872 @retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
5875 @bt_pre_not_null{field_class}
5876 @bt_pre_hot{field_class}
5877 @bt_pre_is_var_wuis_fc{field_class}
5879 <strong>If \bt_p{name} is not \c NULL</strong>, then
5880 \bt_p{field_class} has no option with the name \bt_p{name}.
5882 <strong>If \bt_p{field_class} was created from a
5883 \bt_trace_cls which was created from a \bt_comp which belongs
5884 to a trace processing \bt_graph with the effective \bt_mip
5885 version 0</strong>, then \bt_p{name} is \em not \c NULL.
5886 @bt_pre_not_null{option_field_class}
5887 @bt_pre_fc_not_in_tc{option_field_class}
5888 @bt_pre_not_null{ŗanges}
5890 \bt_p{ranges} contains one or more unsigned integer ranges.
5892 The unsigned integer ranges in \bt_p{ranges} do not overlap
5893 any unsigned integer range of any existing option in
5896 @bt_post_success_frozen{option_field_class}
5898 extern bt_field_class_variant_with_selector_field_integer_append_option_status
5899 bt_field_class_variant_with_selector_field_integer_unsigned_append_option(
5900 bt_field_class
*field_class
, const char *name
,
5901 bt_field_class
*option_field_class
,
5902 const bt_integer_range_set_unsigned
*ranges
) __BT_NOEXCEPT
;
5906 Borrows the option at index \bt_p{index} from the
5907 \bt_var_fc (instances with a linked unsigned integer selector field)
5910 See the \ref api-tir-fc-var-prop-opts "options" property.
5912 @param[in] field_class
5913 Variant field class from which to borrow the option at
5916 Index of the option to borrow from \bt_p{field_class}.
5920 \em Borrowed reference of the option of
5921 \bt_p{field_class} at index \bt_p{index}.
5923 The returned pointer remains valid as long as \bt_p{field_class}
5927 @bt_pre_not_null{field_class}
5928 @bt_pre_is_var_wuis_fc{field_class}
5930 \bt_p{index} is less than the number of options in
5931 \bt_p{field_class} (as returned by
5932 bt_field_class_variant_get_option_count()).
5934 @sa bt_field_class_variant_get_option_count() —
5935 Returns the number of options contained in a variant field class.
5937 extern const bt_field_class_variant_with_selector_field_integer_unsigned_option
*
5938 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(
5939 const bt_field_class
*field_class
, uint64_t index
)
5944 Borrows the option having the name \bt_p{name} from the
5945 \bt_var_fc (instances with a linked unsigned integer selector field)
5948 See the \ref api-tir-fc-var-prop-opts "options" property.
5950 If there's no option having the name \bt_p{name} in
5951 \bt_p{field_class}, this function returns \c NULL.
5953 @param[in] field_class
5954 Variant field class from which to borrow the option having the
5957 Name of the option to borrow from \bt_p{field_class}.
5961 \em Borrowed reference of the option of
5962 \bt_p{field_class} having the name \bt_p{name}, or \c NULL
5965 The returned pointer remains valid as long as \bt_p{field_class}
5969 @bt_pre_not_null{field_class}
5970 @bt_pre_is_var_wuis_fc{field_class}
5971 @bt_pre_not_null{name}
5973 @sa bt_field_class_variant_borrow_option_by_name_const() —
5974 Borrows an option by name from a variant field class.
5976 extern const bt_field_class_variant_with_selector_field_integer_unsigned_option
*
5977 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const(
5978 const bt_field_class
*field_class
, const char *name
)
5984 @name Variant field class option: instances with a linked unsigned integer selector field
5989 @typedef struct bt_field_class_variant_with_selector_field_integer_unsigned_option bt_field_class_variant_with_selector_field_integer_unsigned_option;
5992 Variant field class option (instances with a linked unsigned integer selector field).
5997 Borrows the \bt_p_uint_rg from the \bt_var_fc option
5998 (instances with a linked unsigned integer selector field)
6001 See the \ref api-tir-fc-var-prop-opts "options" property.
6004 Variant field class option from which to borrow the
6005 unsigned integer ranges.
6008 Unsigned integer ranges of \bt_p{option}.
6010 @bt_pre_not_null{option}
6012 extern const bt_integer_range_set_unsigned
*
6013 bt_field_class_variant_with_selector_field_integer_unsigned_option_borrow_ranges_const(
6014 const bt_field_class_variant_with_selector_field_integer_unsigned_option
*option
)
6019 \ref api-fund-c-typing "Upcasts" the \bt_var_fc option (instances
6020 with a linked unsigned integer selector field) \bt_p{option} to the
6021 common #bt_field_class_variant_option type.
6023 See the \ref api-tir-fc-var-prop-opts "options" property.
6027 Variant field class option to upcast.
6033 \bt_p{option} as a common variant field class option.
6036 const bt_field_class_variant_option
*
6037 bt_field_class_variant_with_selector_field_integer_unsigned_option_as_option_const(
6038 const bt_field_class_variant_with_selector_field_integer_unsigned_option
*option
)
6041 return __BT_UPCAST_CONST(bt_field_class_variant_option
, option
);
6047 @name Variant field class: instances with a linked signed integer selector field
6053 Creates an empty \bt_var_fc (instances with a linked
6054 signed integer selector field) having the
6055 selector \bt_field_loc \bt_p{selector_field_location}
6056 from the trace class \bt_p{trace_class}.
6058 On success, the returned variant field class has the following
6066 <td>\ref api-tir-fc-var-prop-sel-fp "Selector field location"
6068 \bt_p{selector_field_location}.
6070 See \ref api-tir-fc-link "Fields with links to other fields"
6073 <td>\ref api-tir-fc-var-prop-opts "Options"
6076 <td>\ref api-tir-fc-prop-user-attrs "User attributes"
6077 <td>Empty \bt_map_val
6080 @param[in] trace_class
6081 Trace class from which to create a variant field class.
6082 @param[in] selector_field_location
6083 Selector field location of the variant field class to create.
6086 New variant field class reference, or \c NULL on memory error.
6088 @bt_pre_not_null{trace_class}
6089 @bt_pre_tc_with_mip{trace_class, 1}
6090 @bt_pre_not_null{selector_field_location}
6092 @sa bt_field_class_variant_without_selector_field_location_create() —
6093 Creates a class of variant field without a linked selector field.
6094 @sa bt_field_class_option_with_selector_field_location_integer_unsigned_create() —
6095 Creates a class of variant field with a linked unsigned integer
6098 extern bt_field_class
*bt_field_class_variant_with_selector_field_location_integer_signed_create(
6099 bt_trace_class
*trace_class
,
6100 const bt_field_location
*selector_field_location
) __BT_NOEXCEPT
;
6104 Appends an option to the \bt_var_fc (instances with a linked signed
6105 integer selector field) \bt_p{field_class} having the name
6106 \bt_p{name}, the field class \bt_p{option_field_class}, and the
6107 \bt_p_sint_rg \bt_p{ranges}.
6109 See the \ref api-tir-fc-var-prop-opts "options" property.
6111 @param[in] field_class
6112 Variant field class to which to append an option having
6113 the name \bt_p{name} and the field class \bt_p{option_field_class},
6114 and the signed integer ranges \bt_p{ranges}.
6117 Name of the option to append to \bt_p{field_class} (copied).
6119 Can be \c NULL when the effective \bt_mip version of the trace
6120 processing \bt_graph is 1.
6122 @param[in] option_field_class
6123 Field class of the option to append to \bt_p{field_class}.
6125 Signed integer ranges of the option to append to
6128 @retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
6130 @retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
6133 @bt_pre_not_null{field_class}
6134 @bt_pre_hot{field_class}
6135 @bt_pre_is_var_wsis_fc{field_class}
6137 <strong>If \bt_p{name} is not \c NULL</strong>, then
6138 \bt_p{field_class} has no option with the name \bt_p{name}.
6140 <strong>If \bt_p{field_class} was created from a
6141 \bt_trace_cls which was created from a \bt_comp which belongs
6142 to a trace processing \bt_graph with the effective \bt_mip
6143 version 0</strong>, then \bt_p{name} is \em not \c NULL.
6144 @bt_pre_not_null{option_field_class}
6145 @bt_pre_fc_not_in_tc{option_field_class}
6146 @bt_pre_not_null{ŗanges}
6148 \bt_p{ranges} contains one or more signed integer ranges.
6150 The signed integer ranges in \bt_p{ranges} do not overlap with
6151 any signed integer range of any existing option in
6154 @bt_post_success_frozen{option_field_class}
6156 extern bt_field_class_variant_with_selector_field_integer_append_option_status
6157 bt_field_class_variant_with_selector_field_integer_signed_append_option(
6158 bt_field_class
*field_class
, const char *name
,
6159 bt_field_class
*option_field_class
,
6160 const bt_integer_range_set_signed
*ranges
)
6165 Borrows the option at index \bt_p{index} from the
6166 \bt_var_fc (instances with a linked signed integer selector field)
6169 See the \ref api-tir-fc-var-prop-opts "options" property.
6171 @param[in] field_class
6172 Variant field class from which to borrow the option at
6175 Index of the option to borrow from \bt_p{field_class}.
6179 \em Borrowed reference of the option of
6180 \bt_p{field_class} at index \bt_p{index}.
6182 The returned pointer remains valid as long as \bt_p{field_class}
6186 @bt_pre_not_null{field_class}
6187 @bt_pre_is_var_wsis_fc{field_class}
6189 \bt_p{index} is less than the number of options in
6190 \bt_p{field_class} (as returned by
6191 bt_field_class_variant_get_option_count()).
6193 @sa bt_field_class_variant_get_option_count() —
6194 Returns the number of options contained in a variant field class.
6196 extern const bt_field_class_variant_with_selector_field_integer_signed_option
*
6197 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(
6198 const bt_field_class
*field_class
, uint64_t index
)
6203 Borrows the option having the name \bt_p{name} from the
6204 \bt_var_fc (instances with a linked signed integer selector field)
6207 See the \ref api-tir-fc-var-prop-opts "options" property.
6209 If there's no option having the name \bt_p{name} in
6210 \bt_p{field_class}, this function returns \c NULL.
6212 @param[in] field_class
6213 Variant field class from which to borrow the option having the
6216 Name of the option to borrow from \bt_p{field_class}.
6220 \em Borrowed reference of the option of
6221 \bt_p{field_class} having the name \bt_p{name}, or \c NULL
6224 The returned pointer remains valid as long as \bt_p{field_class}
6228 @bt_pre_not_null{field_class}
6229 @bt_pre_is_var_wsis_fc{field_class}
6230 @bt_pre_not_null{name}
6232 @sa bt_field_class_variant_borrow_option_by_name_const() —
6233 Borrows an option by name from a variant field class.
6235 extern const bt_field_class_variant_with_selector_field_integer_signed_option
*
6236 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const(
6237 const bt_field_class
*field_class
, const char *name
)
6243 @name Variant field class option: instances with a linked signed integer selector field
6248 @typedef struct bt_field_class_variant_with_selector_field_integer_signed_option bt_field_class_variant_with_selector_field_integer_signed_option;
6251 Variant field class option (instances with a linked signed integer selector field).
6256 Borrows the \bt_p_sint_rg from the \bt_var_fc option
6257 (instances with a linked signed integer selector field)
6260 See the \ref api-tir-fc-var-prop-opts "options" property.
6263 Variant field class option from which to borrow the
6264 signed integer ranges.
6267 Signed integer ranges of \bt_p{option}.
6269 @bt_pre_not_null{option}
6271 extern const bt_integer_range_set_signed
*
6272 bt_field_class_variant_with_selector_field_integer_signed_option_borrow_ranges_const(
6273 const bt_field_class_variant_with_selector_field_integer_signed_option
*option
)
6278 \ref api-fund-c-typing "Upcasts" the \bt_var_fc option
6279 (instances with a linked signed integer selector field)
6280 \bt_p{option} to the common #bt_field_class_variant_option type.
6282 See the \ref api-tir-fc-var-prop-opts "options" property.
6286 Variant field class option to upcast.
6292 \bt_p{option} as a common variant field class option.
6295 const bt_field_class_variant_option
*
6296 bt_field_class_variant_with_selector_field_integer_signed_option_as_option_const(
6297 const bt_field_class_variant_with_selector_field_integer_signed_option
*option
)
6300 return __BT_UPCAST_CONST(bt_field_class_variant_option
, option
);
6306 @name Reference count
6312 Increments the \ref api-fund-shared-object "reference count" of
6313 the field class \bt_p{field_class}.
6315 @param[in] field_class
6317 Field class of which to increment the reference count.
6322 @sa bt_field_class_put_ref() —
6323 Decrements the reference count of a field class.
6325 extern void bt_field_class_get_ref(
6326 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
6330 Decrements the \ref api-fund-shared-object "reference count" of
6331 the field class \bt_p{field_class}.
6333 @param[in] field_class
6335 Field class of which to decrement the reference count.
6340 @sa bt_field_class_get_ref() —
6341 Increments the reference count of a field class.
6343 extern void bt_field_class_put_ref(
6344 const bt_field_class
*field_class
) __BT_NOEXCEPT
;
6348 Decrements the reference count of the field class
6349 \bt_p{_field_class}, and then sets \bt_p{_field_class} to \c NULL.
6353 Field class of which to decrement the reference count.
6355 Can contain \c NULL.
6358 @bt_pre_assign_expr{_field_class}
6360 #define BT_FIELD_CLASS_PUT_REF_AND_RESET(_field_class) \
6362 bt_field_class_put_ref(_field_class); \
6363 (_field_class) = NULL; \
6368 Decrements the reference count of the field class \bt_p{_dst}, sets
6369 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
6371 This macro effectively moves a field class reference from the expression
6372 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
6373 \bt_p{_dst} reference.
6377 Destination expression.
6379 Can contain \c NULL.
6385 Can contain \c NULL.
6388 @bt_pre_assign_expr{_dst}
6389 @bt_pre_assign_expr{_src}
6391 #define BT_FIELD_CLASS_MOVE_REF(_dst, _src) \
6393 bt_field_class_put_ref(_dst); \
6406 #endif /* BABELTRACE2_TRACE_IR_FIELD_CLASS_H */