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 #ifndef __BT_IN_BABELTRACE_H
11 # error "Please include <babeltrace2/babeltrace.h> instead."
16 #include <babeltrace2/types.h>
23 @defgroup api-tir-field Fields
27 Containers of trace data.
29 <strong><em>Fields</em></strong> are containers of trace data: they are
30 found in \bt_p_ev and \bt_p_pkt.
32 Fields are instances of \bt_p_fc:
34 @image html field-class-zoom.png
36 Borrow the class of a field with bt_field_borrow_class() and
37 bt_field_borrow_class_const().
39 Fields are \ref api-tir "trace IR" data objects.
41 There are many types of fields. They can be divided into two main
47 Fields which contain a simple value.
49 The scalar fields are:
51 - \ref api-tir-field-bool "Boolean"
52 - \ref api-tir-field-ba "Bit array"
53 - \ref api-tir-field-int "Integer" (unsigned and signed)
54 - \ref api-tir-field-enum "Enumeration" (unsigned and signed)
55 - \ref api-tir-field-real "Real" (single-precision and double-precision)
56 - \ref api-tir-field-string "String"
61 Fields which contain other fields.
63 The container fields are:
65 - \ref api-tir-field-array "Array" (static and dynamic)
66 - \ref api-tir-field-struct "Structure"
67 - \ref api-tir-field-opt "Option"
68 - \ref api-tir-field-var "Variant"
72 @image html fc-to-field.png "Fields (green) are instances of field classes (orange)."
74 You cannot directly create a field: there are no
75 <code>bt_field_*_create()</code> functions. The \bt_name library
76 creates fields within an \bt_ev or a \bt_pkt from \bt_p_fc.
77 Therefore, to fill the payload fields of an \bt_ev, you must first
78 borrow the event's existing payload \bt_struct_field with
79 bt_event_borrow_payload_field() and then borrow each field, recursively,
82 The functions to borrow a field from an event or a packet are:
84 - bt_packet_borrow_context_field() and
85 bt_packet_borrow_context_field_const()
86 - bt_event_borrow_common_context_field() and
87 bt_event_borrow_common_context_field_const()
88 - bt_event_borrow_specific_context_field() and
89 bt_event_borrow_specific_context_field_const()
90 - bt_event_borrow_payload_field() and
91 bt_event_borrow_payload_field_const()
93 Some fields conceptually inherit other fields, eventually
94 making an inheritance hierarchy. For example, an \bt_enum_field
95 \em is an \bt_int_field. Therefore, an enumeration field holds an
96 integral value, just like an integer field does.
98 The complete field inheritance hierarchy is:
100 @image html all-fields.png
102 This is the same inheritance hierarchy as the \bt_fc inheritance
105 In the illustration above:
107 - A field with a dark background is instantiated from a concrete \bt_fc,
108 which you can directly create with a dedicated
109 <code>bt_field_class_*_create()</code> function.
111 - A field with a pale background is an \em abstract field: it's not a
112 concrete instance, but it can have properties, therefore there can be
113 functions which apply to it.
115 For example, bt_field_integer_signed_set_value() applies to any
118 Fields are \ref api-fund-unique-object "unique objects": they belong
119 to an \bt_ev or to a \bt_pkt.
121 Some library functions \ref api-fund-freezing "freeze" fields on
122 success. The documentation of those functions indicate this
125 All the field types share the same C type, #bt_field.
127 Get the type enumerator of a field's class with bt_field_get_class_type().
128 Get whether or not a field class type conceptually \em is a given type
129 with the inline bt_field_class_type_is() function.
131 <h1>\anchor api-tir-field-bool Boolean field</h1>
133 A <strong><em>boolean field</em></strong> is a \bt_bool_fc instance.
135 A boolean field contains a boolean value (#BT_TRUE or #BT_FALSE).
137 Set the value of a boolean field with bt_field_bool_set_value().
139 Get the value of a boolean field with bt_field_bool_get_value().
141 <h1>\anchor api-tir-field-ba Bit array field</h1>
143 A <strong><em>bit array field</em></strong> is a \bt_ba_fc instance.
145 A bit array field contains a fixed-length array of bits. Its length
146 is \ref api-tir-fc-ba-prop-len "given by its class".
148 The bit array field API interprets the array as an unsigned integer
149 value: the least significant bit's index is 0.
151 For example, to get whether or not bit 3 of a bit array field is
155 uint64_t value = bt_field_bit_array_get_value_as_integer(field);
157 if (value & (UINT64_C(1) << UINT64_C(3))) {
162 Set the bits of a bit array field with
163 bt_field_bit_array_set_value_as_integer().
165 Get the bits of a bit array field with
166 bt_field_bit_array_get_value_as_integer().
168 <h1>\anchor api-tir-field-int Integer fields</h1>
170 <strong><em>Integer fields</em></strong> are \bt_int_fc instances.
172 Integer fields contain integral values.
174 An integer field is an \em abstract field. The concrete integer fields
178 <dt>Unsigned integer field</dt>
180 An \bt_uint_fc instance.
182 An unsigned integer field contains an unsigned integral value
185 Set the value of an unsigned integer field with
186 bt_field_integer_unsigned_set_value().
188 Get the value of an unsigned integer field with
189 bt_field_integer_unsigned_get_value().
192 <dt>Signed integer field</dt>
194 A \bt_sint_fc instance.
196 A signed integer field contains a signed integral value (\c int64_t).
198 Set the value of a signed integer field with
199 bt_field_integer_signed_set_value().
201 Get the value of a signed integer field with
202 bt_field_integer_signed_get_value().
206 <h2>\anchor api-tir-field-enum Enumeration fields</h2>
208 <strong><em>Enumeration fields</em></strong> are \bt_enum_fc instances.
210 Enumeration fields \em are \bt_p_int_field: they contain integral
213 An enumeration field is an \em abstract field.
214 The concrete enumeration fields are:
217 <dt>Unsigned enumeration field</dt>
219 An \bt_uenum_fc instance.
221 An unsigned enumeration field contains an unsigned integral value
224 Set the value of an unsigned enumeration field with
225 bt_field_integer_unsigned_set_value().
227 Get the value of an unsigned enumeration field with
228 bt_field_integer_unsigned_get_value().
230 Get all the enumeration field class labels mapped to the value of a
231 given unsigned enumeration field with
232 bt_field_enumeration_unsigned_get_mapping_labels().
235 <dt>Signed enumeration field</dt>
237 A \bt_senum_fc instance.
239 A signed enumeration field contains a signed integral value
242 Set the value of a signed enumeration field with
243 bt_field_integer_signed_set_value().
245 Get the value of a signed enumeration field with
246 bt_field_integer_signed_get_value().
248 Get all the enumeration field class labels mapped to the value of a
249 given signed enumeration field with
250 bt_field_enumeration_signed_get_mapping_labels().
254 <h1>\anchor api-tir-field-real Real fields</h1>
256 <strong><em>Real fields</em></strong> are \bt_real_fc instances.
259 <a href="https://en.wikipedia.org/wiki/Real_number">real</a>
260 values (\c float or \c double types).
262 A real field is an \em abstract field. The concrete real fields are:
265 <dt>Single-precision real field</dt>
267 A single-precision real field class instance.
269 A single-precision real field contains a \c float value.
271 Set the value of a single-precision real field with
272 bt_field_real_single_precision_set_value().
274 Get the value of a single-precision real field with
275 bt_field_real_single_precision_get_value().
278 <dt>Double-precision real field</dt>
280 A double-precision real field class instance.
282 A double-precision real field contains a \c double value.
284 Set the value of a double-precision real field with
285 bt_field_real_double_precision_set_value().
287 Get the value of a double-precision real field with
288 bt_field_real_double_precision_get_value().
292 <h1>\anchor api-tir-field-string String field</h1>
294 A <strong><em>string field</em></strong> is a \bt_string_fc instance.
296 A string field contains an UTF-8 string value.
298 Set the value of a string field with
299 bt_field_string_set_value().
301 Get the value of a string field with
302 bt_field_string_get_value().
304 Get the length of a string field with
305 bt_field_string_get_length().
307 Append a string to a string field's current value with
308 bt_field_string_append() and bt_field_string_append_with_length().
310 Clear a string field with bt_field_string_clear().
312 <h1>\anchor api-tir-field-array Array fields</h1>
314 <strong><em>Array fields</em></strong> are \bt_array_fc instances.
316 Array fields contain zero or more fields which have the same class.
318 An array field is an \em abstract field. The concrete array fields are:
321 <dt>Static array field</dt>
323 A \bt_sarray_fc instance.
325 A static array field contains a fixed number of fields. Its length
326 is \ref api-tir-fc-sarray-prop-len "given by its class".
329 <dt>Dynamic array field class</dt>
331 A \bt_darray_fc instance.
333 A dynamic array field contains a variable number of fields, that is,
334 each instance of the same dynamic array field class can contain a
335 different number of elements.
337 Set a dynamic array field's length with
338 bt_field_array_dynamic_set_length() before you borrow any of its
343 Get an array field's length with bt_field_array_get_length().
345 Borrow a field from an array field at a given index with
346 bt_field_array_borrow_element_field_by_index() and
347 bt_field_array_borrow_element_field_by_index_const().
349 <h1>\anchor api-tir-field-struct Structure field</h1>
351 A <strong><em>structure field</em></strong> is a \bt_struct_fc instance.
353 A structure field contains an ordered list of zero or more members. A
354 structure field member contains a field: it's an instance of a structure
357 Borrow a member's field from a structure field at a given index with
358 bt_field_structure_borrow_member_field_by_index() and
359 bt_field_structure_borrow_member_field_by_index_const().
361 Borrow a member's field from a structure field by name with
362 bt_field_structure_borrow_member_field_by_name() and
363 bt_field_structure_borrow_member_field_by_name_const().
365 <h1>\anchor api-tir-field-opt Option field</h1>
367 An <strong><em>option field</em></strong> is an \bt_opt_fc instance.
369 An option field either does or doesn't contain a field.
371 Set whether or not an option field has a field with
372 bt_field_option_set_has_field().
374 Borrow the field from an option field with
375 bt_field_option_borrow_field() or
376 bt_field_option_borrow_field_const().
378 <h1>\anchor api-tir-field-var Variant field</h1>
380 A <strong><em>variant field</em></strong> is a \bt_var_fc instance.
382 A variant field has a single selected option amongst one or more
383 possible options. A variant field option contains a field: it's an
384 instance of a variant field class option.
386 Set the current option of a variant field with
387 bt_field_variant_select_option_by_index().
389 Get a variant field's selected option's index with
390 bt_field_variant_get_selected_option_index().
392 Borrow a variant field's selected option's field with
393 bt_field_variant_borrow_selected_option_field() and
394 bt_field_variant_borrow_selected_option_field_const().
396 Borrow the class of a variant field's selected
397 option with bt_field_variant_borrow_selected_option_class_const(),
398 bt_field_variant_with_selector_field_integer_unsigned_borrow_selected_option_class_const(),
400 bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const().
409 @typedef struct bt_field bt_field;
424 Returns the type enumerator of the \ref api-tir-fc "class" of the
427 This function returns
430 bt_field_class_get_type(bt_field_borrow_class(field))
434 Field of which to get the class's type enumerator
437 Type enumerator of the class of \bt_p{field}.
439 @bt_pre_not_null{field}
441 @sa bt_field_class_get_type() —
442 Returns the type enumerator of a \bt_fc.
444 extern bt_field_class_type
bt_field_get_class_type(
445 const bt_field
*field
);
456 Borrows the \ref api-tir-fc "class" of the field \bt_p{field}.
459 Field of which to borrow the class.
462 \em Borrowed reference of the class of \bt_p{field}.
464 @bt_pre_not_null{field}
466 @sa bt_field_borrow_class_const() —
467 \c const version of this function.
469 extern bt_field_class
*bt_field_borrow_class(bt_field
*field
);
473 Borrows the \ref api-tir-fc "class" of the field \bt_p{field}
476 See bt_field_borrow_class().
478 extern const bt_field_class
*bt_field_borrow_class_const(
479 const bt_field
*field
);
490 Sets the value of the \bt_bool_field \bt_p{field} to
494 Boolean field of which to set the value to \bt_p{value}.
496 New value of \bt_p{field}.
498 @bt_pre_not_null{field}
499 @bt_pre_is_bool_field{field}
502 @sa bt_field_bool_get_value() —
503 Returns the value of a boolean field.
505 extern void bt_field_bool_set_value(bt_field
*field
, bt_bool value
);
509 Returns the value of the \bt_bool_field \bt_p{field}.
512 Boolean field of which to get the value.
515 Value of \bt_p{field}.
517 @bt_pre_not_null{field}
518 @bt_pre_is_bool_field{field}
520 @sa bt_field_bool_set_value() —
521 Sets the value of a boolean field.
523 extern bt_bool
bt_field_bool_get_value(const bt_field
*field
);
528 @name Bit array field
534 Sets the bits of the \bt_ba_field \bt_p{field} to the bits of
537 The least significant bit's index is 0.
539 See \bt_c_ba_field to learn more.
542 Bit array field of which to set the bits to \bt_p{bits}.
544 New bits of \bt_p{field}.
546 @bt_pre_not_null{field}
547 @bt_pre_is_ba_field{field}
550 @sa bt_field_bit_array_get_value_as_integer() —
551 Returns the bits of a bit array field as an integer.
553 extern void bt_field_bit_array_set_value_as_integer(bt_field
*field
,
558 Returns the bits of the \bt_ba_field \bt_p{field} as an
561 The least significant bit's index is 0.
563 See \bt_c_ba_field to learn more.
566 Bit array field of which to get the bits.
569 Bits of \bt_p{field} as an unsigned integer.
571 @bt_pre_not_null{field}
572 @bt_pre_is_ba_field{field}
574 @sa bt_field_bit_array_set_value_as_integer() —
575 Sets the bits of a bit array field from an integer.
577 extern uint64_t bt_field_bit_array_get_value_as_integer(
578 const bt_field
*field
);
589 Sets the value of the \bt_uint_field \bt_p{field} to
593 Unsigned integer field of which to set the value to \bt_p{value}.
595 New value of \bt_p{field}.
597 @bt_pre_not_null{field}
598 @bt_pre_is_uint_field{field}
601 \bt_p{value} is within the
602 \ref api-tir-fc-int-prop-size "field value range" of the
603 class of \bt_p{field}.
605 @sa bt_field_integer_unsigned_get_value() —
606 Returns the value of an unsigned integer field.
608 extern void bt_field_integer_unsigned_set_value(bt_field
*field
,
613 Returns the value of the \bt_uint_field \bt_p{field}.
616 Unsigned integer field of which to get the value.
619 Value of \bt_p{field}.
621 @bt_pre_not_null{field}
622 @bt_pre_is_uint_field{field}
624 @sa bt_field_integer_unsigned_set_value() —
625 Sets the value of an unsigned integer field.
627 extern uint64_t bt_field_integer_unsigned_get_value(
628 const bt_field
*field
);
632 Sets the value of the \bt_sint_field \bt_p{field} to
636 Signed integer field of which to set the value to \bt_p{value}.
638 New value of \bt_p{field}.
640 @bt_pre_not_null{field}
641 @bt_pre_is_sint_field{field}
644 \bt_p{value} is within the
645 \ref api-tir-fc-int-prop-size "field value range" of the
646 class of \bt_p{field}.
648 @sa bt_field_integer_signed_get_value() —
649 Returns the value of an signed integer field.
651 extern void bt_field_integer_signed_set_value(bt_field
*field
,
656 Returns the value of the \bt_sint_field \bt_p{field}.
659 Signed integer field of which to get the value.
662 Value of \bt_p{field}.
664 @bt_pre_not_null{field}
665 @bt_pre_is_sint_field{field}
667 @sa bt_field_integer_signed_set_value() —
668 Sets the value of an signed integer field.
670 extern int64_t bt_field_integer_signed_get_value(const bt_field
*field
);
675 @name Enumeration field
682 bt_field_enumeration_unsigned_get_mapping_labels() and
683 bt_field_enumeration_signed_get_mapping_labels().
685 typedef enum bt_field_enumeration_get_mapping_labels_status
{
690 BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK
= __BT_FUNC_STATUS_OK
,
696 BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
697 } bt_field_enumeration_get_mapping_labels_status
;
701 Returns an array of all the labels of the mappings of the
702 \ref api-tir-fc-enum "class" of the \bt_uenum_field \bt_p{field}
703 of which the \bt_p_uint_rg contain the integral value
706 This function returns
709 (bt_field_enumeration_get_mapping_labels_status)
710 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value(
711 bt_field_borrow_class_const(field),
712 bt_field_integer_unsigned_get_value(field),
717 Unsigned enumeration field having the class from which to get the
718 labels of the mappings of which the ranges contain its
722 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value().
725 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value().
727 @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK
729 @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR
732 @bt_pre_not_null{field}
733 @bt_pre_is_uenum_field{field}
734 @bt_pre_not_null{labels}
735 @bt_pre_not_null{count}
737 extern bt_field_enumeration_get_mapping_labels_status
738 bt_field_enumeration_unsigned_get_mapping_labels(const bt_field
*field
,
739 bt_field_class_enumeration_mapping_label_array
*labels
,
744 Returns an array of all the labels of the mappings of the
745 \ref api-tir-fc-enum "class" of the \bt_senum_field \bt_p{field}
746 of which the \bt_p_sint_rg contain the integral value
749 This function returns
752 (bt_field_enumeration_get_mapping_labels_status)
753 bt_field_class_enumeration_signed_get_mapping_labels_for_value(
754 bt_field_borrow_class_const(field),
755 bt_field_integer_signed_get_value(field),
760 Signed enumeration field having the class from which to get the
761 labels of the mappings of which the ranges contain its
765 bt_field_class_enumeration_signed_get_mapping_labels_for_value().
768 bt_field_class_enumeration_signed_get_mapping_labels_for_value().
770 @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK
772 @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR
775 @bt_pre_not_null{field}
776 @bt_pre_is_senum_field{field}
777 @bt_pre_not_null{labels}
778 @bt_pre_not_null{count}
780 extern bt_field_enumeration_get_mapping_labels_status
781 bt_field_enumeration_signed_get_mapping_labels(const bt_field
*field
,
782 bt_field_class_enumeration_mapping_label_array
*labels
,
794 Sets the value of the \bt_sreal_field \bt_p{field} to
798 Single-precision real field of which to set the value to
801 New value of \bt_p{field}.
803 @bt_pre_not_null{field}
804 @bt_pre_is_sreal_field{field}
807 @sa bt_field_real_single_precision_get_value() —
808 Returns the value of a single-precision real field.
810 extern void bt_field_real_single_precision_set_value(bt_field
*field
,
815 Returns the value of the \bt_sreal_field \bt_p{field}.
818 Single-precision real field of which to get the value.
821 Value of \bt_p{field}.
823 @bt_pre_not_null{field}
824 @bt_pre_is_sreal_field{field}
826 @sa bt_field_real_single_precision_set_value() —
827 Sets the value of a single-precision real field.
829 extern float bt_field_real_single_precision_get_value(const bt_field
*field
);
833 Sets the value of the \bt_dreal_field \bt_p{field} to
837 Double-precision real field of which to set the value to
840 New value of \bt_p{field}.
842 @bt_pre_not_null{field}
843 @bt_pre_is_dreal_field{field}
846 @sa bt_field_real_double_precision_get_value() —
847 Returns the value of a double-precision real field.
849 extern void bt_field_real_double_precision_set_value(bt_field
*field
,
854 Returns the value of the \bt_dreal_field \bt_p{field}.
857 Double-precision real field of which to get the value.
860 Value of \bt_p{field}.
862 @bt_pre_not_null{field}
863 @bt_pre_is_dreal_field{field}
865 @sa bt_field_real_double_precision_set_value() —
866 Sets the value of a double-precision real field.
868 extern double bt_field_real_double_precision_get_value(const bt_field
*field
);
879 Status codes for bt_field_string_set_value().
881 typedef enum bt_field_string_set_value_status
{
886 BT_FIELD_STRING_SET_VALUE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
892 BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
893 } bt_field_string_set_value_status
;
897 Sets the value of the \bt_string_field \bt_p{field} to
898 a copy of \bt_p{value}.
901 String field of which to set the value to \bt_p{value}.
903 New value of \bt_p{field} (copied).
905 @retval #BT_FIELD_STRING_SET_VALUE_STATUS_OK
907 @retval #BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR
910 @bt_pre_not_null{field}
911 @bt_pre_is_string_field{field}
913 @bt_pre_not_null{value}
915 @sa bt_field_string_get_value() —
916 Returns the value of a string field.
917 @sa bt_field_string_append() —
918 Appends a string to a string field.
919 @sa bt_field_string_clear() —
920 Clears a string field.
922 extern bt_field_string_set_value_status
bt_field_string_set_value(
923 bt_field
*field
, const char *value
);
927 Returns the length of the \bt_string_field \bt_p{field}.
930 String field of which to get the length.
933 Length of \bt_p{field}.
935 @bt_pre_not_null{field}
936 @bt_pre_is_string_field{field}
938 extern uint64_t bt_field_string_get_length(const bt_field
*field
);
942 Returns the value of the \bt_string_field \bt_p{field}.
945 String field of which to get the value.
949 Value of \bt_p{field}.
951 The returned pointer remains valid until \bt_p{field} is modified.
954 @bt_pre_not_null{field}
955 @bt_pre_is_string_field{field}
957 @sa bt_field_string_set_value() —
958 Sets the value of a string field.
960 extern const char *bt_field_string_get_value(const bt_field
*field
);
964 Status codes for bt_field_string_append() and
965 bt_field_string_append_with_length().
967 typedef enum bt_field_string_append_status
{
972 BT_FIELD_STRING_APPEND_STATUS_OK
= __BT_FUNC_STATUS_OK
,
978 BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
979 } bt_field_string_append_status
;
983 Appends a copy of the string \bt_p{value} to the current value of
984 the \bt_string_field \bt_p{field}.
987 If you didn't set the value of \bt_p{field} yet, you must call
988 bt_field_string_clear() before you call this function.
991 String field to which to append the string \bt_p{value}.
993 String to append to \bt_p{field} (copied).
995 @retval #BT_FIELD_STRING_APPEND_STATUS_OK
997 @retval #BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR
1000 @bt_pre_not_null{field}
1001 @bt_pre_is_string_field{field}
1003 @bt_pre_not_null{value}
1005 @sa bt_field_string_append_with_length() —
1006 Appends a string with a given length to a string field.
1007 @sa bt_field_string_set_value() —
1008 Sets the value of a string field.
1010 extern bt_field_string_append_status
bt_field_string_append(
1011 bt_field
*field
, const char *value
);
1015 Appends a copy of the first \bt_p{length} bytes of the string
1016 \bt_p{value} to the current value of the \bt_string_field
1020 If you didn't set the value of \bt_p{field} yet, you must call
1021 bt_field_string_clear() before you call this function.
1024 String field to which to append the first \bt_p{length} bytes of
1025 the string \bt_p{value}.
1027 String of which to append the first \bt_p{length} bytes to
1028 \bt_p{field} (copied).
1030 Number of bytes of \bt_p{value} to append to \bt_p{field}.
1032 @retval #BT_FIELD_STRING_APPEND_STATUS_OK
1034 @retval #BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR
1037 @bt_pre_not_null{field}
1038 @bt_pre_is_string_field{field}
1040 @bt_pre_not_null{value}
1042 @sa bt_field_string_append() —
1043 Appends a string to a string field.
1044 @sa bt_field_string_set_value() —
1045 Sets the value of a string field.
1047 extern bt_field_string_append_status
bt_field_string_append_with_length(
1048 bt_field
*field
, const char *value
, uint64_t length
);
1052 Clears the \bt_string_field \bt_p{field}, making its value an empty
1056 String field to clear.
1058 @bt_pre_not_null{field}
1059 @bt_pre_is_string_field{field}
1062 @sa bt_field_string_set_value() —
1063 Sets the value of a string field.
1065 extern void bt_field_string_clear(bt_field
*field
);
1076 Returns the length of the \bt_array_field \bt_p{field}.
1079 Array field of which to get the length.
1082 Length of \bt_p{field}.
1084 @bt_pre_not_null{field}
1085 @bt_pre_is_array_field{field}
1087 extern uint64_t bt_field_array_get_length(const bt_field
*field
);
1091 Borrows the field at index \bt_p{index} from the \bt_array_field
1095 If \bt_p{field} is a dynamic array field, it must have a length
1096 (call bt_field_array_dynamic_set_length()) before you call this
1100 Array field from which to borrow the field at index \bt_p{index}.
1102 Index of the field to borrow from \bt_p{field}.
1106 \em Borrowed reference of the field of \bt_p{field} at index
1109 The returned pointer remains valid as long as \bt_p{field} exists.
1112 @bt_pre_not_null{field}
1113 @bt_pre_is_array_field{field}
1115 \bt_p{index} is less than the length of \bt_p{field} (as returned by
1116 bt_field_array_get_length()).
1118 @sa bt_field_array_borrow_element_field_by_index_const() —
1119 \c const version of this function.
1121 extern bt_field
*bt_field_array_borrow_element_field_by_index(
1122 bt_field
*field
, uint64_t index
);
1126 Borrows the field at index \bt_p{index} from the \bt_array_field
1127 \bt_p{field} (\c const version).
1129 See bt_field_array_borrow_element_field_by_index().
1131 extern const bt_field
*
1132 bt_field_array_borrow_element_field_by_index_const(
1133 const bt_field
*field
, uint64_t index
);
1137 Status codes for bt_field_array_dynamic_set_length().
1139 typedef enum bt_field_array_dynamic_set_length_status
{
1144 BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1150 BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1151 } bt_field_array_dynamic_set_length_status
;
1155 Sets the length of the \bt_darray_field \bt_p{field}.
1158 Dynamic array field of which to set the length.
1160 New length of \bt_p{field}.
1162 @retval #BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_OK
1164 @retval #BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR
1167 @bt_pre_not_null{field}
1168 @bt_pre_is_darray_field{field}
1171 extern bt_field_array_dynamic_set_length_status
1172 bt_field_array_dynamic_set_length(bt_field
*field
, uint64_t length
);
1177 @name Structure field
1183 Borrows the field of the member at index \bt_p{index} from the
1184 \bt_struct_field \bt_p{field}.
1187 Structure field from which to borrow the field of the member at
1190 Index of the member containing the field to borrow from
1195 \em Borrowed reference of the field of the member of \bt_p{field} at
1198 The returned pointer remains valid as long as \bt_p{field} exists.
1201 @bt_pre_not_null{field}
1202 @bt_pre_is_struct_field{field}
1204 \bt_p{index} is less than the number of members in the
1205 \ref api-tir-fc-struct "class" of \bt_p{field} (as
1206 returned by bt_field_class_structure_get_member_count()).
1208 @sa bt_field_structure_borrow_member_field_by_index_const() —
1209 \c const version of this function.
1211 extern bt_field
*bt_field_structure_borrow_member_field_by_index(
1212 bt_field
*field
, uint64_t index
);
1216 Borrows the field of the member at index \bt_p{index} from the
1217 \bt_struct_field \bt_p{field} (\c const version).
1219 See bt_field_structure_borrow_member_field_by_index().
1221 extern const bt_field
*
1222 bt_field_structure_borrow_member_field_by_index_const(
1223 const bt_field
*field
, uint64_t index
);
1227 Borrows the field of the member having the name \bt_p{name} from the
1228 \bt_struct_field \bt_p{field}.
1230 If there's no member having the name \bt_p{name} in the
1231 \ref api-tir-fc-struct "class" of \bt_p{field}, this function
1235 Structure field from which to borrow the field of the member having
1236 the name \bt_p{name}.
1238 Name of the member containing the field to borrow from \bt_p{field}.
1242 \em Borrowed reference of the field of the member of \bt_p{field}
1243 having the name \bt_p{name}, or \c NULL if none.
1245 The returned pointer remains valid as long as \bt_p{field} exists.
1248 @bt_pre_not_null{field}
1249 @bt_pre_is_struct_field{field}
1250 @bt_pre_not_null{name}
1252 @sa bt_field_structure_borrow_member_field_by_name_const() —
1253 \c const version of this function.
1255 extern bt_field
*bt_field_structure_borrow_member_field_by_name(
1256 bt_field
*field
, const char *name
);
1260 Borrows the field of the member having the name \bt_p{name} from the
1261 \bt_struct_field \bt_p{field} (\c const version).
1263 See bt_field_structure_borrow_member_field_by_name().
1265 extern const bt_field
*
1266 bt_field_structure_borrow_member_field_by_name_const(
1267 const bt_field
*field
, const char *name
);
1278 Sets whether or not the \bt_opt_field \bt_p{field}
1282 Option field of which to set whether or not it has a field.
1283 @param[in] has_field
1284 #BT_TRUE to make \bt_p{field} have a field.
1286 @bt_pre_not_null{field}
1287 @bt_pre_is_opt_field{field}
1289 extern void bt_field_option_set_has_field(bt_field
*field
, bt_bool has_field
);
1293 Borrows the field of the \bt_opt_field \bt_p{field}.
1296 You must call bt_field_option_set_has_field() before you call
1299 If \bt_p{field} has no field, this function returns \c NULL.
1302 Option field from which to borrow the field.
1306 \em Borrowed reference of the field of \bt_p{field},
1309 The returned pointer remains valid as long as \bt_p{field} exists.
1312 @bt_pre_not_null{field}
1313 @bt_pre_is_opt_field{field}
1315 @sa bt_field_option_set_has_field() —
1316 Sets whether or not an option field has a field.
1317 @sa bt_field_option_borrow_field_const() —
1318 \c const version of this function.
1320 extern bt_field
*bt_field_option_borrow_field(bt_field
*field
);
1324 Borrows the field of the \bt_opt_field \bt_p{field}
1327 See bt_field_option_borrow_field().
1329 extern const bt_field
*
1330 bt_field_option_borrow_field_const(const bt_field
*field
);
1341 Status code for bt_field_variant_select_option_by_index().
1343 typedef enum bt_field_variant_select_option_by_index_status
{
1348 BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1349 } bt_field_variant_select_option_by_index_status
;
1353 Sets the selected option of the \bt_var_field \bt_p{field}
1354 to the option at index \bt_p{index}.
1357 Variant field of which to set the selected option.
1359 Index of the option to set as the selected option of \bt_p{field}.
1361 @retval #BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK
1364 @bt_pre_not_null{field}
1365 @bt_pre_is_var_field{field}
1367 \bt_p{index} is less than the number of options in the
1368 \ref api-tir-fc-var "class" of \bt_p{field} (as
1369 returned by bt_field_class_variant_get_option_count()).
1371 extern bt_field_variant_select_option_by_index_status
1372 bt_field_variant_select_option_by_index(
1373 bt_field
*field
, uint64_t index
);
1377 Borrows the field of the selected option of the \bt_var_field
1381 You must call bt_field_variant_select_option_by_index() before
1382 you call this function.
1385 Variant field from which to borrow the selected option's field.
1389 \em Borrowed reference of the field of the selected option of
1390 \bt_p{field}, or \c NULL if none.
1392 The returned pointer remains valid as long as \bt_p{field} exists.
1395 @bt_pre_not_null{field}
1396 @bt_pre_is_var_field{field}
1398 @sa bt_field_variant_select_option_by_index() —
1399 Sets a variant field's selected option.
1400 @sa bt_field_variant_get_selected_option_index() —
1401 Returns the index of a variant field's selected option.
1402 @sa bt_field_variant_borrow_selected_option_field_const() —
1403 \c const version of this function.
1405 extern bt_field
*bt_field_variant_borrow_selected_option_field(
1410 Borrows the field of the selected option of the \bt_var_field
1411 \bt_p{field} (\c const version).
1413 See bt_field_variant_borrow_selected_option_field().
1415 extern const bt_field
*
1416 bt_field_variant_borrow_selected_option_field_const(
1417 const bt_field
*field
);
1421 Returns the index of the selected option of the \bt_var_field
1425 Variant field of which to get the index of the selected option.
1428 Index of the selected option of \bt_p{field}.
1430 @bt_pre_not_null{field}
1431 @bt_pre_is_var_field{field}
1433 @sa bt_field_variant_borrow_selected_option_field_const() —
1434 Borrows the field of a variant field's selected option.
1436 extern uint64_t bt_field_variant_get_selected_option_index(
1437 const bt_field
*field
);
1441 Borrows the class of the selected option of the \bt_var_field
1444 This function returns
1447 bt_field_class_variant_borrow_option_by_index(
1448 bt_field_variant_get_selected_option_index(field))
1452 Variant field of which to get the selected option's class.
1455 Class of the selected option of \bt_p{field}.
1457 @bt_pre_not_null{field}
1458 @bt_pre_is_var_field{field}
1460 extern const bt_field_class_variant_option
*
1461 bt_field_variant_borrow_selected_option_class_const(
1462 const bt_field
*field
);
1466 Borrows the class of the selected option of the \bt_var_field
1467 (with an unsigned integer selector field) \bt_p{field}.
1469 This function returns
1472 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(
1473 bt_field_variant_get_selected_option_index(field))
1477 Variant field of which to get the selected option's class.
1480 Class of the selected option of \bt_p{field}.
1482 @bt_pre_not_null{field}
1483 @bt_pre_is_var_wuis_field{field}
1485 extern const bt_field_class_variant_with_selector_field_integer_unsigned_option
*
1486 bt_field_variant_with_selector_field_integer_unsigned_borrow_selected_option_class_const(
1487 const bt_field
*field
);
1491 Borrows the class of the selected option of the \bt_var_field
1492 (with a signed integer selector field) \bt_p{field}.
1494 This function returns
1497 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(
1498 bt_field_variant_get_selected_option_index(field))
1502 Variant field of which to get the selected option's class.
1505 Class of the selected option of \bt_p{field}.
1507 @bt_pre_not_null{field}
1508 @bt_pre_is_var_wsis_field{field}
1510 extern const bt_field_class_variant_with_selector_field_integer_signed_option
*
1511 bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const(
1512 const bt_field
*field
);
1522 #endif /* BABELTRACE2_TRACE_IR_FIELD_H */