include: add IWYU pragmas in private header files
[babeltrace.git] / include / babeltrace2 / trace-ir / field.h
1 /*
2 * SPDX-License-Identifier: MIT
3 *
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
5 */
6
7 #ifndef BABELTRACE2_TRACE_IR_FIELD_H
8 #define BABELTRACE2_TRACE_IR_FIELD_H
9
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
11
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
14 #endif
15
16 #include <stdint.h>
17
18 #include <babeltrace2/types.h>
19
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23
24 /*!
25 @defgroup api-tir-field Fields
26 @ingroup api-tir
27
28 @brief
29 Containers of trace data.
30
31 <strong><em>Fields</em></strong> are containers of trace data: they are
32 found in \bt_p_ev and \bt_p_pkt.
33
34 Fields are instances of \bt_p_fc:
35
36 @image html field-class-zoom.png
37
38 Borrow the class of a field with bt_field_borrow_class() and
39 bt_field_borrow_class_const().
40
41 Fields are \ref api-tir "trace IR" data objects.
42
43 There are many types of fields. They can be divided into two main
44 categories:
45
46 <dl>
47 <dt>Scalar</dt>
48 <dd>
49 Fields which contain a simple value.
50
51 The scalar fields are:
52
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"
59 </dd>
60
61 <dt>Container</dt>
62 <dd>
63 Fields which contain other fields.
64
65 The container fields are:
66
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"
71 </dd>
72 </dl>
73
74 @image html fc-to-field.png "Fields (green) are instances of field classes (orange)."
75
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,
82 to set their values.
83
84 The functions to borrow a field from an event or a packet are:
85
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()
94
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.
99
100 The complete field inheritance hierarchy is:
101
102 @image html all-fields.png
103
104 This is the same inheritance hierarchy as the \bt_fc inheritance
105 hierarchy.
106
107 In the illustration above:
108
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.
112
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.
116
117 For example, bt_field_integer_signed_set_value() applies to any
118 \bt_sint_field.
119
120 Fields are \ref api-fund-unique-object "unique objects": they belong
121 to an \bt_ev or to a \bt_pkt.
122
123 Some library functions \ref api-fund-freezing "freeze" fields on
124 success. The documentation of those functions indicate this
125 postcondition.
126
127 All the field types share the same C type, #bt_field.
128
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.
132
133 <h1>\anchor api-tir-field-bool Boolean field</h1>
134
135 A <strong><em>boolean field</em></strong> is a \bt_bool_fc instance.
136
137 A boolean field contains a boolean value (#BT_TRUE or #BT_FALSE).
138
139 Set the value of a boolean field with bt_field_bool_set_value().
140
141 Get the value of a boolean field with bt_field_bool_get_value().
142
143 <h1>\anchor api-tir-field-ba Bit array field</h1>
144
145 A <strong><em>bit array field</em></strong> is a \bt_ba_fc instance.
146
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".
149
150 The bit array field API interprets the array as an unsigned integer
151 value: the least significant bit's index is 0.
152
153 For example, to get whether or not bit&nbsp;3 of a bit array field is
154 set:
155
156 @code
157 uint64_t value = bt_field_bit_array_get_value_as_integer(field);
158
159 if (value & (UINT64_C(1) << UINT64_C(3))) {
160 // Bit 3 is set
161 }
162 @endcode
163
164 Set the bits of a bit array field with
165 bt_field_bit_array_set_value_as_integer().
166
167 Get the bits of a bit array field with
168 bt_field_bit_array_get_value_as_integer().
169
170 <h1>\anchor api-tir-field-int Integer fields</h1>
171
172 <strong><em>Integer fields</em></strong> are \bt_int_fc instances.
173
174 Integer fields contain integral values.
175
176 An integer field is an \em abstract field. The concrete integer fields
177 are:
178
179 <dl>
180 <dt>Unsigned integer field</dt>
181 <dd>
182 An \bt_uint_fc instance.
183
184 An unsigned integer field contains an unsigned integral value
185 (\c uint64_t).
186
187 Set the value of an unsigned integer field with
188 bt_field_integer_unsigned_set_value().
189
190 Get the value of an unsigned integer field with
191 bt_field_integer_unsigned_get_value().
192 </dd>
193
194 <dt>Signed integer field</dt>
195 <dd>
196 A \bt_sint_fc instance.
197
198 A signed integer field contains a signed integral value (\c int64_t).
199
200 Set the value of a signed integer field with
201 bt_field_integer_signed_set_value().
202
203 Get the value of a signed integer field with
204 bt_field_integer_signed_get_value().
205 </dd>
206 </dl>
207
208 <h2>\anchor api-tir-field-enum Enumeration fields</h2>
209
210 <strong><em>Enumeration fields</em></strong> are \bt_enum_fc instances.
211
212 Enumeration fields \em are \bt_p_int_field: they contain integral
213 values.
214
215 An enumeration field is an \em abstract field.
216 The concrete enumeration fields are:
217
218 <dl>
219 <dt>Unsigned enumeration field</dt>
220 <dd>
221 An \bt_uenum_fc instance.
222
223 An unsigned enumeration field contains an unsigned integral value
224 (\c uint64_t).
225
226 Set the value of an unsigned enumeration field with
227 bt_field_integer_unsigned_set_value().
228
229 Get the value of an unsigned enumeration field with
230 bt_field_integer_unsigned_get_value().
231
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().
235 </dd>
236
237 <dt>Signed enumeration field</dt>
238 <dd>
239 A \bt_senum_fc instance.
240
241 A signed enumeration field contains a signed integral value
242 (\c int64_t).
243
244 Set the value of a signed enumeration field with
245 bt_field_integer_signed_set_value().
246
247 Get the value of a signed enumeration field with
248 bt_field_integer_signed_get_value().
249
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().
253 </dd>
254 </dl>
255
256 <h1>\anchor api-tir-field-real Real fields</h1>
257
258 <strong><em>Real fields</em></strong> are \bt_real_fc instances.
259
260 Real fields contain
261 <a href="https://en.wikipedia.org/wiki/Real_number">real</a>
262 values (\c float or \c double types).
263
264 A real field is an \em abstract field. The concrete real fields are:
265
266 <dl>
267 <dt>Single-precision real field</dt>
268 <dd>
269 A single-precision real field class instance.
270
271 A single-precision real field contains a \c float value.
272
273 Set the value of a single-precision real field with
274 bt_field_real_single_precision_set_value().
275
276 Get the value of a single-precision real field with
277 bt_field_real_single_precision_get_value().
278 </dd>
279
280 <dt>Double-precision real field</dt>
281 <dd>
282 A double-precision real field class instance.
283
284 A double-precision real field contains a \c double value.
285
286 Set the value of a double-precision real field with
287 bt_field_real_double_precision_set_value().
288
289 Get the value of a double-precision real field with
290 bt_field_real_double_precision_get_value().
291 </dd>
292 </dl>
293
294 <h1>\anchor api-tir-field-string String field</h1>
295
296 A <strong><em>string field</em></strong> is a \bt_string_fc instance.
297
298 A string field contains an UTF-8 string value.
299
300 Set the value of a string field with
301 bt_field_string_set_value().
302
303 Get the value of a string field with
304 bt_field_string_get_value().
305
306 Get the length of a string field with
307 bt_field_string_get_length().
308
309 Append a string to a string field's current value with
310 bt_field_string_append() and bt_field_string_append_with_length().
311
312 Clear a string field with bt_field_string_clear().
313
314 <h1>\anchor api-tir-field-array Array fields</h1>
315
316 <strong><em>Array fields</em></strong> are \bt_array_fc instances.
317
318 Array fields contain zero or more fields which have the same class.
319
320 An array field is an \em abstract field. The concrete array fields are:
321
322 <dl>
323 <dt>Static array field</dt>
324 <dd>
325 A \bt_sarray_fc instance.
326
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".
329 </dd>
330
331 <dt>Dynamic array field class</dt>
332 <dd>
333 A \bt_darray_fc instance.
334
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.
338
339 Set a dynamic array field's length with
340 bt_field_array_dynamic_set_length() before you borrow any of its
341 fields.
342 </dd>
343 </dl>
344
345 Get an array field's length with bt_field_array_get_length().
346
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().
350
351 <h1>\anchor api-tir-field-struct Structure field</h1>
352
353 A <strong><em>structure field</em></strong> is a \bt_struct_fc instance.
354
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
357 field class member.
358
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().
362
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().
366
367 <h1>\anchor api-tir-field-opt Option field</h1>
368
369 An <strong><em>option field</em></strong> is an \bt_opt_fc instance.
370
371 An option field either does or doesn't contain a field.
372
373 Set whether or not an option field has a field with
374 bt_field_option_set_has_field().
375
376 Borrow the field from an option field with
377 bt_field_option_borrow_field() or
378 bt_field_option_borrow_field_const().
379
380 <h1>\anchor api-tir-field-var Variant field</h1>
381
382 A <strong><em>variant field</em></strong> is a \bt_var_fc instance.
383
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.
387
388 Set the current option of a variant field with
389 bt_field_variant_select_option_by_index().
390
391 Get a variant field's selected option's index with
392 bt_field_variant_get_selected_option_index().
393
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().
397
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(),
401 and
402 bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const().
403 */
404
405 /*! @{ */
406
407 /*!
408 @name Type
409 @{
410
411 @typedef struct bt_field bt_field;
412
413 @brief
414 Field.
415
416 @}
417 */
418
419 /*!
420 @name Type query
421 @{
422 */
423
424 /*!
425 @brief
426 Returns the type enumerator of the \ref api-tir-fc "class" of the
427 field \bt_p{field}.
428
429 This function returns
430
431 @code
432 bt_field_class_get_type(bt_field_borrow_class(field))
433 @endcode
434
435 @param[in] field
436 Field of which to get the class's type enumerator
437
438 @returns
439 Type enumerator of the class of \bt_p{field}.
440
441 @bt_pre_not_null{field}
442
443 @sa bt_field_class_get_type() &mdash;
444 Returns the type enumerator of a \bt_fc.
445 */
446 extern bt_field_class_type bt_field_get_class_type(
447 const bt_field *field);
448
449 /*! @} */
450
451 /*!
452 @name Class access
453 @{
454 */
455
456 /*!
457 @brief
458 Borrows the \ref api-tir-fc "class" of the field \bt_p{field}.
459
460 @param[in] field
461 Field of which to borrow the class.
462
463 @returns
464 \em Borrowed reference of the class of \bt_p{field}.
465
466 @bt_pre_not_null{field}
467
468 @sa bt_field_borrow_class_const() &mdash;
469 \c const version of this function.
470 */
471 extern bt_field_class *bt_field_borrow_class(bt_field *field);
472
473 /*!
474 @brief
475 Borrows the \ref api-tir-fc "class" of the field \bt_p{field}
476 (\c const version).
477
478 See bt_field_borrow_class().
479 */
480 extern const bt_field_class *bt_field_borrow_class_const(
481 const bt_field *field);
482
483 /*! @} */
484
485 /*!
486 @name Boolean field
487 @{
488 */
489
490 /*!
491 @brief
492 Sets the value of the \bt_bool_field \bt_p{field} to
493 \bt_p{value}.
494
495 @param[in] field
496 Boolean field of which to set the value to \bt_p{value}.
497 @param[in] value
498 New value of \bt_p{field}.
499
500 @bt_pre_not_null{field}
501 @bt_pre_is_bool_field{field}
502 @bt_pre_hot{field}
503
504 @sa bt_field_bool_get_value() &mdash;
505 Returns the value of a boolean field.
506 */
507 extern void bt_field_bool_set_value(bt_field *field, bt_bool value);
508
509 /*!
510 @brief
511 Returns the value of the \bt_bool_field \bt_p{field}.
512
513 @param[in] field
514 Boolean field of which to get the value.
515
516 @returns
517 Value of \bt_p{field}.
518
519 @bt_pre_not_null{field}
520 @bt_pre_is_bool_field{field}
521
522 @sa bt_field_bool_set_value() &mdash;
523 Sets the value of a boolean field.
524 */
525 extern bt_bool bt_field_bool_get_value(const bt_field *field);
526
527 /*! @} */
528
529 /*!
530 @name Bit array field
531 @{
532 */
533
534 /*!
535 @brief
536 Sets the bits of the \bt_ba_field \bt_p{field} to the bits of
537 \bt_p{bits}.
538
539 The least significant bit's index is 0.
540
541 See \bt_c_ba_field to learn more.
542
543 @param[in] field
544 Bit array field of which to set the bits to \bt_p{bits}.
545 @param[in] bits
546 New bits of \bt_p{field}.
547
548 @bt_pre_not_null{field}
549 @bt_pre_is_ba_field{field}
550 @bt_pre_hot{field}
551
552 @sa bt_field_bit_array_get_value_as_integer() &mdash;
553 Returns the bits of a bit array field as an integer.
554 */
555 extern void bt_field_bit_array_set_value_as_integer(bt_field *field,
556 uint64_t bits);
557
558 /*!
559 @brief
560 Returns the bits of the \bt_ba_field \bt_p{field} as an
561 unsigned integer.
562
563 The least significant bit's index is 0.
564
565 See \bt_c_ba_field to learn more.
566
567 @param[in] field
568 Bit array field of which to get the bits.
569
570 @returns
571 Bits of \bt_p{field} as an unsigned integer.
572
573 @bt_pre_not_null{field}
574 @bt_pre_is_ba_field{field}
575
576 @sa bt_field_bit_array_set_value_as_integer() &mdash;
577 Sets the bits of a bit array field from an integer.
578 */
579 extern uint64_t bt_field_bit_array_get_value_as_integer(
580 const bt_field *field);
581
582 /*! @} */
583
584 /*!
585 @name Integer field
586 @{
587 */
588
589 /*!
590 @brief
591 Sets the value of the \bt_uint_field \bt_p{field} to
592 \bt_p{value}.
593
594 @param[in] field
595 Unsigned integer field of which to set the value to \bt_p{value}.
596 @param[in] value
597 New value of \bt_p{field}.
598
599 @bt_pre_not_null{field}
600 @bt_pre_is_uint_field{field}
601 @bt_pre_hot{field}
602 @pre
603 \bt_p{value} is within the
604 \ref api-tir-fc-int-prop-size "field value range" of the
605 class of \bt_p{field}.
606
607 @sa bt_field_integer_unsigned_get_value() &mdash;
608 Returns the value of an unsigned integer field.
609 */
610 extern void bt_field_integer_unsigned_set_value(bt_field *field,
611 uint64_t value);
612
613 /*!
614 @brief
615 Returns the value of the \bt_uint_field \bt_p{field}.
616
617 @param[in] field
618 Unsigned integer field of which to get the value.
619
620 @returns
621 Value of \bt_p{field}.
622
623 @bt_pre_not_null{field}
624 @bt_pre_is_uint_field{field}
625
626 @sa bt_field_integer_unsigned_set_value() &mdash;
627 Sets the value of an unsigned integer field.
628 */
629 extern uint64_t bt_field_integer_unsigned_get_value(
630 const bt_field *field);
631
632 /*!
633 @brief
634 Sets the value of the \bt_sint_field \bt_p{field} to
635 \bt_p{value}.
636
637 @param[in] field
638 Signed integer field of which to set the value to \bt_p{value}.
639 @param[in] value
640 New value of \bt_p{field}.
641
642 @bt_pre_not_null{field}
643 @bt_pre_is_sint_field{field}
644 @bt_pre_hot{field}
645 @pre
646 \bt_p{value} is within the
647 \ref api-tir-fc-int-prop-size "field value range" of the
648 class of \bt_p{field}.
649
650 @sa bt_field_integer_signed_get_value() &mdash;
651 Returns the value of an signed integer field.
652 */
653 extern void bt_field_integer_signed_set_value(bt_field *field,
654 int64_t value);
655
656 /*!
657 @brief
658 Returns the value of the \bt_sint_field \bt_p{field}.
659
660 @param[in] field
661 Signed integer field of which to get the value.
662
663 @returns
664 Value of \bt_p{field}.
665
666 @bt_pre_not_null{field}
667 @bt_pre_is_sint_field{field}
668
669 @sa bt_field_integer_signed_set_value() &mdash;
670 Sets the value of an signed integer field.
671 */
672 extern int64_t bt_field_integer_signed_get_value(const bt_field *field);
673
674 /*! @} */
675
676 /*!
677 @name Enumeration field
678 @{
679 */
680
681 /*!
682 @brief
683 Status codes for
684 bt_field_enumeration_unsigned_get_mapping_labels() and
685 bt_field_enumeration_signed_get_mapping_labels().
686 */
687 typedef enum bt_field_enumeration_get_mapping_labels_status {
688 /*!
689 @brief
690 Success.
691 */
692 BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK = __BT_FUNC_STATUS_OK,
693
694 /*!
695 @brief
696 Out of memory.
697 */
698 BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
699 } bt_field_enumeration_get_mapping_labels_status;
700
701 /*!
702 @brief
703 Returns an array of all the labels of the mappings of the
704 \ref api-tir-fc-enum "class" of the \bt_uenum_field \bt_p{field}
705 of which the \bt_p_uint_rg contain the integral value
706 of \bt_p{field}.
707
708 This function returns
709
710 @code
711 (bt_field_enumeration_get_mapping_labels_status)
712 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value(
713 bt_field_borrow_class_const(field),
714 bt_field_integer_unsigned_get_value(field),
715 labels, count)
716 @endcode
717
718 @param[in] field
719 Unsigned enumeration field having the class from which to get the
720 labels of the mappings of which the ranges contain its
721 integral value.
722 @param[out] labels
723 See
724 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value().
725 @param[out] count
726 See
727 bt_field_class_enumeration_unsigned_get_mapping_labels_for_value().
728
729 @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK
730 Success.
731 @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR
732 Out of memory.
733
734 @bt_pre_not_null{field}
735 @bt_pre_is_uenum_field{field}
736 @bt_pre_not_null{labels}
737 @bt_pre_not_null{count}
738 */
739 extern bt_field_enumeration_get_mapping_labels_status
740 bt_field_enumeration_unsigned_get_mapping_labels(const bt_field *field,
741 bt_field_class_enumeration_mapping_label_array *labels,
742 uint64_t *count);
743
744 /*!
745 @brief
746 Returns an array of all the labels of the mappings of the
747 \ref api-tir-fc-enum "class" of the \bt_senum_field \bt_p{field}
748 of which the \bt_p_sint_rg contain the integral value
749 of \bt_p{field}.
750
751 This function returns
752
753 @code
754 (bt_field_enumeration_get_mapping_labels_status)
755 bt_field_class_enumeration_signed_get_mapping_labels_for_value(
756 bt_field_borrow_class_const(field),
757 bt_field_integer_signed_get_value(field),
758 labels, count)
759 @endcode
760
761 @param[in] field
762 Signed enumeration field having the class from which to get the
763 labels of the mappings of which the ranges contain its
764 integral value.
765 @param[out] labels
766 See
767 bt_field_class_enumeration_signed_get_mapping_labels_for_value().
768 @param[out] count
769 See
770 bt_field_class_enumeration_signed_get_mapping_labels_for_value().
771
772 @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK
773 Success.
774 @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR
775 Out of memory.
776
777 @bt_pre_not_null{field}
778 @bt_pre_is_senum_field{field}
779 @bt_pre_not_null{labels}
780 @bt_pre_not_null{count}
781 */
782 extern bt_field_enumeration_get_mapping_labels_status
783 bt_field_enumeration_signed_get_mapping_labels(const bt_field *field,
784 bt_field_class_enumeration_mapping_label_array *labels,
785 uint64_t *count);
786
787 /*! @} */
788
789 /*!
790 @name Real field
791 @{
792 */
793
794 /*!
795 @brief
796 Sets the value of the \bt_sreal_field \bt_p{field} to
797 \bt_p{value}.
798
799 @param[in] field
800 Single-precision real field of which to set the value to
801 \bt_p{value}.
802 @param[in] value
803 New value of \bt_p{field}.
804
805 @bt_pre_not_null{field}
806 @bt_pre_is_sreal_field{field}
807 @bt_pre_hot{field}
808
809 @sa bt_field_real_single_precision_get_value() &mdash;
810 Returns the value of a single-precision real field.
811 */
812 extern void bt_field_real_single_precision_set_value(bt_field *field,
813 float value);
814
815 /*!
816 @brief
817 Returns the value of the \bt_sreal_field \bt_p{field}.
818
819 @param[in] field
820 Single-precision real field of which to get the value.
821
822 @returns
823 Value of \bt_p{field}.
824
825 @bt_pre_not_null{field}
826 @bt_pre_is_sreal_field{field}
827
828 @sa bt_field_real_single_precision_set_value() &mdash;
829 Sets the value of a single-precision real field.
830 */
831 extern float bt_field_real_single_precision_get_value(const bt_field *field);
832
833 /*!
834 @brief
835 Sets the value of the \bt_dreal_field \bt_p{field} to
836 \bt_p{value}.
837
838 @param[in] field
839 Double-precision real field of which to set the value to
840 \bt_p{value}.
841 @param[in] value
842 New value of \bt_p{field}.
843
844 @bt_pre_not_null{field}
845 @bt_pre_is_dreal_field{field}
846 @bt_pre_hot{field}
847
848 @sa bt_field_real_double_precision_get_value() &mdash;
849 Returns the value of a double-precision real field.
850 */
851 extern void bt_field_real_double_precision_set_value(bt_field *field,
852 double value);
853
854 /*!
855 @brief
856 Returns the value of the \bt_dreal_field \bt_p{field}.
857
858 @param[in] field
859 Double-precision real field of which to get the value.
860
861 @returns
862 Value of \bt_p{field}.
863
864 @bt_pre_not_null{field}
865 @bt_pre_is_dreal_field{field}
866
867 @sa bt_field_real_double_precision_set_value() &mdash;
868 Sets the value of a double-precision real field.
869 */
870 extern double bt_field_real_double_precision_get_value(const bt_field *field);
871
872 /*! @} */
873
874 /*!
875 @name String field
876 @{
877 */
878
879 /*!
880 @brief
881 Status codes for bt_field_string_set_value().
882 */
883 typedef enum bt_field_string_set_value_status {
884 /*!
885 @brief
886 Success.
887 */
888 BT_FIELD_STRING_SET_VALUE_STATUS_OK = __BT_FUNC_STATUS_OK,
889
890 /*!
891 @brief
892 Out of memory.
893 */
894 BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
895 } bt_field_string_set_value_status;
896
897 /*!
898 @brief
899 Sets the value of the \bt_string_field \bt_p{field} to
900 a copy of \bt_p{value}.
901
902 @param[in] field
903 String field of which to set the value to \bt_p{value}.
904 @param[in] value
905 New value of \bt_p{field} (copied).
906
907 @retval #BT_FIELD_STRING_SET_VALUE_STATUS_OK
908 Success.
909 @retval #BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR
910 Out of memory.
911
912 @bt_pre_not_null{field}
913 @bt_pre_is_string_field{field}
914 @bt_pre_hot{field}
915 @bt_pre_not_null{value}
916
917 @sa bt_field_string_get_value() &mdash;
918 Returns the value of a string field.
919 @sa bt_field_string_append() &mdash;
920 Appends a string to a string field.
921 @sa bt_field_string_clear() &mdash;
922 Clears a string field.
923 */
924 extern bt_field_string_set_value_status bt_field_string_set_value(
925 bt_field *field, const char *value);
926
927 /*!
928 @brief
929 Returns the length of the \bt_string_field \bt_p{field}.
930
931 @param[in] field
932 String field of which to get the length.
933
934 @returns
935 Length of \bt_p{field}.
936
937 @bt_pre_not_null{field}
938 @bt_pre_is_string_field{field}
939 */
940 extern uint64_t bt_field_string_get_length(const bt_field *field);
941
942 /*!
943 @brief
944 Returns the value of the \bt_string_field \bt_p{field}.
945
946 @param[in] field
947 String field of which to get the value.
948
949 @returns
950 @parblock
951 Value of \bt_p{field}.
952
953 The returned pointer remains valid until \bt_p{field} is modified.
954 @endparblock
955
956 @bt_pre_not_null{field}
957 @bt_pre_is_string_field{field}
958
959 @sa bt_field_string_set_value() &mdash;
960 Sets the value of a string field.
961 */
962 extern const char *bt_field_string_get_value(const bt_field *field);
963
964 /*!
965 @brief
966 Status codes for bt_field_string_append() and
967 bt_field_string_append_with_length().
968 */
969 typedef enum bt_field_string_append_status {
970 /*!
971 @brief
972 Success.
973 */
974 BT_FIELD_STRING_APPEND_STATUS_OK = __BT_FUNC_STATUS_OK,
975
976 /*!
977 @brief
978 Out of memory.
979 */
980 BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
981 } bt_field_string_append_status;
982
983 /*!
984 @brief
985 Appends a copy of the string \bt_p{value} to the current value of
986 the \bt_string_field \bt_p{field}.
987
988 @attention
989 If you didn't set the value of \bt_p{field} yet, you must call
990 bt_field_string_clear() before you call this function.
991
992 @param[in] field
993 String field to which to append the string \bt_p{value}.
994 @param[in] value
995 String to append to \bt_p{field} (copied).
996
997 @retval #BT_FIELD_STRING_APPEND_STATUS_OK
998 Success.
999 @retval #BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR
1000 Out of memory.
1001
1002 @bt_pre_not_null{field}
1003 @bt_pre_is_string_field{field}
1004 @bt_pre_hot{field}
1005 @bt_pre_not_null{value}
1006
1007 @sa bt_field_string_append_with_length() &mdash;
1008 Appends a string with a given length to a string field.
1009 @sa bt_field_string_set_value() &mdash;
1010 Sets the value of a string field.
1011 */
1012 extern bt_field_string_append_status bt_field_string_append(
1013 bt_field *field, const char *value);
1014
1015 /*!
1016 @brief
1017 Appends a copy of the first \bt_p{length} bytes of the string
1018 \bt_p{value} to the current value of the \bt_string_field
1019 \bt_p{field}.
1020
1021 @attention
1022 If you didn't set the value of \bt_p{field} yet, you must call
1023 bt_field_string_clear() before you call this function.
1024
1025 @param[in] field
1026 String field to which to append the first \bt_p{length} bytes of
1027 the string \bt_p{value}.
1028 @param[in] value
1029 String of which to append the first \bt_p{length} bytes to
1030 \bt_p{field} (copied).
1031 @param[in] length
1032 Number of bytes of \bt_p{value} to append to \bt_p{field}.
1033
1034 @retval #BT_FIELD_STRING_APPEND_STATUS_OK
1035 Success.
1036 @retval #BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR
1037 Out of memory.
1038
1039 @bt_pre_not_null{field}
1040 @bt_pre_is_string_field{field}
1041 @bt_pre_hot{field}
1042 @bt_pre_not_null{value}
1043
1044 @sa bt_field_string_append() &mdash;
1045 Appends a string to a string field.
1046 @sa bt_field_string_set_value() &mdash;
1047 Sets the value of a string field.
1048 */
1049 extern bt_field_string_append_status bt_field_string_append_with_length(
1050 bt_field *field, const char *value, uint64_t length);
1051
1052 /*!
1053 @brief
1054 Clears the \bt_string_field \bt_p{field}, making its value an empty
1055 string.
1056
1057 @param[in] field
1058 String field to clear.
1059
1060 @bt_pre_not_null{field}
1061 @bt_pre_is_string_field{field}
1062 @bt_pre_hot{field}
1063
1064 @sa bt_field_string_set_value() &mdash;
1065 Sets the value of a string field.
1066 */
1067 extern void bt_field_string_clear(bt_field *field);
1068
1069 /*! @} */
1070
1071 /*!
1072 @name Array field
1073 @{
1074 */
1075
1076 /*!
1077 @brief
1078 Returns the length of the \bt_array_field \bt_p{field}.
1079
1080 @param[in] field
1081 Array field of which to get the length.
1082
1083 @returns
1084 Length of \bt_p{field}.
1085
1086 @bt_pre_not_null{field}
1087 @bt_pre_is_array_field{field}
1088 */
1089 extern uint64_t bt_field_array_get_length(const bt_field *field);
1090
1091 /*!
1092 @brief
1093 Borrows the field at index \bt_p{index} from the \bt_array_field
1094 \bt_p{field}.
1095
1096 @attention
1097 If \bt_p{field} is a dynamic array field, it must have a length
1098 (call bt_field_array_dynamic_set_length()) before you call this
1099 function.
1100
1101 @param[in] field
1102 Array field from which to borrow the field at index \bt_p{index}.
1103 @param[in] index
1104 Index of the field to borrow from \bt_p{field}.
1105
1106 @returns
1107 @parblock
1108 \em Borrowed reference of the field of \bt_p{field} at index
1109 \bt_p{index}.
1110
1111 The returned pointer remains valid as long as \bt_p{field} exists.
1112 @endparblock
1113
1114 @bt_pre_not_null{field}
1115 @bt_pre_is_array_field{field}
1116 @pre
1117 \bt_p{index} is less than the length of \bt_p{field} (as returned by
1118 bt_field_array_get_length()).
1119
1120 @sa bt_field_array_borrow_element_field_by_index_const() &mdash;
1121 \c const version of this function.
1122 */
1123 extern bt_field *bt_field_array_borrow_element_field_by_index(
1124 bt_field *field, uint64_t index);
1125
1126 /*!
1127 @brief
1128 Borrows the field at index \bt_p{index} from the \bt_array_field
1129 \bt_p{field} (\c const version).
1130
1131 See bt_field_array_borrow_element_field_by_index().
1132 */
1133 extern const bt_field *
1134 bt_field_array_borrow_element_field_by_index_const(
1135 const bt_field *field, uint64_t index);
1136
1137 /*!
1138 @brief
1139 Status codes for bt_field_array_dynamic_set_length().
1140 */
1141 typedef enum bt_field_array_dynamic_set_length_status {
1142 /*!
1143 @brief
1144 Success.
1145 */
1146 BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_OK = __BT_FUNC_STATUS_OK,
1147
1148 /*!
1149 @brief
1150 Out of memory.
1151 */
1152 BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
1153 } bt_field_array_dynamic_set_length_status;
1154
1155 /*!
1156 @brief
1157 Sets the length of the \bt_darray_field \bt_p{field}.
1158
1159 @param[in] field
1160 Dynamic array field of which to set the length.
1161 @param[in] length
1162 New length of \bt_p{field}.
1163
1164 @retval #BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_OK
1165 Success.
1166 @retval #BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR
1167 Out of memory.
1168
1169 @bt_pre_not_null{field}
1170 @bt_pre_is_darray_field{field}
1171 @bt_pre_hot{field}
1172 */
1173 extern bt_field_array_dynamic_set_length_status
1174 bt_field_array_dynamic_set_length(bt_field *field, uint64_t length);
1175
1176 /*! @} */
1177
1178 /*!
1179 @name Structure field
1180 @{
1181 */
1182
1183 /*!
1184 @brief
1185 Borrows the field of the member at index \bt_p{index} from the
1186 \bt_struct_field \bt_p{field}.
1187
1188 @param[in] field
1189 Structure field from which to borrow the field of the member at
1190 index \bt_p{index}.
1191 @param[in] index
1192 Index of the member containing the field to borrow from
1193 \bt_p{field}.
1194
1195 @returns
1196 @parblock
1197 \em Borrowed reference of the field of the member of \bt_p{field} at
1198 index \bt_p{index}.
1199
1200 The returned pointer remains valid as long as \bt_p{field} exists.
1201 @endparblock
1202
1203 @bt_pre_not_null{field}
1204 @bt_pre_is_struct_field{field}
1205 @pre
1206 \bt_p{index} is less than the number of members in the
1207 \ref api-tir-fc-struct "class" of \bt_p{field} (as
1208 returned by bt_field_class_structure_get_member_count()).
1209
1210 @sa bt_field_structure_borrow_member_field_by_index_const() &mdash;
1211 \c const version of this function.
1212 */
1213 extern bt_field *bt_field_structure_borrow_member_field_by_index(
1214 bt_field *field, uint64_t index);
1215
1216 /*!
1217 @brief
1218 Borrows the field of the member at index \bt_p{index} from the
1219 \bt_struct_field \bt_p{field} (\c const version).
1220
1221 See bt_field_structure_borrow_member_field_by_index().
1222 */
1223 extern const bt_field *
1224 bt_field_structure_borrow_member_field_by_index_const(
1225 const bt_field *field, uint64_t index);
1226
1227 /*!
1228 @brief
1229 Borrows the field of the member having the name \bt_p{name} from the
1230 \bt_struct_field \bt_p{field}.
1231
1232 If there's no member having the name \bt_p{name} in the
1233 \ref api-tir-fc-struct "class" of \bt_p{field}, this function
1234 returns \c NULL.
1235
1236 @param[in] field
1237 Structure field from which to borrow the field of the member having
1238 the name \bt_p{name}.
1239 @param[in] name
1240 Name of the member containing the field to borrow from \bt_p{field}.
1241
1242 @returns
1243 @parblock
1244 \em Borrowed reference of the field of the member of \bt_p{field}
1245 having the name \bt_p{name}, or \c NULL if none.
1246
1247 The returned pointer remains valid as long as \bt_p{field} exists.
1248 @endparblock
1249
1250 @bt_pre_not_null{field}
1251 @bt_pre_is_struct_field{field}
1252 @bt_pre_not_null{name}
1253
1254 @sa bt_field_structure_borrow_member_field_by_name_const() &mdash;
1255 \c const version of this function.
1256 */
1257 extern bt_field *bt_field_structure_borrow_member_field_by_name(
1258 bt_field *field, const char *name);
1259
1260 /*!
1261 @brief
1262 Borrows the field of the member having the name \bt_p{name} from the
1263 \bt_struct_field \bt_p{field} (\c const version).
1264
1265 See bt_field_structure_borrow_member_field_by_name().
1266 */
1267 extern const bt_field *
1268 bt_field_structure_borrow_member_field_by_name_const(
1269 const bt_field *field, const char *name);
1270
1271 /*! @} */
1272
1273 /*!
1274 @name Option field
1275 @{
1276 */
1277
1278 /*!
1279 @brief
1280 Sets whether or not the \bt_opt_field \bt_p{field}
1281 has a field.
1282
1283 @param[in] field
1284 Option field of which to set whether or not it has a field.
1285 @param[in] has_field
1286 #BT_TRUE to make \bt_p{field} have a field.
1287
1288 @bt_pre_not_null{field}
1289 @bt_pre_is_opt_field{field}
1290 */
1291 extern void bt_field_option_set_has_field(bt_field *field, bt_bool has_field);
1292
1293 /*!
1294 @brief
1295 Borrows the field of the \bt_opt_field \bt_p{field}.
1296
1297 @attention
1298 You must call bt_field_option_set_has_field() before you call
1299 this function.
1300
1301 If \bt_p{field} has no field, this function returns \c NULL.
1302
1303 @param[in] field
1304 Option field from which to borrow the field.
1305
1306 @returns
1307 @parblock
1308 \em Borrowed reference of the field of \bt_p{field},
1309 or \c NULL if none.
1310
1311 The returned pointer remains valid as long as \bt_p{field} exists.
1312 @endparblock
1313
1314 @bt_pre_not_null{field}
1315 @bt_pre_is_opt_field{field}
1316
1317 @sa bt_field_option_set_has_field() &mdash;
1318 Sets whether or not an option field has a field.
1319 @sa bt_field_option_borrow_field_const() &mdash;
1320 \c const version of this function.
1321 */
1322 extern bt_field *bt_field_option_borrow_field(bt_field *field);
1323
1324 /*!
1325 @brief
1326 Borrows the field of the \bt_opt_field \bt_p{field}
1327 (\c const version).
1328
1329 See bt_field_option_borrow_field().
1330 */
1331 extern const bt_field *
1332 bt_field_option_borrow_field_const(const bt_field *field);
1333
1334 /*! @} */
1335
1336 /*!
1337 @name Variant field
1338 @{
1339 */
1340
1341 /*!
1342 @brief
1343 Status code for bt_field_variant_select_option_by_index().
1344 */
1345 typedef enum bt_field_variant_select_option_by_index_status {
1346 /*!
1347 @brief
1348 Success.
1349 */
1350 BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK = __BT_FUNC_STATUS_OK,
1351 } bt_field_variant_select_option_by_index_status;
1352
1353 /*!
1354 @brief
1355 Sets the selected option of the \bt_var_field \bt_p{field}
1356 to the option at index \bt_p{index}.
1357
1358 @param[in] field
1359 Variant field of which to set the selected option.
1360 @param[in] index
1361 Index of the option to set as the selected option of \bt_p{field}.
1362
1363 @retval #BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK
1364 Success.
1365
1366 @bt_pre_not_null{field}
1367 @bt_pre_is_var_field{field}
1368 @pre
1369 \bt_p{index} is less than the number of options in the
1370 \ref api-tir-fc-var "class" of \bt_p{field} (as
1371 returned by bt_field_class_variant_get_option_count()).
1372 */
1373 extern bt_field_variant_select_option_by_index_status
1374 bt_field_variant_select_option_by_index(
1375 bt_field *field, uint64_t index);
1376
1377 /*!
1378 @brief
1379 Borrows the field of the selected option of the \bt_var_field
1380 \bt_p{field}.
1381
1382 @attention
1383 You must call bt_field_variant_select_option_by_index() before
1384 you call this function.
1385
1386 @param[in] field
1387 Variant field from which to borrow the selected option's field.
1388
1389 @returns
1390 @parblock
1391 \em Borrowed reference of the field of the selected option of
1392 \bt_p{field}, or \c NULL if none.
1393
1394 The returned pointer remains valid as long as \bt_p{field} exists.
1395 @endparblock
1396
1397 @bt_pre_not_null{field}
1398 @bt_pre_is_var_field{field}
1399
1400 @sa bt_field_variant_select_option_by_index() &mdash;
1401 Sets a variant field's selected option.
1402 @sa bt_field_variant_get_selected_option_index() &mdash;
1403 Returns the index of a variant field's selected option.
1404 @sa bt_field_variant_borrow_selected_option_field_const() &mdash;
1405 \c const version of this function.
1406 */
1407 extern bt_field *bt_field_variant_borrow_selected_option_field(
1408 bt_field *field);
1409
1410 /*!
1411 @brief
1412 Borrows the field of the selected option of the \bt_var_field
1413 \bt_p{field} (\c const version).
1414
1415 See bt_field_variant_borrow_selected_option_field().
1416 */
1417 extern const bt_field *
1418 bt_field_variant_borrow_selected_option_field_const(
1419 const bt_field *field);
1420
1421 /*!
1422 @brief
1423 Returns the index of the selected option of the \bt_var_field
1424 \bt_p{field}.
1425
1426 @param[in] field
1427 Variant field of which to get the index of the selected option.
1428
1429 @returns
1430 Index of the selected option of \bt_p{field}.
1431
1432 @bt_pre_not_null{field}
1433 @bt_pre_is_var_field{field}
1434
1435 @sa bt_field_variant_borrow_selected_option_field_const() &mdash;
1436 Borrows the field of a variant field's selected option.
1437 */
1438 extern uint64_t bt_field_variant_get_selected_option_index(
1439 const bt_field *field);
1440
1441 /*!
1442 @brief
1443 Borrows the class of the selected option of the \bt_var_field
1444 \bt_p{field}.
1445
1446 This function returns
1447
1448 @code
1449 bt_field_class_variant_borrow_option_by_index(
1450 bt_field_variant_get_selected_option_index(field))
1451 @endcode
1452
1453 @param[in] field
1454 Variant field of which to get the selected option's class.
1455
1456 @returns
1457 Class of the selected option of \bt_p{field}.
1458
1459 @bt_pre_not_null{field}
1460 @bt_pre_is_var_field{field}
1461 */
1462 extern const bt_field_class_variant_option *
1463 bt_field_variant_borrow_selected_option_class_const(
1464 const bt_field *field);
1465
1466 /*!
1467 @brief
1468 Borrows the class of the selected option of the \bt_var_field
1469 (with an unsigned integer selector field) \bt_p{field}.
1470
1471 This function returns
1472
1473 @code
1474 bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(
1475 bt_field_variant_get_selected_option_index(field))
1476 @endcode
1477
1478 @param[in] field
1479 Variant field of which to get the selected option's class.
1480
1481 @returns
1482 Class of the selected option of \bt_p{field}.
1483
1484 @bt_pre_not_null{field}
1485 @bt_pre_is_var_wuis_field{field}
1486 */
1487 extern const bt_field_class_variant_with_selector_field_integer_unsigned_option *
1488 bt_field_variant_with_selector_field_integer_unsigned_borrow_selected_option_class_const(
1489 const bt_field *field);
1490
1491 /*!
1492 @brief
1493 Borrows the class of the selected option of the \bt_var_field
1494 (with a signed integer selector field) \bt_p{field}.
1495
1496 This function returns
1497
1498 @code
1499 bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(
1500 bt_field_variant_get_selected_option_index(field))
1501 @endcode
1502
1503 @param[in] field
1504 Variant field of which to get the selected option's class.
1505
1506 @returns
1507 Class of the selected option of \bt_p{field}.
1508
1509 @bt_pre_not_null{field}
1510 @bt_pre_is_var_wsis_field{field}
1511 */
1512 extern const bt_field_class_variant_with_selector_field_integer_signed_option *
1513 bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const(
1514 const bt_field *field);
1515
1516 /*! @} */
1517
1518 /*! @} */
1519
1520 #ifdef __cplusplus
1521 }
1522 #endif
1523
1524 #endif /* BABELTRACE2_TRACE_IR_FIELD_H */
This page took 0.080858 seconds and 4 git commands to generate.