1 #ifndef BABELTRACE2_TRACE_IR_FIELD_H
2 #define BABELTRACE2_TRACE_IR_FIELD_H
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
32 #include <babeltrace2/types.h>
39 @defgroup api-tir-field Fields
43 Containers of trace data.
45 <strong><em>Fields</em></strong> are containers of trace data: they are
46 found in \bt_p_ev and \bt_p_pkt.
48 Fields are instances of \bt_p_fc:
50 @image html field-class-zoom.png
52 Borrow the class of a field with bt_field_borrow_class() and
53 bt_field_borrow_class_const().
55 Fields are \ref api-tir "trace IR" data objects.
57 There are many types of fields. They can be divided into two main
63 Fields which contain a simple value.
65 The scalar fields are:
67 - \ref api-tir-field-bool "Boolean"
68 - \ref api-tir-field-ba "Bit array"
69 - \ref api-tir-field-int "Integer" (unsigned and signed)
70 - \ref api-tir-field-enum "Enumeration" (unsigned and signed)
71 - \ref api-tir-field-real "Real" (single-precision and double-precision)
72 - \ref api-tir-field-string "String"
77 Fields which contain other fields.
79 The container fields are:
81 - \ref api-tir-field-array "Array" (static and dynamic)
82 - \ref api-tir-field-struct "Structure"
83 - \ref api-tir-field-opt "Option"
84 - \ref api-tir-field-var "Variant"
88 @image html fc-to-field.png "Fields (green) are instances of field classes (orange)."
90 You cannot directly create a field: there are no
91 <code>bt_field_*_create()</code> functions. The \bt_name library
92 creates fields within an \bt_ev or a \bt_pkt from \bt_p_fc.
93 Therefore, to fill the payload fields of an \bt_ev, you must first
94 borrow the event's existing payload \bt_struct_field with
95 bt_event_borrow_payload_field() and then borrow each field, recursively,
98 The functions to borrow a field from an event or a packet are:
100 - bt_packet_borrow_context_field() and
101 bt_packet_borrow_context_field_const()
102 - bt_event_borrow_common_context_field() and
103 bt_event_borrow_common_context_field_const()
104 - bt_event_borrow_specific_context_field() and
105 bt_event_borrow_specific_context_field_const()
106 - bt_event_borrow_payload_field() and
107 bt_event_borrow_payload_field_const()
109 Some fields conceptually inherit other fields, eventually
110 making an inheritance hierarchy. For example, an \bt_enum_field
111 \em is an \bt_int_field. Therefore, an enumeration field holds an
112 integral value, just like an integer field does.
114 The complete field inheritance hierarchy is:
116 @image html all-fields.png
118 This is the same inheritance hierarchy as the \bt_fc inheritance
121 In the illustration above:
123 - A field with a dark background is instantiated from a concrete \bt_fc,
124 which you can directly create with a dedicated
125 <code>bt_field_class_*_create()</code> function.
127 - A field with a pale background is an \em abstract field: it's not a
128 concrete instance, but it can have properties, therefore there can be
129 functions which apply to it.
131 For example, bt_field_integer_signed_set_value() applies to any
134 Fields are \ref api-fund-unique-object "unique objects": they belong
135 to an \bt_ev or to a \bt_pkt.
137 Some library functions \ref api-fund-freezing "freeze" fields on
138 success. The documentation of those functions indicate this
141 All the field types share the same C type, #bt_field.
143 Get the type enumerator of a field's class with bt_field_get_class_type().
144 Get whether or not a field class type conceptually \em is a given type
145 with the inline bt_field_class_type_is() function.
147 <h1>\anchor api-tir-field-bool Boolean field</h1>
149 A <strong><em>boolean field</em></strong> is a \bt_bool_fc instance.
151 A boolean field contains a boolean value (#BT_TRUE or #BT_FALSE).
153 Set the value of a boolean field with bt_field_bool_set_value().
155 Get the value of a boolean field with bt_field_bool_get_value().
157 <h1>\anchor api-tir-field-ba Bit array field</h1>
159 A <strong><em>bit array field</em></strong> is a \bt_ba_fc instance.
161 A bit array field contains a fixed-length array of bits. Its length
162 is \ref api-tir-fc-ba-prop-len "given by its class".
164 The bit array field API interprets the array as an unsigned integer
165 value: the least significant bit's index is 0.
167 For example, to get whether or not bit 3 of a bit array field is
171 uint64_t value = bt_field_bit_array_get_value_as_integer(field);
173 if (value & (UINT64_C(1) << UINT64_C(3))) {
178 Set the bits of a bit array field with
179 bt_field_bit_array_set_value_as_integer().
181 Get the bits of a bit array field with
182 bt_field_bit_array_get_value_as_integer().
184 <h1>\anchor api-tir-field-int Integer fields</h1>
186 <strong><em>Integer fields</em></strong> are \bt_int_fc instances.
188 Integer fields contain integral values.
190 An integer field is an \em abstract field. The concrete integer fields
194 <dt>Unsigned integer field</dt>
196 An \bt_uint_fc instance.
198 An unsigned integer field contains an unsigned integral value
201 Set the value of an unsigned integer field with
202 bt_field_integer_unsigned_set_value().
204 Get the value of an unsigned integer field with
205 bt_field_integer_unsigned_get_value().
208 <dt>Signed integer field</dt>
210 A \bt_sint_fc instance.
212 A signed integer field contains a signed integral value (\c int64_t).
214 Set the value of a signed integer field with
215 bt_field_integer_signed_set_value().
217 Get the value of a signed integer field with
218 bt_field_integer_signed_get_value().
222 <h2>\anchor api-tir-field-enum Enumeration fields</h2>
224 <strong><em>Enumeration fields</em></strong> are \bt_enum_fc instances.
226 Enumeration fields \em are \bt_p_int_field: they contain integral
229 An enumeration field is an \em abstract field.
230 The concrete enumeration fields are:
233 <dt>Unsigned enumeration field</dt>
235 An \bt_uenum_fc instance.
237 An unsigned enumeration field contains an unsigned integral value
240 Set the value of an unsigned enumeration field with
241 bt_field_integer_unsigned_set_value().
243 Get the value of an unsigned enumeration field with
244 bt_field_integer_unsigned_get_value().
246 Get all the enumeration field class labels mapped to the value of a
247 given unsigned enumeration field with
248 bt_field_enumeration_unsigned_get_mapping_labels().
251 <dt>Signed enumeration field</dt>
253 A \bt_senum_fc instance.
255 A signed enumeration field contains a signed integral value
258 Set the value of a signed enumeration field with
259 bt_field_integer_signed_set_value().
261 Get the value of a signed enumeration field with
262 bt_field_integer_signed_get_value().
264 Get all the enumeration field class labels mapped to the value of a
265 given signed enumeration field with
266 bt_field_enumeration_signed_get_mapping_labels().
270 <h1>\anchor api-tir-field-real Real fields</h1>
272 <strong><em>Real fields</em></strong> are \bt_real_fc instances.
275 <a href="https://en.wikipedia.org/wiki/Real_number">real</a>
276 values (\c float or \c double types).
278 A real field is an \em abstract field. The concrete real fields are:
281 <dt>Single-precision real field</dt>
283 A single-precision real field class instance.
285 A single-precision real field contains a \c float value.
287 Set the value of a single-precision real field with
288 bt_field_real_single_precision_set_value().
290 Get the value of a single-precision real field with
291 bt_field_real_single_precision_get_value().
294 <dt>Double-precision real field</dt>
296 A double-precision real field class instance.
298 A double-precision real field contains a \c double value.
300 Set the value of a double-precision real field with
301 bt_field_real_double_precision_set_value().
303 Get the value of a double-precision real field with
304 bt_field_real_double_precision_get_value().
308 <h1>\anchor api-tir-field-string String field</h1>
310 A <strong><em>string field</em></strong> is a \bt_string_fc instance.
312 A string field contains an UTF-8 string value.
314 Set the value of a string field with
315 bt_field_string_set_value().
317 Get the value of a string field with
318 bt_field_string_get_value().
320 Get the length of a string field with
321 bt_field_string_get_length().
323 Append a string to a string field's current value with
324 bt_field_string_append() and bt_field_string_append_with_length().
326 Clear a string field with bt_field_string_clear().
328 <h1>\anchor api-tir-field-array Array fields</h1>
330 <strong><em>Array fields</em></strong> are \bt_array_fc instances.
332 Array fields contain zero or more fields which have the same class.
334 An array field is an \em abstract field. The concrete array fields are:
337 <dt>Static array field</dt>
339 A \bt_sarray_fc instance.
341 A static array field contains a fixed number of fields. Its length
342 is \ref api-tir-fc-sarray-prop-len "given by its class".
345 <dt>Dynamic array field class</dt>
347 A \bt_darray_fc instance.
349 A dynamic array field contains a variable number of fields, that is,
350 each instance of the same dynamic array field class can contain a
351 different number of elements.
353 Set a dynamic array field's length with
354 bt_field_array_dynamic_set_length() before you borrow any of its
359 Get an array field's length with bt_field_array_get_length().
361 Borrow a field from an array field at a given index with
362 bt_field_array_borrow_element_field_by_index() and
363 bt_field_array_borrow_element_field_by_index_const().
365 <h1>\anchor api-tir-field-struct Structure field</h1>
367 A <strong><em>structure field</em></strong> is a \bt_struct_fc instance.
369 A structure field contains an ordered list of zero or more members. A
370 structure field member contains a field: it's an instance of a structure
373 Borrow a member's field from a structure field at a given index with
374 bt_field_structure_borrow_member_field_by_index() and
375 bt_field_structure_borrow_member_field_by_index_const().
377 Borrow a member's field from a structure field by name with
378 bt_field_structure_borrow_member_field_by_name() and
379 bt_field_structure_borrow_member_field_by_name_const().
381 <h1>\anchor api-tir-field-opt Option field</h1>
383 An <strong><em>option field</em></strong> is an \bt_opt_fc instance.
385 An option field either does or doesn't contain a field.
387 Set whether or not an option field has a field with
388 bt_field_option_set_has_field().
390 Borrow the field from an option field with
391 bt_field_option_borrow_field() or
392 bt_field_option_borrow_field_const().
394 <h1>\anchor api-tir-field-var Variant field</h1>
396 A <strong><em>variant field</em></strong> is a \bt_var_fc instance.
398 A variant field has a single selected option amongst one or more
399 possible options. A variant field option contains a field: it's an
400 instance of a variant field class option.
402 Set the current option of a variant field with
403 bt_field_variant_select_option_by_index().
405 Get a variant field's selected option's index with
406 bt_field_variant_get_selected_option_index().
408 Borrow a variant field's selected option's field with
409 bt_field_variant_borrow_selected_option_field() and
410 bt_field_variant_borrow_selected_option_field_const().
412 Borrow the class of a variant field's selected
413 option with bt_field_variant_borrow_selected_option_class_const(),
414 bt_field_variant_with_selector_field_integer_unsigned_borrow_selected_option_class_const(),
416 bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const().
425 @typedef struct bt_field bt_field;
440 Returns the type enumerator of the \ref api-tir-fc "class" of the
443 This function returns
446 bt_field_class_get_type(bt_field_borrow_class(field))
450 Field of which to get the class's type enumerator
453 Type enumerator of the class of \bt_p{field}.
455 @bt_pre_not_null{field}
457 @sa bt_field_class_get_type() —
458 Returns the type enumerator of a \bt_fc.
460 extern bt_field_class_type
bt_field_get_class_type(
461 const bt_field
*field
);
472 Borrows the \ref api-tir-fc "class" of the field \bt_p{field}.
475 Field of which to borrow the class.
478 \em Borrowed reference of the class of \bt_p{field}.
480 @bt_pre_not_null{field}
482 @sa bt_field_borrow_class_const() —
483 \c const version of this function.
485 extern bt_field_class
*bt_field_borrow_class(bt_field
*field
);
489 Borrows the \ref api-tir-fc "class" of the field \bt_p{field}
492 See bt_field_borrow_class().
494 extern const bt_field_class
*bt_field_borrow_class_const(
495 const bt_field
*field
);
506 Sets the value of the \bt_bool_field \bt_p{field} to
510 Boolean field of which to set the value to \bt_p{value}.
512 New value of \bt_p{field}.
514 @bt_pre_not_null{field}
515 @bt_pre_is_bool_field{field}
518 @sa bt_field_bool_get_value() —
519 Returns the value of a boolean field.
521 extern void bt_field_bool_set_value(bt_field
*field
, bt_bool value
);
525 Returns the value of the \bt_bool_field \bt_p{field}.
528 Boolean field of which to get the value.
531 Value of \bt_p{field}.
533 @bt_pre_not_null{field}
534 @bt_pre_is_bool_field{field}
536 @sa bt_field_bool_set_value() —
537 Sets the value of a boolean field.
539 extern bt_bool
bt_field_bool_get_value(const bt_field
*field
);
544 @name Bit array field
550 Sets the bits of the \bt_ba_field \bt_p{field} to the bits of
553 The least significant bit's index is 0.
555 See \bt_c_ba_field to learn more.
558 Bit array field of which to set the bits to \bt_p{bits}.
560 New bits of \bt_p{field}.
562 @bt_pre_not_null{field}
563 @bt_pre_is_ba_field{field}
566 @sa bt_field_bit_array_get_value_as_integer() —
567 Returns the bits of a bit array field as an integer.
569 extern void bt_field_bit_array_set_value_as_integer(bt_field
*field
,
574 Returns the bits of the \bt_ba_field \bt_p{field} as an
577 The least significant bit's index is 0.
579 See \bt_c_ba_field to learn more.
582 Bit array field of which to get the bits.
585 Bits of \bt_p{field} as an unsigned integer.
587 @bt_pre_not_null{field}
588 @bt_pre_is_ba_field{field}
590 @sa bt_field_bit_array_set_value_as_integer() —
591 Sets the bits of a bit array field from an integer.
593 extern uint64_t bt_field_bit_array_get_value_as_integer(
594 const bt_field
*field
);
605 Sets the value of the \bt_uint_field \bt_p{field} to
609 Unsigned integer field of which to set the value to \bt_p{value}.
611 New value of \bt_p{field}.
613 @bt_pre_not_null{field}
614 @bt_pre_is_uint_field{field}
617 \bt_p{value} is within the
618 \ref api-tir-fc-int-prop-size "field value range" of the
619 class of \bt_p{field}.
621 @sa bt_field_integer_unsigned_get_value() —
622 Returns the value of an unsigned integer field.
624 extern void bt_field_integer_unsigned_set_value(bt_field
*field
,
629 Returns the value of the \bt_uint_field \bt_p{field}.
632 Unsigned integer field of which to get the value.
635 Value of \bt_p{field}.
637 @bt_pre_not_null{field}
638 @bt_pre_is_uint_field{field}
640 @sa bt_field_integer_unsigned_set_value() —
641 Sets the value of an unsigned integer field.
643 extern uint64_t bt_field_integer_unsigned_get_value(
644 const bt_field
*field
);
648 Sets the value of the \bt_sint_field \bt_p{field} to
652 Signed integer field of which to set the value to \bt_p{value}.
654 New value of \bt_p{field}.
656 @bt_pre_not_null{field}
657 @bt_pre_is_sint_field{field}
660 \bt_p{value} is within the
661 \ref api-tir-fc-int-prop-size "field value range" of the
662 class of \bt_p{field}.
664 @sa bt_field_integer_signed_get_value() —
665 Returns the value of an signed integer field.
667 extern void bt_field_integer_signed_set_value(bt_field
*field
,
672 Returns the value of the \bt_sint_field \bt_p{field}.
675 Signed integer field of which to get the value.
678 Value of \bt_p{field}.
680 @bt_pre_not_null{field}
681 @bt_pre_is_sint_field{field}
683 @sa bt_field_integer_signed_set_value() —
684 Sets the value of an signed integer field.
686 extern int64_t bt_field_integer_signed_get_value(const bt_field
*field
);
691 @name Enumeration field
698 bt_field_enumeration_unsigned_get_mapping_labels() and
699 bt_field_enumeration_signed_get_mapping_labels().
701 typedef enum bt_field_enumeration_get_mapping_labels_status
{
706 BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK
= __BT_FUNC_STATUS_OK
,
712 BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
713 } bt_field_enumeration_get_mapping_labels_status
;
717 Returns an array of all the labels of the mappings of the
718 \ref api-tir-fc-enum "class" of the \bt_uenum_field \bt_p{field}
719 of which the \bt_p_uint_rg contain the integral value
722 This function returns
725 (bt_field_enumeration_get_mapping_labels_status)
726 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value(
727 bt_field_borrow_class_const(field),
728 bt_field_integer_unsigned_get_value(field),
733 Unsigned enumeration field having the class from which to get the
734 labels of the mappings of which the ranges contain its
738 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value().
741 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value().
743 @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK
745 @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR
748 @bt_pre_not_null{field}
749 @bt_pre_is_uenum_field{field}
750 @bt_pre_not_null{labels}
751 @bt_pre_not_null{count}
753 extern bt_field_enumeration_get_mapping_labels_status
754 bt_field_enumeration_unsigned_get_mapping_labels(const bt_field
*field
,
755 bt_field_class_enumeration_mapping_label_array
*labels
,
760 Returns an array of all the labels of the mappings of the
761 \ref api-tir-fc-enum "class" of the \bt_senum_field \bt_p{field}
762 of which the \bt_p_sint_rg contain the integral value
765 This function returns
768 (bt_field_enumeration_get_mapping_labels_status)
769 bt_field_class_enumeration_signed_get_mapping_labels_for_value(
770 bt_field_borrow_class_const(field),
771 bt_field_integer_signed_get_value(field),
776 Signed enumeration field having the class from which to get the
777 labels of the mappings of which the ranges contain its
781 bt_field_class_enumeration_signed_get_mapping_labels_for_value().
784 bt_field_class_enumeration_signed_get_mapping_labels_for_value().
786 @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK
788 @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR
791 @bt_pre_not_null{field}
792 @bt_pre_is_senum_field{field}
793 @bt_pre_not_null{labels}
794 @bt_pre_not_null{count}
796 extern bt_field_enumeration_get_mapping_labels_status
797 bt_field_enumeration_signed_get_mapping_labels(const bt_field
*field
,
798 bt_field_class_enumeration_mapping_label_array
*labels
,
810 Sets the value of the \bt_sreal_field \bt_p{field} to
814 Single-precision real field of which to set the value to
817 New value of \bt_p{field}.
819 @bt_pre_not_null{field}
820 @bt_pre_is_sreal_field{field}
823 @sa bt_field_real_single_precision_get_value() —
824 Returns the value of a single-precision real field.
826 extern void bt_field_real_single_precision_set_value(bt_field
*field
,
831 Returns the value of the \bt_sreal_field \bt_p{field}.
834 Single-precision real field of which to get the value.
837 Value of \bt_p{field}.
839 @bt_pre_not_null{field}
840 @bt_pre_is_sreal_field{field}
842 @sa bt_field_real_single_precision_set_value() —
843 Sets the value of a single-precision real field.
845 extern float bt_field_real_single_precision_get_value(const bt_field
*field
);
849 Sets the value of the \bt_dreal_field \bt_p{field} to
853 Double-precision real field of which to set the value to
856 New value of \bt_p{field}.
858 @bt_pre_not_null{field}
859 @bt_pre_is_dreal_field{field}
862 @sa bt_field_real_double_precision_get_value() —
863 Returns the value of a double-precision real field.
865 extern void bt_field_real_double_precision_set_value(bt_field
*field
,
870 Returns the value of the \bt_dreal_field \bt_p{field}.
873 Double-precision real field of which to get the value.
876 Value of \bt_p{field}.
878 @bt_pre_not_null{field}
879 @bt_pre_is_dreal_field{field}
881 @sa bt_field_real_double_precision_set_value() —
882 Sets the value of a double-precision real field.
884 extern double bt_field_real_double_precision_get_value(const bt_field
*field
);
895 Status codes for bt_field_string_set_value().
897 typedef enum bt_field_string_set_value_status
{
902 BT_FIELD_STRING_SET_VALUE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
908 BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
909 } bt_field_string_set_value_status
;
913 Sets the value of the \bt_string_field \bt_p{field} to
914 a copy of \bt_p{value}.
917 String field of which to set the value to \bt_p{value}.
919 New value of \bt_p{field} (copied).
921 @retval #BT_FIELD_STRING_SET_VALUE_STATUS_OK
923 @retval #BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR
926 @bt_pre_not_null{field}
927 @bt_pre_is_string_field{field}
929 @bt_pre_not_null{value}
931 @sa bt_field_string_get_value() —
932 Returns the value of a string field.
933 @sa bt_field_string_append() —
934 Appends a string to a string field.
935 @sa bt_field_string_clear() —
936 Clears a string field.
938 extern bt_field_string_set_value_status
bt_field_string_set_value(
939 bt_field
*field
, const char *value
);
943 Returns the length of the \bt_string_field \bt_p{field}.
946 String field of which to get the length.
949 Length of \bt_p{field}.
951 @bt_pre_not_null{field}
952 @bt_pre_is_string_field{field}
954 extern uint64_t bt_field_string_get_length(const bt_field
*field
);
958 Returns the value of the \bt_string_field \bt_p{field}.
961 String field of which to get the value.
965 Value of \bt_p{field}.
967 The returned pointer remains valid until \bt_p{field} is modified.
970 @bt_pre_not_null{field}
971 @bt_pre_is_string_field{field}
973 @sa bt_field_string_set_value() —
974 Sets the value of a string field.
976 extern const char *bt_field_string_get_value(const bt_field
*field
);
980 Status codes for bt_field_string_append() and
981 bt_field_string_append_with_length().
983 typedef enum bt_field_string_append_status
{
988 BT_FIELD_STRING_APPEND_STATUS_OK
= __BT_FUNC_STATUS_OK
,
994 BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
995 } bt_field_string_append_status
;
999 Appends a copy of the string \bt_p{value} to the current value of
1000 the \bt_string_field \bt_p{field}.
1003 If you didn't set the value of \bt_p{field} yet, you must call
1004 bt_field_string_clear() before you call this function.
1007 String field to which to append the string \bt_p{value}.
1009 String to append to \bt_p{field} (copied).
1011 @retval #BT_FIELD_STRING_APPEND_STATUS_OK
1013 @retval #BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR
1016 @bt_pre_not_null{field}
1017 @bt_pre_is_string_field{field}
1019 @bt_pre_not_null{value}
1021 @sa bt_field_string_append_with_length() —
1022 Appends a string with a given length to a string field.
1023 @sa bt_field_string_set_value() —
1024 Sets the value of a string field.
1026 extern bt_field_string_append_status
bt_field_string_append(
1027 bt_field
*field
, const char *value
);
1031 Appends a copy of the first \bt_p{length} bytes of the string
1032 \bt_p{value} to the current value of the \bt_string_field
1036 If you didn't set the value of \bt_p{field} yet, you must call
1037 bt_field_string_clear() before you call this function.
1040 String field to which to append the first \bt_p{length} bytes of
1041 the string \bt_p{value}.
1043 String of which to append the first \bt_p{length} bytes to
1044 \bt_p{field} (copied).
1046 Number of bytes of \bt_p{value} to append to \bt_p{field}.
1048 @retval #BT_FIELD_STRING_APPEND_STATUS_OK
1050 @retval #BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR
1053 @bt_pre_not_null{field}
1054 @bt_pre_is_string_field{field}
1056 @bt_pre_not_null{value}
1058 @sa bt_field_string_append() —
1059 Appends a string to a string field.
1060 @sa bt_field_string_set_value() —
1061 Sets the value of a string field.
1063 extern bt_field_string_append_status
bt_field_string_append_with_length(
1064 bt_field
*field
, const char *value
, uint64_t length
);
1068 Clears the \bt_string_field \bt_p{field}, making its value an empty
1072 String field to clear.
1074 @bt_pre_not_null{field}
1075 @bt_pre_is_string_field{field}
1078 @sa bt_field_string_set_value() —
1079 Sets the value of a string field.
1081 extern void bt_field_string_clear(bt_field
*field
);
1092 Returns the length of the \bt_array_field \bt_p{field}.
1095 Array field of which to get the length.
1098 Length of \bt_p{field}.
1100 @bt_pre_not_null{field}
1101 @bt_pre_is_array_field{field}
1103 extern uint64_t bt_field_array_get_length(const bt_field
*field
);
1107 Borrows the field at index \bt_p{index} from the \bt_array_field
1111 If \bt_p{field} is a dynamic array field, it must have a length
1112 (call bt_field_array_dynamic_set_length()) before you call this
1116 Array field from which to borrow the field at index \bt_p{index}.
1118 Index of the field to borrow from \bt_p{field}.
1122 \em Borrowed reference of the field of \bt_p{field} at index
1125 The returned pointer remains valid as long as \bt_p{field} exists.
1128 @bt_pre_not_null{field}
1129 @bt_pre_is_array_field{field}
1131 \bt_p{index} is less than the length of \bt_p{field} (as returned by
1132 bt_field_array_get_length()).
1134 @sa bt_field_array_borrow_element_field_by_index_const() —
1135 \c const version of this function.
1137 extern bt_field
*bt_field_array_borrow_element_field_by_index(
1138 bt_field
*field
, uint64_t index
);
1142 Borrows the field at index \bt_p{index} from the \bt_array_field
1143 \bt_p{field} (\c const version).
1145 See bt_field_array_borrow_element_field_by_index().
1147 extern const bt_field
*
1148 bt_field_array_borrow_element_field_by_index_const(
1149 const bt_field
*field
, uint64_t index
);
1153 Status codes for bt_field_array_dynamic_set_length().
1155 typedef enum bt_field_array_dynamic_set_length_status
{
1160 BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1166 BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1167 } bt_field_array_dynamic_set_length_status
;
1171 Sets the length of the \bt_darray_field \bt_p{field}.
1174 Dynamic array field of which to set the length.
1176 New length of \bt_p{field}.
1178 @retval #BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_OK
1180 @retval #BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR
1183 @bt_pre_not_null{field}
1184 @bt_pre_is_darray_field{field}
1187 extern bt_field_array_dynamic_set_length_status
1188 bt_field_array_dynamic_set_length(bt_field
*field
, uint64_t length
);
1193 @name Structure field
1199 Borrows the field of the member at index \bt_p{index} from the
1200 \bt_struct_field \bt_p{field}.
1203 Structure field from which to borrow the field of the member at
1206 Index of the member containing the field to borrow from
1211 \em Borrowed reference of the field of the member of \bt_p{field} at
1214 The returned pointer remains valid as long as \bt_p{field} exists.
1217 @bt_pre_not_null{field}
1218 @bt_pre_is_struct_field{field}
1220 \bt_p{index} is less than the number of members in the
1221 \ref api-tir-fc-struct "class" of \bt_p{field} (as
1222 returned by bt_field_class_structure_get_member_count()).
1224 @sa bt_field_structure_borrow_member_field_by_index_const() —
1225 \c const version of this function.
1227 extern bt_field
*bt_field_structure_borrow_member_field_by_index(
1228 bt_field
*field
, uint64_t index
);
1232 Borrows the field of the member at index \bt_p{index} from the
1233 \bt_struct_field \bt_p{field} (\c const version).
1235 See bt_field_structure_borrow_member_field_by_index().
1237 extern const bt_field
*
1238 bt_field_structure_borrow_member_field_by_index_const(
1239 const bt_field
*field
, uint64_t index
);
1243 Borrows the field of the member having the name \bt_p{name} from the
1244 \bt_struct_field \bt_p{field}.
1246 If there's no member having the name \bt_p{name} in the
1247 \ref api-tir-fc-struct "class" of \bt_p{field}, this function
1251 Structure field from which to borrow the field of the member having
1252 the name \bt_p{name}.
1254 Name of the member containing the field to borrow from \bt_p{field}.
1258 \em Borrowed reference of the field of the member of \bt_p{field}
1259 having the name \bt_p{name}, or \c NULL if none.
1261 The returned pointer remains valid as long as \bt_p{field} exists.
1264 @bt_pre_not_null{field}
1265 @bt_pre_is_struct_field{field}
1266 @bt_pre_not_null{name}
1268 @sa bt_field_structure_borrow_member_field_by_name_const() —
1269 \c const version of this function.
1271 extern bt_field
*bt_field_structure_borrow_member_field_by_name(
1272 bt_field
*field
, const char *name
);
1276 Borrows the field of the member having the name \bt_p{name} from the
1277 \bt_struct_field \bt_p{field} (\c const version).
1279 See bt_field_structure_borrow_member_field_by_name().
1281 extern const bt_field
*
1282 bt_field_structure_borrow_member_field_by_name_const(
1283 const bt_field
*field
, const char *name
);
1294 Sets whether or not the \bt_opt_field \bt_p{field}
1298 Option field of which to set whether or not it has a field.
1299 @param[in] has_field
1300 #BT_TRUE to make \bt_p{field} have a field.
1302 @bt_pre_not_null{field}
1303 @bt_pre_is_opt_field{field}
1305 extern void bt_field_option_set_has_field(bt_field
*field
, bt_bool has_field
);
1309 Borrows the field of the \bt_opt_field \bt_p{field}.
1312 You must call bt_field_option_set_has_field() before you call
1315 If \bt_p{field} has no field, this function returns \c NULL.
1318 Option field from which to borrow the field.
1322 \em Borrowed reference of the field of \bt_p{field},
1325 The returned pointer remains valid as long as \bt_p{field} exists.
1328 @bt_pre_not_null{field}
1329 @bt_pre_is_opt_field{field}
1331 @sa bt_field_option_set_has_field() —
1332 Sets whether or not an option field has a field.
1333 @sa bt_field_option_borrow_field_const() —
1334 \c const version of this function.
1336 extern bt_field
*bt_field_option_borrow_field(bt_field
*field
);
1340 Borrows the field of the \bt_opt_field \bt_p{field}
1343 See bt_field_option_borrow_field().
1345 extern const bt_field
*
1346 bt_field_option_borrow_field_const(const bt_field
*field
);
1357 Status code for bt_field_variant_select_option_by_index().
1359 typedef enum bt_field_variant_select_option_by_index_status
{
1364 BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1365 } bt_field_variant_select_option_by_index_status
;
1369 Sets the selected option of the \bt_var_field \bt_p{field}
1370 to the option at index \bt_p{index}.
1373 Variant field of which to set the selected option.
1375 Index of the option to set as the selected option of \bt_p{field}.
1377 @retval #BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK
1380 @bt_pre_not_null{field}
1381 @bt_pre_is_var_field{field}
1383 \bt_p{index} is less than the number of options in the
1384 \ref api-tir-fc-var "class" of \bt_p{field} (as
1385 returned by bt_field_class_variant_get_option_count()).
1387 extern bt_field_variant_select_option_by_index_status
1388 bt_field_variant_select_option_by_index(
1389 bt_field
*field
, uint64_t index
);
1393 Borrows the field of the selected option of the \bt_var_field
1397 You must call bt_field_variant_select_option_by_index() before
1398 you call this function.
1401 Variant field from which to borrow the selected option's field.
1405 \em Borrowed reference of the field of the selected option of
1406 \bt_p{field}, or \c NULL if none.
1408 The returned pointer remains valid as long as \bt_p{field} exists.
1411 @bt_pre_not_null{field}
1412 @bt_pre_is_var_field{field}
1414 @sa bt_field_variant_select_option_by_index() —
1415 Sets a variant field's selected option.
1416 @sa bt_field_variant_get_selected_option_index() —
1417 Returns the index of a variant field's selected option.
1418 @sa bt_field_variant_borrow_selected_option_field_const() —
1419 \c const version of this function.
1421 extern bt_field
*bt_field_variant_borrow_selected_option_field(
1426 Borrows the field of the selected option of the \bt_var_field
1427 \bt_p{field} (\c const version).
1429 See bt_field_variant_borrow_selected_option_field().
1431 extern const bt_field
*
1432 bt_field_variant_borrow_selected_option_field_const(
1433 const bt_field
*field
);
1437 Returns the index of the selected option of the \bt_var_field
1441 Variant field of which to get the index of the selected option.
1444 Index of the selected option of \bt_p{field}.
1446 @bt_pre_not_null{field}
1447 @bt_pre_is_var_field{field}
1449 @sa bt_field_variant_borrow_selected_option_field_const() —
1450 Borrows the field of a variant field's selected option.
1452 extern uint64_t bt_field_variant_get_selected_option_index(
1453 const bt_field
*field
);
1457 Borrows the class of the selected option of the \bt_var_field
1460 This function returns
1463 bt_field_class_variant_borrow_option_by_index(
1464 bt_field_variant_get_selected_option_index(field))
1468 Variant field of which to get the selected option's class.
1471 Class of the selected option of \bt_p{field}.
1473 @bt_pre_not_null{field}
1474 @bt_pre_is_var_field{field}
1476 extern const bt_field_class_variant_option
*
1477 bt_field_variant_borrow_selected_option_class_const(
1478 const bt_field
*field
);
1482 Borrows the class of the selected option of the \bt_var_field
1483 (with an unsigned integer selector field) \bt_p{field}.
1485 This function returns
1488 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(
1489 bt_field_variant_get_selected_option_index(field))
1493 Variant field of which to get the selected option's class.
1496 Class of the selected option of \bt_p{field}.
1498 @bt_pre_not_null{field}
1499 @bt_pre_is_var_wuis_field{field}
1501 extern const bt_field_class_variant_with_selector_field_integer_unsigned_option
*
1502 bt_field_variant_with_selector_field_integer_unsigned_borrow_selected_option_class_const(
1503 const bt_field
*field
);
1507 Borrows the class of the selected option of the \bt_var_field
1508 (with a signed integer selector field) \bt_p{field}.
1510 This function returns
1513 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(
1514 bt_field_variant_get_selected_option_index(field))
1518 Variant field of which to get the selected option's class.
1521 Class of the selected option of \bt_p{field}.
1523 @bt_pre_not_null{field}
1524 @bt_pre_is_var_wsis_field{field}
1526 extern const bt_field_class_variant_with_selector_field_integer_signed_option
*
1527 bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const(
1528 const bt_field
*field
);
1538 #endif /* BABELTRACE2_TRACE_IR_FIELD_H */