2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_TRACE_IR_FIELD_H
8 #define BABELTRACE2_TRACE_IR_FIELD_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
18 #include <babeltrace2/types.h>
25 @defgroup api-tir-field Fields
29 Containers of trace data.
31 <strong><em>Fields</em></strong> are containers of trace data: they are
32 found in \bt_p_ev and \bt_p_pkt.
34 Fields are instances of \bt_p_fc:
36 @image html field-class-zoom.png
38 Borrow the class of a field with bt_field_borrow_class() and
39 bt_field_borrow_class_const().
41 Fields are \ref api-tir "trace IR" data objects.
43 There are many types of fields. They can be divided into two main
49 Fields which contain a simple value.
51 The scalar fields are:
53 - \ref api-tir-field-bool "Boolean"
54 - \ref api-tir-field-ba "Bit array"
55 - \ref api-tir-field-int "Integer" (unsigned and signed)
56 - \ref api-tir-field-enum "Enumeration" (unsigned and signed)
57 - \ref api-tir-field-real "Real" (single-precision and double-precision)
58 - \ref api-tir-field-string "String"
63 Fields which contain other fields.
65 The container fields are:
67 - \ref api-tir-field-array "Array" (static and dynamic)
68 - \ref api-tir-field-struct "Structure"
69 - \ref api-tir-field-opt "Option"
70 - \ref api-tir-field-var "Variant"
74 @image html fc-to-field.png "Fields (green) are instances of field classes (orange)."
76 You cannot directly create a field: there are no
77 <code>bt_field_*_create()</code> functions. The \bt_name library
78 creates fields within an \bt_ev or a \bt_pkt from \bt_p_fc.
79 Therefore, to fill the payload fields of an \bt_ev, you must first
80 borrow the event's existing payload \bt_struct_field with
81 bt_event_borrow_payload_field() and then borrow each field, recursively,
84 The functions to borrow a field from an event or a packet are:
86 - bt_packet_borrow_context_field() and
87 bt_packet_borrow_context_field_const()
88 - bt_event_borrow_common_context_field() and
89 bt_event_borrow_common_context_field_const()
90 - bt_event_borrow_specific_context_field() and
91 bt_event_borrow_specific_context_field_const()
92 - bt_event_borrow_payload_field() and
93 bt_event_borrow_payload_field_const()
95 Some fields conceptually inherit other fields, eventually
96 making an inheritance hierarchy. For example, an \bt_enum_field
97 \em is an \bt_int_field. Therefore, an enumeration field holds an
98 integral value, just like an integer field does.
100 The complete field inheritance hierarchy is:
102 @image html all-fields.png
104 This is the same inheritance hierarchy as the \bt_fc inheritance
107 In the illustration above:
109 - A field with a dark background is instantiated from a concrete \bt_fc,
110 which you can directly create with a dedicated
111 <code>bt_field_class_*_create()</code> function.
113 - A field with a pale background is an \em abstract field: it's not a
114 concrete instance, but it can have properties, therefore there can be
115 functions which apply to it.
117 For example, bt_field_integer_signed_set_value() applies to any
120 Fields are \ref api-fund-unique-object "unique objects": they belong
121 to an \bt_ev or to a \bt_pkt.
123 Some library functions \ref api-fund-freezing "freeze" fields on
124 success. The documentation of those functions indicate this
127 All the field types share the same C type, #bt_field.
129 Get the type enumerator of a field's class with bt_field_get_class_type().
130 Get whether or not a field class type conceptually \em is a given type
131 with the inline bt_field_class_type_is() function.
133 <h1>\anchor api-tir-field-bool Boolean field</h1>
135 A <strong><em>boolean field</em></strong> is a \bt_bool_fc instance.
137 A boolean field contains a boolean value (#BT_TRUE or #BT_FALSE).
139 Set the value of a boolean field with bt_field_bool_set_value().
141 Get the value of a boolean field with bt_field_bool_get_value().
143 <h1>\anchor api-tir-field-ba Bit array field</h1>
145 A <strong><em>bit array field</em></strong> is a \bt_ba_fc instance.
147 A bit array field contains a fixed-length array of bits. Its length
148 is \ref api-tir-fc-ba-prop-len "given by its class".
150 The bit array field API interprets the array as an unsigned integer
151 value: the least significant bit's index is 0.
153 For example, to get whether or not bit 3 of a bit array field is
157 uint64_t value = bt_field_bit_array_get_value_as_integer(field);
159 if (value & (UINT64_C(1) << UINT64_C(3))) {
164 Set the bits of a bit array field with
165 bt_field_bit_array_set_value_as_integer().
167 Get the bits of a bit array field with
168 bt_field_bit_array_get_value_as_integer().
170 <h1>\anchor api-tir-field-int Integer fields</h1>
172 <strong><em>Integer fields</em></strong> are \bt_int_fc instances.
174 Integer fields contain integral values.
176 An integer field is an \em abstract field. The concrete integer fields
180 <dt>Unsigned integer field</dt>
182 An \bt_uint_fc instance.
184 An unsigned integer field contains an unsigned integral value
187 Set the value of an unsigned integer field with
188 bt_field_integer_unsigned_set_value().
190 Get the value of an unsigned integer field with
191 bt_field_integer_unsigned_get_value().
194 <dt>Signed integer field</dt>
196 A \bt_sint_fc instance.
198 A signed integer field contains a signed integral value (\c int64_t).
200 Set the value of a signed integer field with
201 bt_field_integer_signed_set_value().
203 Get the value of a signed integer field with
204 bt_field_integer_signed_get_value().
208 <h2>\anchor api-tir-field-enum Enumeration fields</h2>
210 <strong><em>Enumeration fields</em></strong> are \bt_enum_fc instances.
212 Enumeration fields \em are \bt_p_int_field: they contain integral
215 An enumeration field is an \em abstract field.
216 The concrete enumeration fields are:
219 <dt>Unsigned enumeration field</dt>
221 An \bt_uenum_fc instance.
223 An unsigned enumeration field contains an unsigned integral value
226 Set the value of an unsigned enumeration field with
227 bt_field_integer_unsigned_set_value().
229 Get the value of an unsigned enumeration field with
230 bt_field_integer_unsigned_get_value().
232 Get all the enumeration field class labels mapped to the value of a
233 given unsigned enumeration field with
234 bt_field_enumeration_unsigned_get_mapping_labels().
237 <dt>Signed enumeration field</dt>
239 A \bt_senum_fc instance.
241 A signed enumeration field contains a signed integral value
244 Set the value of a signed enumeration field with
245 bt_field_integer_signed_set_value().
247 Get the value of a signed enumeration field with
248 bt_field_integer_signed_get_value().
250 Get all the enumeration field class labels mapped to the value of a
251 given signed enumeration field with
252 bt_field_enumeration_signed_get_mapping_labels().
256 <h1>\anchor api-tir-field-real Real fields</h1>
258 <strong><em>Real fields</em></strong> are \bt_real_fc instances.
261 <a href="https://en.wikipedia.org/wiki/Real_number">real</a>
262 values (\c float or \c double types).
264 A real field is an \em abstract field. The concrete real fields are:
267 <dt>Single-precision real field</dt>
269 A single-precision real field class instance.
271 A single-precision real field contains a \c float value.
273 Set the value of a single-precision real field with
274 bt_field_real_single_precision_set_value().
276 Get the value of a single-precision real field with
277 bt_field_real_single_precision_get_value().
280 <dt>Double-precision real field</dt>
282 A double-precision real field class instance.
284 A double-precision real field contains a \c double value.
286 Set the value of a double-precision real field with
287 bt_field_real_double_precision_set_value().
289 Get the value of a double-precision real field with
290 bt_field_real_double_precision_get_value().
294 <h1>\anchor api-tir-field-string String field</h1>
296 A <strong><em>string field</em></strong> is a \bt_string_fc instance.
298 A string field contains an UTF-8 string value.
300 Set the value of a string field with
301 bt_field_string_set_value().
303 Get the value of a string field with
304 bt_field_string_get_value().
306 Get the length of a string field with
307 bt_field_string_get_length().
309 Append a string to a string field's current value with
310 bt_field_string_append() and bt_field_string_append_with_length().
312 Clear a string field with bt_field_string_clear().
314 <h1>\anchor api-tir-field-array Array fields</h1>
316 <strong><em>Array fields</em></strong> are \bt_array_fc instances.
318 Array fields contain zero or more fields which have the same class.
320 An array field is an \em abstract field. The concrete array fields are:
323 <dt>Static array field</dt>
325 A \bt_sarray_fc instance.
327 A static array field contains a fixed number of fields. Its length
328 is \ref api-tir-fc-sarray-prop-len "given by its class".
331 <dt>Dynamic array field class</dt>
333 A \bt_darray_fc instance.
335 A dynamic array field contains a variable number of fields, that is,
336 each instance of the same dynamic array field class can contain a
337 different number of elements.
339 Set a dynamic array field's length with
340 bt_field_array_dynamic_set_length() before you borrow any of its
345 Get an array field's length with bt_field_array_get_length().
347 Borrow a field from an array field at a given index with
348 bt_field_array_borrow_element_field_by_index() and
349 bt_field_array_borrow_element_field_by_index_const().
351 <h1>\anchor api-tir-field-struct Structure field</h1>
353 A <strong><em>structure field</em></strong> is a \bt_struct_fc instance.
355 A structure field contains an ordered list of zero or more members. A
356 structure field member contains a field: it's an instance of a structure
359 Borrow a member's field from a structure field at a given index with
360 bt_field_structure_borrow_member_field_by_index() and
361 bt_field_structure_borrow_member_field_by_index_const().
363 Borrow a member's field from a structure field by name with
364 bt_field_structure_borrow_member_field_by_name() and
365 bt_field_structure_borrow_member_field_by_name_const().
367 <h1>\anchor api-tir-field-opt Option field</h1>
369 An <strong><em>option field</em></strong> is an \bt_opt_fc instance.
371 An option field either does or doesn't contain a field.
373 Set whether or not an option field has a field with
374 bt_field_option_set_has_field().
376 Borrow the field from an option field with
377 bt_field_option_borrow_field() or
378 bt_field_option_borrow_field_const().
380 <h1>\anchor api-tir-field-var Variant field</h1>
382 A <strong><em>variant field</em></strong> is a \bt_var_fc instance.
384 A variant field has a single selected option amongst one or more
385 possible options. A variant field option contains a field: it's an
386 instance of a variant field class option.
388 Set the current option of a variant field with
389 bt_field_variant_select_option_by_index().
391 Get a variant field's selected option's index with
392 bt_field_variant_get_selected_option_index().
394 Borrow a variant field's selected option's field with
395 bt_field_variant_borrow_selected_option_field() and
396 bt_field_variant_borrow_selected_option_field_const().
398 Borrow the class of a variant field's selected
399 option with bt_field_variant_borrow_selected_option_class_const(),
400 bt_field_variant_with_selector_field_integer_unsigned_borrow_selected_option_class_const(),
402 bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const().
411 @typedef struct bt_field bt_field;
426 Returns the type enumerator of the \ref api-tir-fc "class" of the
429 This function returns
432 bt_field_class_get_type(bt_field_borrow_class(field))
436 Field of which to get the class's type enumerator
439 Type enumerator of the class of \bt_p{field}.
441 @bt_pre_not_null{field}
443 @sa bt_field_class_get_type() —
444 Returns the type enumerator of a \bt_fc.
446 extern bt_field_class_type
bt_field_get_class_type(
447 const bt_field
*field
);
458 Borrows the \ref api-tir-fc "class" of the field \bt_p{field}.
461 Field of which to borrow the class.
464 \em Borrowed reference of the class of \bt_p{field}.
466 @bt_pre_not_null{field}
468 @sa bt_field_borrow_class_const() —
469 \c const version of this function.
471 extern bt_field_class
*bt_field_borrow_class(bt_field
*field
);
475 Borrows the \ref api-tir-fc "class" of the field \bt_p{field}
478 See bt_field_borrow_class().
480 extern const bt_field_class
*bt_field_borrow_class_const(
481 const bt_field
*field
);
492 Sets the value of the \bt_bool_field \bt_p{field} to
496 Boolean field of which to set the value to \bt_p{value}.
498 New value of \bt_p{field}.
500 @bt_pre_not_null{field}
501 @bt_pre_is_bool_field{field}
504 @sa bt_field_bool_get_value() —
505 Returns the value of a boolean field.
507 extern void bt_field_bool_set_value(bt_field
*field
, bt_bool value
);
511 Returns the value of the \bt_bool_field \bt_p{field}.
514 Boolean field of which to get the value.
517 Value of \bt_p{field}.
519 @bt_pre_not_null{field}
520 @bt_pre_is_bool_field{field}
522 @sa bt_field_bool_set_value() —
523 Sets the value of a boolean field.
525 extern bt_bool
bt_field_bool_get_value(const bt_field
*field
);
530 @name Bit array field
536 Sets the bits of the \bt_ba_field \bt_p{field} to the bits of
539 The least significant bit's index is 0.
541 See \bt_c_ba_field to learn more.
544 Bit array field of which to set the bits to \bt_p{bits}.
546 New bits of \bt_p{field}.
548 @bt_pre_not_null{field}
549 @bt_pre_is_ba_field{field}
552 @sa bt_field_bit_array_get_value_as_integer() —
553 Returns the bits of a bit array field as an integer.
555 extern void bt_field_bit_array_set_value_as_integer(bt_field
*field
,
560 Returns the bits of the \bt_ba_field \bt_p{field} as an
563 The least significant bit's index is 0.
565 See \bt_c_ba_field to learn more.
568 Bit array field of which to get the bits.
571 Bits of \bt_p{field} as an unsigned integer.
573 @bt_pre_not_null{field}
574 @bt_pre_is_ba_field{field}
576 @sa bt_field_bit_array_set_value_as_integer() —
577 Sets the bits of a bit array field from an integer.
579 extern uint64_t bt_field_bit_array_get_value_as_integer(
580 const bt_field
*field
);
591 Sets the value of the \bt_uint_field \bt_p{field} to
595 Unsigned integer field of which to set the value to \bt_p{value}.
597 New value of \bt_p{field}.
599 @bt_pre_not_null{field}
600 @bt_pre_is_uint_field{field}
603 \bt_p{value} is within the
604 \ref api-tir-fc-int-prop-size "field value range" of the
605 class of \bt_p{field}.
607 @sa bt_field_integer_unsigned_get_value() —
608 Returns the value of an unsigned integer field.
610 extern void bt_field_integer_unsigned_set_value(bt_field
*field
,
615 Returns the value of the \bt_uint_field \bt_p{field}.
618 Unsigned integer field of which to get the value.
621 Value of \bt_p{field}.
623 @bt_pre_not_null{field}
624 @bt_pre_is_uint_field{field}
626 @sa bt_field_integer_unsigned_set_value() —
627 Sets the value of an unsigned integer field.
629 extern uint64_t bt_field_integer_unsigned_get_value(
630 const bt_field
*field
);
634 Sets the value of the \bt_sint_field \bt_p{field} to
638 Signed integer field of which to set the value to \bt_p{value}.
640 New value of \bt_p{field}.
642 @bt_pre_not_null{field}
643 @bt_pre_is_sint_field{field}
646 \bt_p{value} is within the
647 \ref api-tir-fc-int-prop-size "field value range" of the
648 class of \bt_p{field}.
650 @sa bt_field_integer_signed_get_value() —
651 Returns the value of an signed integer field.
653 extern void bt_field_integer_signed_set_value(bt_field
*field
,
658 Returns the value of the \bt_sint_field \bt_p{field}.
661 Signed integer field of which to get the value.
664 Value of \bt_p{field}.
666 @bt_pre_not_null{field}
667 @bt_pre_is_sint_field{field}
669 @sa bt_field_integer_signed_set_value() —
670 Sets the value of an signed integer field.
672 extern int64_t bt_field_integer_signed_get_value(const bt_field
*field
);
677 @name Enumeration field
684 bt_field_enumeration_unsigned_get_mapping_labels() and
685 bt_field_enumeration_signed_get_mapping_labels().
687 typedef enum bt_field_enumeration_get_mapping_labels_status
{
692 BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK
= __BT_FUNC_STATUS_OK
,
698 BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
699 } bt_field_enumeration_get_mapping_labels_status
;
703 Returns an array of all the labels of the mappings of the
704 \ref api-tir-fc-enum "class" of the \bt_uenum_field \bt_p{field}
705 of which the \bt_p_uint_rg contain the integral value
708 This function returns
711 (bt_field_enumeration_get_mapping_labels_status)
712 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value(
713 bt_field_borrow_class_const(field),
714 bt_field_integer_unsigned_get_value(field),
719 Unsigned enumeration field having the class from which to get the
720 labels of the mappings of which the ranges contain its
724 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value().
727 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value().
729 @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK
731 @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR
734 @bt_pre_not_null{field}
735 @bt_pre_is_uenum_field{field}
736 @bt_pre_not_null{labels}
737 @bt_pre_not_null{count}
739 extern bt_field_enumeration_get_mapping_labels_status
740 bt_field_enumeration_unsigned_get_mapping_labels(const bt_field
*field
,
741 bt_field_class_enumeration_mapping_label_array
*labels
,
746 Returns an array of all the labels of the mappings of the
747 \ref api-tir-fc-enum "class" of the \bt_senum_field \bt_p{field}
748 of which the \bt_p_sint_rg contain the integral value
751 This function returns
754 (bt_field_enumeration_get_mapping_labels_status)
755 bt_field_class_enumeration_signed_get_mapping_labels_for_value(
756 bt_field_borrow_class_const(field),
757 bt_field_integer_signed_get_value(field),
762 Signed enumeration field having the class from which to get the
763 labels of the mappings of which the ranges contain its
767 bt_field_class_enumeration_signed_get_mapping_labels_for_value().
770 bt_field_class_enumeration_signed_get_mapping_labels_for_value().
772 @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK
774 @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR
777 @bt_pre_not_null{field}
778 @bt_pre_is_senum_field{field}
779 @bt_pre_not_null{labels}
780 @bt_pre_not_null{count}
782 extern bt_field_enumeration_get_mapping_labels_status
783 bt_field_enumeration_signed_get_mapping_labels(const bt_field
*field
,
784 bt_field_class_enumeration_mapping_label_array
*labels
,
796 Sets the value of the \bt_sreal_field \bt_p{field} to
800 Single-precision real field of which to set the value to
803 New value of \bt_p{field}.
805 @bt_pre_not_null{field}
806 @bt_pre_is_sreal_field{field}
809 @sa bt_field_real_single_precision_get_value() —
810 Returns the value of a single-precision real field.
812 extern void bt_field_real_single_precision_set_value(bt_field
*field
,
817 Returns the value of the \bt_sreal_field \bt_p{field}.
820 Single-precision real field of which to get the value.
823 Value of \bt_p{field}.
825 @bt_pre_not_null{field}
826 @bt_pre_is_sreal_field{field}
828 @sa bt_field_real_single_precision_set_value() —
829 Sets the value of a single-precision real field.
831 extern float bt_field_real_single_precision_get_value(const bt_field
*field
);
835 Sets the value of the \bt_dreal_field \bt_p{field} to
839 Double-precision real field of which to set the value to
842 New value of \bt_p{field}.
844 @bt_pre_not_null{field}
845 @bt_pre_is_dreal_field{field}
848 @sa bt_field_real_double_precision_get_value() —
849 Returns the value of a double-precision real field.
851 extern void bt_field_real_double_precision_set_value(bt_field
*field
,
856 Returns the value of the \bt_dreal_field \bt_p{field}.
859 Double-precision real field of which to get the value.
862 Value of \bt_p{field}.
864 @bt_pre_not_null{field}
865 @bt_pre_is_dreal_field{field}
867 @sa bt_field_real_double_precision_set_value() —
868 Sets the value of a double-precision real field.
870 extern double bt_field_real_double_precision_get_value(const bt_field
*field
);
881 Status codes for bt_field_string_set_value().
883 typedef enum bt_field_string_set_value_status
{
888 BT_FIELD_STRING_SET_VALUE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
894 BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
895 } bt_field_string_set_value_status
;
899 Sets the value of the \bt_string_field \bt_p{field} to
900 a copy of \bt_p{value}.
903 String field of which to set the value to \bt_p{value}.
905 New value of \bt_p{field} (copied).
907 @retval #BT_FIELD_STRING_SET_VALUE_STATUS_OK
909 @retval #BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR
912 @bt_pre_not_null{field}
913 @bt_pre_is_string_field{field}
915 @bt_pre_not_null{value}
917 @sa bt_field_string_get_value() —
918 Returns the value of a string field.
919 @sa bt_field_string_append() —
920 Appends a string to a string field.
921 @sa bt_field_string_clear() —
922 Clears a string field.
924 extern bt_field_string_set_value_status
bt_field_string_set_value(
925 bt_field
*field
, const char *value
);
929 Returns the length of the \bt_string_field \bt_p{field}.
932 String field of which to get the length.
935 Length of \bt_p{field}.
937 @bt_pre_not_null{field}
938 @bt_pre_is_string_field{field}
940 extern uint64_t bt_field_string_get_length(const bt_field
*field
);
944 Returns the value of the \bt_string_field \bt_p{field}.
947 String field of which to get the value.
951 Value of \bt_p{field}.
953 The returned pointer remains valid until \bt_p{field} is modified.
956 @bt_pre_not_null{field}
957 @bt_pre_is_string_field{field}
959 @sa bt_field_string_set_value() —
960 Sets the value of a string field.
962 extern const char *bt_field_string_get_value(const bt_field
*field
);
966 Status codes for bt_field_string_append() and
967 bt_field_string_append_with_length().
969 typedef enum bt_field_string_append_status
{
974 BT_FIELD_STRING_APPEND_STATUS_OK
= __BT_FUNC_STATUS_OK
,
980 BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
981 } bt_field_string_append_status
;
985 Appends a copy of the string \bt_p{value} to the current value of
986 the \bt_string_field \bt_p{field}.
989 If you didn't set the value of \bt_p{field} yet, you must call
990 bt_field_string_clear() before you call this function.
993 String field to which to append the string \bt_p{value}.
995 String to append to \bt_p{field} (copied).
997 @retval #BT_FIELD_STRING_APPEND_STATUS_OK
999 @retval #BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR
1002 @bt_pre_not_null{field}
1003 @bt_pre_is_string_field{field}
1005 @bt_pre_not_null{value}
1007 @sa bt_field_string_append_with_length() —
1008 Appends a string with a given length to a string field.
1009 @sa bt_field_string_set_value() —
1010 Sets the value of a string field.
1012 extern bt_field_string_append_status
bt_field_string_append(
1013 bt_field
*field
, const char *value
);
1017 Appends a copy of the first \bt_p{length} bytes of the string
1018 \bt_p{value} to the current value of the \bt_string_field
1022 If you didn't set the value of \bt_p{field} yet, you must call
1023 bt_field_string_clear() before you call this function.
1026 String field to which to append the first \bt_p{length} bytes of
1027 the string \bt_p{value}.
1029 String of which to append the first \bt_p{length} bytes to
1030 \bt_p{field} (copied).
1032 Number of bytes of \bt_p{value} to append to \bt_p{field}.
1034 @retval #BT_FIELD_STRING_APPEND_STATUS_OK
1036 @retval #BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR
1039 @bt_pre_not_null{field}
1040 @bt_pre_is_string_field{field}
1042 @bt_pre_not_null{value}
1044 @sa bt_field_string_append() —
1045 Appends a string to a string field.
1046 @sa bt_field_string_set_value() —
1047 Sets the value of a string field.
1049 extern bt_field_string_append_status
bt_field_string_append_with_length(
1050 bt_field
*field
, const char *value
, uint64_t length
);
1054 Clears the \bt_string_field \bt_p{field}, making its value an empty
1058 String field to clear.
1060 @bt_pre_not_null{field}
1061 @bt_pre_is_string_field{field}
1064 @sa bt_field_string_set_value() —
1065 Sets the value of a string field.
1067 extern void bt_field_string_clear(bt_field
*field
);
1078 Returns the length of the \bt_array_field \bt_p{field}.
1081 Array field of which to get the length.
1084 Length of \bt_p{field}.
1086 @bt_pre_not_null{field}
1087 @bt_pre_is_array_field{field}
1089 extern uint64_t bt_field_array_get_length(const bt_field
*field
);
1093 Borrows the field at index \bt_p{index} from the \bt_array_field
1097 If \bt_p{field} is a dynamic array field, it must have a length
1098 (call bt_field_array_dynamic_set_length()) before you call this
1102 Array field from which to borrow the field at index \bt_p{index}.
1104 Index of the field to borrow from \bt_p{field}.
1108 \em Borrowed reference of the field of \bt_p{field} at index
1111 The returned pointer remains valid as long as \bt_p{field} exists.
1114 @bt_pre_not_null{field}
1115 @bt_pre_is_array_field{field}
1117 \bt_p{index} is less than the length of \bt_p{field} (as returned by
1118 bt_field_array_get_length()).
1120 @sa bt_field_array_borrow_element_field_by_index_const() —
1121 \c const version of this function.
1123 extern bt_field
*bt_field_array_borrow_element_field_by_index(
1124 bt_field
*field
, uint64_t index
);
1128 Borrows the field at index \bt_p{index} from the \bt_array_field
1129 \bt_p{field} (\c const version).
1131 See bt_field_array_borrow_element_field_by_index().
1133 extern const bt_field
*
1134 bt_field_array_borrow_element_field_by_index_const(
1135 const bt_field
*field
, uint64_t index
);
1139 Status codes for bt_field_array_dynamic_set_length().
1141 typedef enum bt_field_array_dynamic_set_length_status
{
1146 BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1152 BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1153 } bt_field_array_dynamic_set_length_status
;
1157 Sets the length of the \bt_darray_field \bt_p{field}.
1160 Dynamic array field of which to set the length.
1162 New length of \bt_p{field}.
1164 @retval #BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_OK
1166 @retval #BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR
1169 @bt_pre_not_null{field}
1170 @bt_pre_is_darray_field{field}
1173 extern bt_field_array_dynamic_set_length_status
1174 bt_field_array_dynamic_set_length(bt_field
*field
, uint64_t length
);
1179 @name Structure field
1185 Borrows the field of the member at index \bt_p{index} from the
1186 \bt_struct_field \bt_p{field}.
1189 Structure field from which to borrow the field of the member at
1192 Index of the member containing the field to borrow from
1197 \em Borrowed reference of the field of the member of \bt_p{field} at
1200 The returned pointer remains valid as long as \bt_p{field} exists.
1203 @bt_pre_not_null{field}
1204 @bt_pre_is_struct_field{field}
1206 \bt_p{index} is less than the number of members in the
1207 \ref api-tir-fc-struct "class" of \bt_p{field} (as
1208 returned by bt_field_class_structure_get_member_count()).
1210 @sa bt_field_structure_borrow_member_field_by_index_const() —
1211 \c const version of this function.
1213 extern bt_field
*bt_field_structure_borrow_member_field_by_index(
1214 bt_field
*field
, uint64_t index
);
1218 Borrows the field of the member at index \bt_p{index} from the
1219 \bt_struct_field \bt_p{field} (\c const version).
1221 See bt_field_structure_borrow_member_field_by_index().
1223 extern const bt_field
*
1224 bt_field_structure_borrow_member_field_by_index_const(
1225 const bt_field
*field
, uint64_t index
);
1229 Borrows the field of the member having the name \bt_p{name} from the
1230 \bt_struct_field \bt_p{field}.
1232 If there's no member having the name \bt_p{name} in the
1233 \ref api-tir-fc-struct "class" of \bt_p{field}, this function
1237 Structure field from which to borrow the field of the member having
1238 the name \bt_p{name}.
1240 Name of the member containing the field to borrow from \bt_p{field}.
1244 \em Borrowed reference of the field of the member of \bt_p{field}
1245 having the name \bt_p{name}, or \c NULL if none.
1247 The returned pointer remains valid as long as \bt_p{field} exists.
1250 @bt_pre_not_null{field}
1251 @bt_pre_is_struct_field{field}
1252 @bt_pre_not_null{name}
1254 @sa bt_field_structure_borrow_member_field_by_name_const() —
1255 \c const version of this function.
1257 extern bt_field
*bt_field_structure_borrow_member_field_by_name(
1258 bt_field
*field
, const char *name
);
1262 Borrows the field of the member having the name \bt_p{name} from the
1263 \bt_struct_field \bt_p{field} (\c const version).
1265 See bt_field_structure_borrow_member_field_by_name().
1267 extern const bt_field
*
1268 bt_field_structure_borrow_member_field_by_name_const(
1269 const bt_field
*field
, const char *name
);
1280 Sets whether or not the \bt_opt_field \bt_p{field}
1284 Option field of which to set whether or not it has a field.
1285 @param[in] has_field
1286 #BT_TRUE to make \bt_p{field} have a field.
1288 @bt_pre_not_null{field}
1289 @bt_pre_is_opt_field{field}
1291 extern void bt_field_option_set_has_field(bt_field
*field
, bt_bool has_field
);
1295 Borrows the field of the \bt_opt_field \bt_p{field}.
1298 You must call bt_field_option_set_has_field() before you call
1301 If \bt_p{field} has no field, this function returns \c NULL.
1304 Option field from which to borrow the field.
1308 \em Borrowed reference of the field of \bt_p{field},
1311 The returned pointer remains valid as long as \bt_p{field} exists.
1314 @bt_pre_not_null{field}
1315 @bt_pre_is_opt_field{field}
1317 @sa bt_field_option_set_has_field() —
1318 Sets whether or not an option field has a field.
1319 @sa bt_field_option_borrow_field_const() —
1320 \c const version of this function.
1322 extern bt_field
*bt_field_option_borrow_field(bt_field
*field
);
1326 Borrows the field of the \bt_opt_field \bt_p{field}
1329 See bt_field_option_borrow_field().
1331 extern const bt_field
*
1332 bt_field_option_borrow_field_const(const bt_field
*field
);
1343 Status code for bt_field_variant_select_option_by_index().
1345 typedef enum bt_field_variant_select_option_by_index_status
{
1350 BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1351 } bt_field_variant_select_option_by_index_status
;
1355 Sets the selected option of the \bt_var_field \bt_p{field}
1356 to the option at index \bt_p{index}.
1359 Variant field of which to set the selected option.
1361 Index of the option to set as the selected option of \bt_p{field}.
1363 @retval #BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK
1366 @bt_pre_not_null{field}
1367 @bt_pre_is_var_field{field}
1369 \bt_p{index} is less than the number of options in the
1370 \ref api-tir-fc-var "class" of \bt_p{field} (as
1371 returned by bt_field_class_variant_get_option_count()).
1373 extern bt_field_variant_select_option_by_index_status
1374 bt_field_variant_select_option_by_index(
1375 bt_field
*field
, uint64_t index
);
1379 Borrows the field of the selected option of the \bt_var_field
1383 You must call bt_field_variant_select_option_by_index() before
1384 you call this function.
1387 Variant field from which to borrow the selected option's field.
1391 \em Borrowed reference of the field of the selected option of
1392 \bt_p{field}, or \c NULL if none.
1394 The returned pointer remains valid as long as \bt_p{field} exists.
1397 @bt_pre_not_null{field}
1398 @bt_pre_is_var_field{field}
1400 @sa bt_field_variant_select_option_by_index() —
1401 Sets a variant field's selected option.
1402 @sa bt_field_variant_get_selected_option_index() —
1403 Returns the index of a variant field's selected option.
1404 @sa bt_field_variant_borrow_selected_option_field_const() —
1405 \c const version of this function.
1407 extern bt_field
*bt_field_variant_borrow_selected_option_field(
1412 Borrows the field of the selected option of the \bt_var_field
1413 \bt_p{field} (\c const version).
1415 See bt_field_variant_borrow_selected_option_field().
1417 extern const bt_field
*
1418 bt_field_variant_borrow_selected_option_field_const(
1419 const bt_field
*field
);
1423 Returns the index of the selected option of the \bt_var_field
1427 Variant field of which to get the index of the selected option.
1430 Index of the selected option of \bt_p{field}.
1432 @bt_pre_not_null{field}
1433 @bt_pre_is_var_field{field}
1435 @sa bt_field_variant_borrow_selected_option_field_const() —
1436 Borrows the field of a variant field's selected option.
1438 extern uint64_t bt_field_variant_get_selected_option_index(
1439 const bt_field
*field
);
1443 Borrows the class of the selected option of the \bt_var_field
1446 This function returns
1449 bt_field_class_variant_borrow_option_by_index(
1450 bt_field_variant_get_selected_option_index(field))
1454 Variant field of which to get the selected option's class.
1457 Class of the selected option of \bt_p{field}.
1459 @bt_pre_not_null{field}
1460 @bt_pre_is_var_field{field}
1462 extern const bt_field_class_variant_option
*
1463 bt_field_variant_borrow_selected_option_class_const(
1464 const bt_field
*field
);
1468 Borrows the class of the selected option of the \bt_var_field
1469 (with an unsigned integer selector field) \bt_p{field}.
1471 This function returns
1474 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(
1475 bt_field_variant_get_selected_option_index(field))
1479 Variant field of which to get the selected option's class.
1482 Class of the selected option of \bt_p{field}.
1484 @bt_pre_not_null{field}
1485 @bt_pre_is_var_wuis_field{field}
1487 extern const bt_field_class_variant_with_selector_field_integer_unsigned_option
*
1488 bt_field_variant_with_selector_field_integer_unsigned_borrow_selected_option_class_const(
1489 const bt_field
*field
);
1493 Borrows the class of the selected option of the \bt_var_field
1494 (with a signed integer selector field) \bt_p{field}.
1496 This function returns
1499 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(
1500 bt_field_variant_get_selected_option_index(field))
1504 Variant field of which to get the selected option's class.
1507 Class of the selected option of \bt_p{field}.
1509 @bt_pre_not_null{field}
1510 @bt_pre_is_var_wsis_field{field}
1512 extern const bt_field_class_variant_with_selector_field_integer_signed_option
*
1513 bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const(
1514 const bt_field
*field
);
1524 #endif /* BABELTRACE2_TRACE_IR_FIELD_H */