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
) __BT_NOEXCEPT
;
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
) __BT_NOEXCEPT
;
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
) __BT_NOEXCEPT
;
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
)
512 Returns the value of the \bt_bool_field \bt_p{field}.
515 Boolean field of which to get the value.
518 Value of \bt_p{field}.
520 @bt_pre_not_null{field}
521 @bt_pre_is_bool_field{field}
523 @sa bt_field_bool_set_value() —
524 Sets the value of a boolean field.
526 extern bt_bool
bt_field_bool_get_value(const bt_field
*field
) __BT_NOEXCEPT
;
531 @name Bit array field
537 Sets the bits of the \bt_ba_field \bt_p{field} to the bits of
540 The least significant bit's index is 0.
542 See \bt_c_ba_field to learn more.
545 Bit array field of which to set the bits to \bt_p{bits}.
547 New bits of \bt_p{field}.
549 @bt_pre_not_null{field}
550 @bt_pre_is_ba_field{field}
553 @sa bt_field_bit_array_get_value_as_integer() —
554 Returns the bits of a bit array field as an integer.
556 extern void bt_field_bit_array_set_value_as_integer(bt_field
*field
,
557 uint64_t bits
) __BT_NOEXCEPT
;
561 Returns the bits of the \bt_ba_field \bt_p{field} as an
564 The least significant bit's index is 0.
566 See \bt_c_ba_field to learn more.
569 Bit array field of which to get the bits.
572 Bits of \bt_p{field} as an unsigned integer.
574 @bt_pre_not_null{field}
575 @bt_pre_is_ba_field{field}
577 @sa bt_field_bit_array_set_value_as_integer() —
578 Sets the bits of a bit array field from an integer.
580 extern uint64_t bt_field_bit_array_get_value_as_integer(
581 const bt_field
*field
) __BT_NOEXCEPT
;
592 Sets the value of the \bt_uint_field \bt_p{field} to
596 Unsigned integer field of which to set the value to \bt_p{value}.
598 New value of \bt_p{field}.
600 @bt_pre_not_null{field}
601 @bt_pre_is_uint_field{field}
604 \bt_p{value} is within the
605 \ref api-tir-fc-int-prop-size "field value range" of the
606 class of \bt_p{field}.
608 @sa bt_field_integer_unsigned_get_value() —
609 Returns the value of an unsigned integer field.
611 extern void bt_field_integer_unsigned_set_value(bt_field
*field
,
612 uint64_t value
) __BT_NOEXCEPT
;
616 Returns the value of the \bt_uint_field \bt_p{field}.
619 Unsigned integer field of which to get the value.
622 Value of \bt_p{field}.
624 @bt_pre_not_null{field}
625 @bt_pre_is_uint_field{field}
627 @sa bt_field_integer_unsigned_set_value() —
628 Sets the value of an unsigned integer field.
630 extern uint64_t bt_field_integer_unsigned_get_value(
631 const bt_field
*field
) __BT_NOEXCEPT
;
635 Sets the value of the \bt_sint_field \bt_p{field} to
639 Signed integer field of which to set the value to \bt_p{value}.
641 New value of \bt_p{field}.
643 @bt_pre_not_null{field}
644 @bt_pre_is_sint_field{field}
647 \bt_p{value} is within the
648 \ref api-tir-fc-int-prop-size "field value range" of the
649 class of \bt_p{field}.
651 @sa bt_field_integer_signed_get_value() —
652 Returns the value of an signed integer field.
654 extern void bt_field_integer_signed_set_value(bt_field
*field
,
655 int64_t value
) __BT_NOEXCEPT
;
659 Returns the value of the \bt_sint_field \bt_p{field}.
662 Signed integer field of which to get the value.
665 Value of \bt_p{field}.
667 @bt_pre_not_null{field}
668 @bt_pre_is_sint_field{field}
670 @sa bt_field_integer_signed_set_value() —
671 Sets the value of an signed integer field.
673 extern int64_t bt_field_integer_signed_get_value(
674 const bt_field
*field
) __BT_NOEXCEPT
;
679 @name Enumeration field
686 bt_field_enumeration_unsigned_get_mapping_labels() and
687 bt_field_enumeration_signed_get_mapping_labels().
689 typedef enum bt_field_enumeration_get_mapping_labels_status
{
694 BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK
= __BT_FUNC_STATUS_OK
,
700 BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
701 } bt_field_enumeration_get_mapping_labels_status
;
705 Returns an array of all the labels of the mappings of the
706 \ref api-tir-fc-enum "class" of the \bt_uenum_field \bt_p{field}
707 of which the \bt_p_uint_rg contain the integral value
710 This function returns
713 (bt_field_enumeration_get_mapping_labels_status)
714 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value(
715 bt_field_borrow_class_const(field),
716 bt_field_integer_unsigned_get_value(field),
721 Unsigned enumeration field having the class from which to get the
722 labels of the mappings of which the ranges contain its
726 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value().
729 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value().
731 @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK
733 @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR
736 @bt_pre_not_null{field}
737 @bt_pre_is_uenum_field{field}
738 @bt_pre_not_null{labels}
739 @bt_pre_not_null{count}
741 extern bt_field_enumeration_get_mapping_labels_status
742 bt_field_enumeration_unsigned_get_mapping_labels(const bt_field
*field
,
743 bt_field_class_enumeration_mapping_label_array
*labels
,
744 uint64_t *count
) __BT_NOEXCEPT
;
748 Returns an array of all the labels of the mappings of the
749 \ref api-tir-fc-enum "class" of the \bt_senum_field \bt_p{field}
750 of which the \bt_p_sint_rg contain the integral value
753 This function returns
756 (bt_field_enumeration_get_mapping_labels_status)
757 bt_field_class_enumeration_signed_get_mapping_labels_for_value(
758 bt_field_borrow_class_const(field),
759 bt_field_integer_signed_get_value(field),
764 Signed enumeration field having the class from which to get the
765 labels of the mappings of which the ranges contain its
769 bt_field_class_enumeration_signed_get_mapping_labels_for_value().
772 bt_field_class_enumeration_signed_get_mapping_labels_for_value().
774 @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK
776 @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR
779 @bt_pre_not_null{field}
780 @bt_pre_is_senum_field{field}
781 @bt_pre_not_null{labels}
782 @bt_pre_not_null{count}
784 extern bt_field_enumeration_get_mapping_labels_status
785 bt_field_enumeration_signed_get_mapping_labels(const bt_field
*field
,
786 bt_field_class_enumeration_mapping_label_array
*labels
,
787 uint64_t *count
) __BT_NOEXCEPT
;
798 Sets the value of the \bt_sreal_field \bt_p{field} to
802 Single-precision real field of which to set the value to
805 New value of \bt_p{field}.
807 @bt_pre_not_null{field}
808 @bt_pre_is_sreal_field{field}
811 @sa bt_field_real_single_precision_get_value() —
812 Returns the value of a single-precision real field.
814 extern void bt_field_real_single_precision_set_value(bt_field
*field
,
815 float value
) __BT_NOEXCEPT
;
819 Returns the value of the \bt_sreal_field \bt_p{field}.
822 Single-precision real field of which to get the value.
825 Value of \bt_p{field}.
827 @bt_pre_not_null{field}
828 @bt_pre_is_sreal_field{field}
830 @sa bt_field_real_single_precision_set_value() —
831 Sets the value of a single-precision real field.
833 extern float bt_field_real_single_precision_get_value(
834 const bt_field
*field
) __BT_NOEXCEPT
;
838 Sets the value of the \bt_dreal_field \bt_p{field} to
842 Double-precision real field of which to set the value to
845 New value of \bt_p{field}.
847 @bt_pre_not_null{field}
848 @bt_pre_is_dreal_field{field}
851 @sa bt_field_real_double_precision_get_value() —
852 Returns the value of a double-precision real field.
854 extern void bt_field_real_double_precision_set_value(bt_field
*field
,
855 double value
) __BT_NOEXCEPT
;
859 Returns the value of the \bt_dreal_field \bt_p{field}.
862 Double-precision real field of which to get the value.
865 Value of \bt_p{field}.
867 @bt_pre_not_null{field}
868 @bt_pre_is_dreal_field{field}
870 @sa bt_field_real_double_precision_set_value() —
871 Sets the value of a double-precision real field.
873 extern double bt_field_real_double_precision_get_value(
874 const bt_field
*field
) __BT_NOEXCEPT
;
885 Status codes for bt_field_string_set_value().
887 typedef enum bt_field_string_set_value_status
{
892 BT_FIELD_STRING_SET_VALUE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
898 BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
899 } bt_field_string_set_value_status
;
903 Sets the value of the \bt_string_field \bt_p{field} to
904 a copy of \bt_p{value}.
907 String field of which to set the value to \bt_p{value}.
909 New value of \bt_p{field} (copied).
911 @retval #BT_FIELD_STRING_SET_VALUE_STATUS_OK
913 @retval #BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR
916 @bt_pre_not_null{field}
917 @bt_pre_is_string_field{field}
919 @bt_pre_not_null{value}
921 @sa bt_field_string_get_value() —
922 Returns the value of a string field.
923 @sa bt_field_string_append() —
924 Appends a string to a string field.
925 @sa bt_field_string_clear() —
926 Clears a string field.
928 extern bt_field_string_set_value_status
bt_field_string_set_value(
929 bt_field
*field
, const char *value
) __BT_NOEXCEPT
;
933 Returns the length of the \bt_string_field \bt_p{field}.
936 String field of which to get the length.
939 Length of \bt_p{field}.
941 @bt_pre_not_null{field}
942 @bt_pre_is_string_field{field}
944 extern uint64_t bt_field_string_get_length(const bt_field
*field
) __BT_NOEXCEPT
;
948 Returns the value of the \bt_string_field \bt_p{field}.
951 String field of which to get the value.
955 Value of \bt_p{field}.
957 The returned pointer remains valid until \bt_p{field} is modified.
960 @bt_pre_not_null{field}
961 @bt_pre_is_string_field{field}
963 @sa bt_field_string_set_value() —
964 Sets the value of a string field.
966 extern const char *bt_field_string_get_value(
967 const bt_field
*field
) __BT_NOEXCEPT
;
971 Status codes for bt_field_string_append() and
972 bt_field_string_append_with_length().
974 typedef enum bt_field_string_append_status
{
979 BT_FIELD_STRING_APPEND_STATUS_OK
= __BT_FUNC_STATUS_OK
,
985 BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
986 } bt_field_string_append_status
;
990 Appends a copy of the string \bt_p{value} to the current value of
991 the \bt_string_field \bt_p{field}.
994 If you didn't set the value of \bt_p{field} yet, you must call
995 bt_field_string_clear() before you call this function.
998 String field to which to append the string \bt_p{value}.
1000 String to append to \bt_p{field} (copied).
1002 @retval #BT_FIELD_STRING_APPEND_STATUS_OK
1004 @retval #BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR
1007 @bt_pre_not_null{field}
1008 @bt_pre_is_string_field{field}
1010 @bt_pre_not_null{value}
1012 @sa bt_field_string_append_with_length() —
1013 Appends a string with a given length to a string field.
1014 @sa bt_field_string_set_value() —
1015 Sets the value of a string field.
1017 extern bt_field_string_append_status
bt_field_string_append(
1018 bt_field
*field
, const char *value
) __BT_NOEXCEPT
;
1022 Appends a copy of the first \bt_p{length} bytes of the string
1023 \bt_p{value} to the current value of the \bt_string_field
1027 If you didn't set the value of \bt_p{field} yet, you must call
1028 bt_field_string_clear() before you call this function.
1031 String field to which to append the first \bt_p{length} bytes of
1032 the string \bt_p{value}.
1034 String of which to append the first \bt_p{length} bytes to
1035 \bt_p{field} (copied).
1037 Number of bytes of \bt_p{value} to append to \bt_p{field}.
1039 @retval #BT_FIELD_STRING_APPEND_STATUS_OK
1041 @retval #BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR
1044 @bt_pre_not_null{field}
1045 @bt_pre_is_string_field{field}
1047 @bt_pre_not_null{value}
1049 @sa bt_field_string_append() —
1050 Appends a string to a string field.
1051 @sa bt_field_string_set_value() —
1052 Sets the value of a string field.
1054 extern bt_field_string_append_status
bt_field_string_append_with_length(
1055 bt_field
*field
, const char *value
, uint64_t length
)
1060 Clears the \bt_string_field \bt_p{field}, making its value an empty
1064 String field to clear.
1066 @bt_pre_not_null{field}
1067 @bt_pre_is_string_field{field}
1070 @sa bt_field_string_set_value() —
1071 Sets the value of a string field.
1073 extern void bt_field_string_clear(bt_field
*field
) __BT_NOEXCEPT
;
1084 Returns the length of the \bt_array_field \bt_p{field}.
1087 Array field of which to get the length.
1090 Length of \bt_p{field}.
1092 @bt_pre_not_null{field}
1093 @bt_pre_is_array_field{field}
1095 extern uint64_t bt_field_array_get_length(const bt_field
*field
) __BT_NOEXCEPT
;
1099 Borrows the field at index \bt_p{index} from the \bt_array_field
1103 If \bt_p{field} is a dynamic array field, it must have a length
1104 (call bt_field_array_dynamic_set_length()) before you call this
1108 Array field from which to borrow the field at index \bt_p{index}.
1110 Index of the field to borrow from \bt_p{field}.
1114 \em Borrowed reference of the field of \bt_p{field} at index
1117 The returned pointer remains valid as long as \bt_p{field} exists.
1120 @bt_pre_not_null{field}
1121 @bt_pre_is_array_field{field}
1123 \bt_p{index} is less than the length of \bt_p{field} (as returned by
1124 bt_field_array_get_length()).
1126 @sa bt_field_array_borrow_element_field_by_index_const() —
1127 \c const version of this function.
1129 extern bt_field
*bt_field_array_borrow_element_field_by_index(
1130 bt_field
*field
, uint64_t index
) __BT_NOEXCEPT
;
1134 Borrows the field at index \bt_p{index} from the \bt_array_field
1135 \bt_p{field} (\c const version).
1137 See bt_field_array_borrow_element_field_by_index().
1139 extern const bt_field
*
1140 bt_field_array_borrow_element_field_by_index_const(
1141 const bt_field
*field
, uint64_t index
) __BT_NOEXCEPT
;
1145 Status codes for bt_field_array_dynamic_set_length().
1147 typedef enum bt_field_array_dynamic_set_length_status
{
1152 BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1158 BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1159 } bt_field_array_dynamic_set_length_status
;
1163 Sets the length of the \bt_darray_field \bt_p{field}.
1166 Dynamic array field of which to set the length.
1168 New length of \bt_p{field}.
1170 @retval #BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_OK
1172 @retval #BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR
1175 @bt_pre_not_null{field}
1176 @bt_pre_is_darray_field{field}
1179 extern bt_field_array_dynamic_set_length_status
1180 bt_field_array_dynamic_set_length(bt_field
*field
, uint64_t length
)
1186 @name Structure field
1192 Borrows the field of the member at index \bt_p{index} from the
1193 \bt_struct_field \bt_p{field}.
1196 Structure field from which to borrow the field of the member at
1199 Index of the member containing the field to borrow from
1204 \em Borrowed reference of the field of the member of \bt_p{field} at
1207 The returned pointer remains valid as long as \bt_p{field} exists.
1210 @bt_pre_not_null{field}
1211 @bt_pre_is_struct_field{field}
1213 \bt_p{index} is less than the number of members in the
1214 \ref api-tir-fc-struct "class" of \bt_p{field} (as
1215 returned by bt_field_class_structure_get_member_count()).
1217 @sa bt_field_structure_borrow_member_field_by_index_const() —
1218 \c const version of this function.
1220 extern bt_field
*bt_field_structure_borrow_member_field_by_index(
1221 bt_field
*field
, uint64_t index
) __BT_NOEXCEPT
;
1225 Borrows the field of the member at index \bt_p{index} from the
1226 \bt_struct_field \bt_p{field} (\c const version).
1228 See bt_field_structure_borrow_member_field_by_index().
1230 extern const bt_field
*
1231 bt_field_structure_borrow_member_field_by_index_const(
1232 const bt_field
*field
, uint64_t index
) __BT_NOEXCEPT
;
1236 Borrows the field of the member having the name \bt_p{name} from the
1237 \bt_struct_field \bt_p{field}.
1239 If there's no member having the name \bt_p{name} in the
1240 \ref api-tir-fc-struct "class" of \bt_p{field}, this function
1244 Structure field from which to borrow the field of the member having
1245 the name \bt_p{name}.
1247 Name of the member containing the field to borrow from \bt_p{field}.
1251 \em Borrowed reference of the field of the member of \bt_p{field}
1252 having the name \bt_p{name}, or \c NULL if none.
1254 The returned pointer remains valid as long as \bt_p{field} exists.
1257 @bt_pre_not_null{field}
1258 @bt_pre_is_struct_field{field}
1259 @bt_pre_not_null{name}
1261 @sa bt_field_structure_borrow_member_field_by_name_const() —
1262 \c const version of this function.
1264 extern bt_field
*bt_field_structure_borrow_member_field_by_name(
1265 bt_field
*field
, const char *name
) __BT_NOEXCEPT
;
1269 Borrows the field of the member having the name \bt_p{name} from the
1270 \bt_struct_field \bt_p{field} (\c const version).
1272 See bt_field_structure_borrow_member_field_by_name().
1274 extern const bt_field
*
1275 bt_field_structure_borrow_member_field_by_name_const(
1276 const bt_field
*field
, const char *name
) __BT_NOEXCEPT
;
1287 Sets whether or not the \bt_opt_field \bt_p{field}
1291 Option field of which to set whether or not it has a field.
1292 @param[in] has_field
1293 #BT_TRUE to make \bt_p{field} have a field.
1295 @bt_pre_not_null{field}
1296 @bt_pre_is_opt_field{field}
1298 extern void bt_field_option_set_has_field(bt_field
*field
, bt_bool has_field
)
1303 Borrows the field of the \bt_opt_field \bt_p{field}.
1306 You must call bt_field_option_set_has_field() before you call
1309 If \bt_p{field} has no field, this function returns \c NULL.
1312 Option field from which to borrow the field.
1316 \em Borrowed reference of the field of \bt_p{field},
1319 The returned pointer remains valid as long as \bt_p{field} exists.
1322 @bt_pre_not_null{field}
1323 @bt_pre_is_opt_field{field}
1325 @sa bt_field_option_set_has_field() —
1326 Sets whether or not an option field has a field.
1327 @sa bt_field_option_borrow_field_const() —
1328 \c const version of this function.
1330 extern bt_field
*bt_field_option_borrow_field(bt_field
*field
) __BT_NOEXCEPT
;
1334 Borrows the field of the \bt_opt_field \bt_p{field}
1337 See bt_field_option_borrow_field().
1339 extern const bt_field
*
1340 bt_field_option_borrow_field_const(const bt_field
*field
) __BT_NOEXCEPT
;
1351 Status code for bt_field_variant_select_option_by_index().
1353 typedef enum bt_field_variant_select_option_by_index_status
{
1358 BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1359 } bt_field_variant_select_option_by_index_status
;
1363 Sets the selected option of the \bt_var_field \bt_p{field}
1364 to the option at index \bt_p{index}.
1367 Variant field of which to set the selected option.
1369 Index of the option to set as the selected option of \bt_p{field}.
1371 @retval #BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK
1374 @bt_pre_not_null{field}
1375 @bt_pre_is_var_field{field}
1377 \bt_p{index} is less than the number of options in the
1378 \ref api-tir-fc-var "class" of \bt_p{field} (as
1379 returned by bt_field_class_variant_get_option_count()).
1381 extern bt_field_variant_select_option_by_index_status
1382 bt_field_variant_select_option_by_index(
1383 bt_field
*field
, uint64_t index
) __BT_NOEXCEPT
;
1387 Borrows the field of the selected option of the \bt_var_field
1391 You must call bt_field_variant_select_option_by_index() before
1392 you call this function.
1395 Variant field from which to borrow the selected option's field.
1399 \em Borrowed reference of the field of the selected option of
1400 \bt_p{field}, or \c NULL if none.
1402 The returned pointer remains valid as long as \bt_p{field} exists.
1405 @bt_pre_not_null{field}
1406 @bt_pre_is_var_field{field}
1408 @sa bt_field_variant_select_option_by_index() —
1409 Sets a variant field's selected option.
1410 @sa bt_field_variant_get_selected_option_index() —
1411 Returns the index of a variant field's selected option.
1412 @sa bt_field_variant_borrow_selected_option_field_const() —
1413 \c const version of this function.
1415 extern bt_field
*bt_field_variant_borrow_selected_option_field(
1416 bt_field
*field
) __BT_NOEXCEPT
;
1420 Borrows the field of the selected option of the \bt_var_field
1421 \bt_p{field} (\c const version).
1423 See bt_field_variant_borrow_selected_option_field().
1425 extern const bt_field
*
1426 bt_field_variant_borrow_selected_option_field_const(
1427 const bt_field
*field
) __BT_NOEXCEPT
;
1431 Returns the index of the selected option of the \bt_var_field
1435 Variant field of which to get the index of the selected option.
1438 Index of the selected option of \bt_p{field}.
1440 @bt_pre_not_null{field}
1441 @bt_pre_is_var_field{field}
1443 @sa bt_field_variant_borrow_selected_option_field_const() —
1444 Borrows the field of a variant field's selected option.
1446 extern uint64_t bt_field_variant_get_selected_option_index(
1447 const bt_field
*field
) __BT_NOEXCEPT
;
1451 Borrows the class of the selected option of the \bt_var_field
1454 This function returns
1457 bt_field_class_variant_borrow_option_by_index(
1458 bt_field_variant_get_selected_option_index(field))
1462 Variant field of which to get the selected option's class.
1465 Class of the selected option of \bt_p{field}.
1467 @bt_pre_not_null{field}
1468 @bt_pre_is_var_field{field}
1470 extern const bt_field_class_variant_option
*
1471 bt_field_variant_borrow_selected_option_class_const(
1472 const bt_field
*field
) __BT_NOEXCEPT
;
1476 Borrows the class of the selected option of the \bt_var_field
1477 (with an unsigned integer selector field) \bt_p{field}.
1479 This function returns
1482 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(
1483 bt_field_variant_get_selected_option_index(field))
1487 Variant field of which to get the selected option's class.
1490 Class of the selected option of \bt_p{field}.
1492 @bt_pre_not_null{field}
1493 @bt_pre_is_var_wuis_field{field}
1495 extern const bt_field_class_variant_with_selector_field_integer_unsigned_option
*
1496 bt_field_variant_with_selector_field_integer_unsigned_borrow_selected_option_class_const(
1497 const bt_field
*field
) __BT_NOEXCEPT
;
1501 Borrows the class of the selected option of the \bt_var_field
1502 (with a signed integer selector field) \bt_p{field}.
1504 This function returns
1507 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(
1508 bt_field_variant_get_selected_option_index(field))
1512 Variant field of which to get the selected option's class.
1515 Class of the selected option of \bt_p{field}.
1517 @bt_pre_not_null{field}
1518 @bt_pre_is_var_wsis_field{field}
1520 extern const bt_field_class_variant_with_selector_field_integer_signed_option
*
1521 bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const(
1522 const bt_field
*field
) __BT_NOEXCEPT
;
1532 #endif /* BABELTRACE2_TRACE_IR_FIELD_H */