1 #ifndef BABELTRACE_CTF_IR_FIELDS_H
2 #define BABELTRACE_CTF_IR_FIELDS_H
5 * Babeltrace - CTF IR: Event Fields
7 * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
9 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
11 * Permission is hereby granted, free of charge, to any person obtaining a copy
12 * of this software and associated documentation files (the "Software"), to deal
13 * in the Software without restriction, including without limitation the rights
14 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15 * copies of the Software, and to permit persons to whom the Software is
16 * furnished to do so, subject to the following conditions:
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
29 * The Common Trace Format (CTF) Specification is available at
30 * http://www.efficios.com/ctf
37 #include <babeltrace/types.h>
46 @defgroup ctfirfields CTF IR fields
51 #include <babeltrace/ctf-ir/fields.h>
54 A CTF IR <strong><em>field</em></strong> is an object which holds a
55 concrete value, and which is described by a @ft.
57 In the CTF IR hierarchy, you can set the root fields of two objects:
60 - Trace packet header field: bt_packet_set_header().
61 - Stream packet context field: bt_packet_set_context().
63 - Stream event header field: bt_event_set_header().
64 - Stream event context field: bt_event_set_stream_event_context().
65 - Event context field: bt_event_set_event_context().
66 - Event payload field: bt_event_set_payload_field().
68 There are two categories of fields:
70 - <strong>Basic fields</strong>:
71 - @intfield: contains an integral value.
72 - @floatfield: contains a floating point number value.
73 - @enumfield: contains an integer field which contains an integral
75 - @stringfield: contains a string value.
76 - <strong>Compound fields</strong>:
77 - @structfield: contains an ordered list of named fields
78 (possibly with different @fts).
79 - @arrayfield: contains an ordered list of fields which share
81 - @seqfield: contains an ordered list of fields which share
83 - @varfield: contains a single, current field.
85 You can create a field object from a @ft object with
86 bt_field_create(). The enumeration and compound fields create their
87 contained fields with the following getters if such fields do not exist
90 - bt_field_enumeration_get_container()
91 - bt_field_structure_get_field_by_name()
92 - bt_field_array_get_field()
93 - bt_field_sequence_get_field()
94 - bt_field_variant_get_field()
96 If you already have a field object, you can also assign it to a specific
97 name within a @structfield with
98 bt_field_structure_set_field_by_name().
100 You can get a reference to the @ft which was used to create a field with
101 bt_field_get_type(). You can get the
102 \link #bt_field_type_id type ID\endlink of this field type directly with
103 bt_field_get_type_id().
105 You can get a deep copy of a field with bt_field_copy(). The field
106 copy, and its contained field copies if it's the case, have the same
107 field type as the originals.
109 As with any Babeltrace object, CTF IR field objects have
110 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
111 counts</a>. See \ref refs to learn more about the reference counting
112 management of Babeltrace objects.
114 The functions which freeze CTF IR \link ctfirpacket packet\endlink and
115 \link ctfirevent event\endlink objects also freeze their root field
116 objects. You cannot modify a frozen field object: it is considered
117 immutable, except for \link refs reference counting\endlink.
122 @brief CTF IR fields type and functions.
125 @addtogroup ctfirfields
131 @brief A CTF IR field.
135 struct bt_event_class
;
137 struct bt_field_type
;
138 struct bt_field_type_enumeration_mapping_iterator
;
141 @name Creation and parent field type access functions
146 @brief Creates an uninitialized @field described by the @ft
149 On success, \p field_type becomes the parent of the created field
152 On success, this function creates an \em uninitialized field: it has
153 no value. You need to set the value of the created field with one of the
154 its specific setters.
156 @param[in] field_type Field type which describes the field to create.
157 @returns Created field object, or \c NULL on error.
159 @prenotnull{field_type}
160 @postsuccessrefcountret1
161 @postsuccessfrozen{field_type}
163 extern struct bt_field
*bt_field_create(struct bt_field_type
*field_type
);
166 @brief Returns the parent @ft of the @field \p field.
168 This function returns a reference to the field type which was used to
169 create the field object in the first place with bt_field_create().
171 @param[in] field Field of which to get the parent field type.
172 @returns Parent field type of \p event,
176 @postrefcountsame{field}
177 @postsuccessrefcountretinc
179 extern struct bt_field_type
*bt_field_get_type(struct bt_field
*field
);
184 @name Type information
189 @brief Returns the type ID of the @ft of the @field \p field.
191 @param[in] field Field of which to get the type ID of its
193 @returns Type ID of the parent field type of \p field,
194 or #BT_FIELD_TYPE_ID_UNKNOWN on error.
197 @postrefcountsame{field}
199 @sa #bt_field_type_id: CTF IR field type ID.
200 @sa bt_field_is_integer(): Returns whether or not a given field is a
202 @sa bt_field_is_floating_point(): Returns whether or not a given
203 field is a @floatfield.
204 @sa bt_field_is_enumeration(): Returns whether or not a given field
206 @sa bt_field_is_string(): Returns whether or not a given field is a
208 @sa bt_field_is_structure(): Returns whether or not a given field is
210 @sa bt_field_is_array(): Returns whether or not a given field is a
212 @sa bt_field_is_sequence(): Returns whether or not a given field is
214 @sa bt_field_is_variant(): Returns whether or not a given field is a
217 extern enum bt_field_type_id
bt_field_get_type_id(struct bt_field
*field
);
220 @brief Returns whether or not the @field \p field is a @intfield.
222 @param[in] field Field to check (can be \c NULL).
223 @returns #BT_TRUE if \p field is an integer field, or
224 #BT_FALSE otherwise (including if \p field is
228 @postrefcountsame{field}
230 @sa bt_field_get_type_id(): Returns the type ID of a given
233 extern bt_bool
bt_field_is_integer(struct bt_field
*field
);
236 @brief Returns whether or not the @field \p field is a @floatfield.
238 @param[in] field Field to check (can be \c NULL).
239 @returns #BT_TRUE if \p field is a floating point number fiel
240 #BT_FALSE or 0 otherwise (including if \p field is
244 @postrefcountsame{field}
246 @sa bt_field_get_type_id(): Returns the type ID of a given
249 extern bt_bool
bt_field_is_floating_point(struct bt_field
*field
);
252 @brief Returns whether or not the @field \p field is a @enumfield.
254 @param[in] field Field to check (can be \c NULL).
255 @returns #BT_TRUE if \p field is an enumeration field, or
256 #BT_FALSE otherwise (including if \p field is
260 @postrefcountsame{field}
262 @sa bt_field_get_type_id(): Returns the type ID of a given
265 extern bt_bool
bt_field_is_enumeration(struct bt_field
*field
);
268 @brief Returns whether or not the @field \p field is a @stringfield.
270 @param[in] field Field to check (can be \c NULL).
271 @returns #BT_TRUE if \p field is a string field, or
272 #BT_FALSE otherwise (including if \p field is
276 @postrefcountsame{field}
278 @sa bt_field_get_type_id(): Returns the type ID of a given
281 extern bt_bool
bt_field_is_string(struct bt_field
*field
);
284 @brief Returns whether or not the @field \p field is a @structfield.
286 @param[in] field Field to check (can be \c NULL).
287 @returns #BT_TRUE if \p field is a structure field, or
288 #BT_FALSE otherwise (including if \p field is
292 @postrefcountsame{field}
294 @sa bt_field_get_type_id(): Returns the type ID of a given
297 extern bt_bool
bt_field_is_structure(struct bt_field
*field
);
300 @brief Returns whether or not the @field \p field is a @arrayfield.
302 @param[in] field Field to check (can be \c NULL).
303 @returns #BT_TRUE if \p field is an array field, or
304 #BT_FALSE otherwise (including if \p field is
308 @postrefcountsame{field}
310 @sa bt_field_get_type_id(): Returns the type ID of a given
313 extern bt_bool
bt_field_is_array(struct bt_field
*field
);
316 @brief Returns whether or not the @field \p field is a @seqfield.
318 @param[in] field Field to check (can be \c NULL).
319 @returns #BT_TRUE if \p field is a sequence field, or
320 #BT_FALSE otherwise (including if \p field is
324 @postrefcountsame{field}
326 @sa bt_field_get_type_id(): Returns the type ID of a given
329 extern bt_bool
bt_field_is_sequence(struct bt_field
*field
);
332 @brief Returns whether or not the @field \p field is a @varfield.
334 @param[in] field Field to check (can be \c NULL).
335 @returns #BT_TRUE if \p field is a variant field, or
336 #BT_FALSE otherwise (including if \p field is
340 @postrefcountsame{field}
342 @sa bt_field_get_type_id(): Returns the type ID of a given
345 extern bt_bool
bt_field_is_variant(struct bt_field
*field
);
350 @name Misc. functions
355 @brief Creates a \em deep copy of the @field \p field.
357 You can copy a frozen field: the resulting copy is <em>not frozen</em>.
359 @param[in] field Field to copy.
360 @returns Deep copy of \p field on success,
364 @postrefcountsame{field}
365 @postsuccessrefcountret1
366 @post <strong>On success</strong>, the returned field is not frozen.
368 extern struct bt_field
*bt_field_copy(struct bt_field
*field
);
375 @defgroup ctfirintfield CTF IR integer field
377 @brief CTF IR integer field.
380 #include <babeltrace/ctf-ir/fields.h>
383 A CTF IR <strong><em>integer field</em></strong> is a @field which
384 holds a signed or unsigned integral value, and which is described by
387 An integer field object is considered \em unsigned if
388 bt_field_type_integer_get_signed() on its parent field type returns
389 0. Otherwise it is considered \em signed. You \em must use
390 bt_field_integer_unsigned_get_value() and
391 bt_field_integer_unsigned_set_value() with an unsigned integer
392 field, and bt_field_integer_signed_get_value() and
393 bt_field_integer_signed_set_value() with a signed integer field.
395 After you create an integer field with bt_field_create(), you
396 \em must set an integral value with
397 bt_field_integer_unsigned_set_value() or
398 bt_field_integer_signed_set_value() before you can get the
399 field's value with bt_field_integer_unsigned_get_value() or
400 bt_field_integer_signed_get_value().
402 @sa ctfirintfieldtype
405 @addtogroup ctfirintfield
410 @brief Returns the signed integral value of the @intfield
413 @param[in] integer_field Integer field of which to get the
414 signed integral value.
415 @param[out] value Returned signed integral value of
417 @returns 0 on success, or a negative value on
418 error, including if \p integer_field
419 has no integral value yet.
421 @prenotnull{integer_field}
423 @preisintfield{integer_field}
424 @pre bt_field_type_integer_get_signed() returns 1 for the parent
425 @ft of \p integer_field.
426 @pre \p integer_field contains a signed integral value previously
427 set with bt_field_integer_signed_set_value().
428 @postrefcountsame{integer_field}
430 @sa bt_field_integer_signed_set_value(): Sets the signed integral
431 value of a given integer field.
433 extern int bt_field_integer_signed_get_value(
434 struct bt_field
*integer_field
, int64_t *value
);
437 @brief Sets the signed integral value of the @intfield
438 \p integer_field to \p value.
440 @param[in] integer_field Integer field of which to set
441 the signed integral value.
442 @param[in] value New signed integral value of
444 @returns 0 on success, or a negative value on error.
446 @prenotnull{integer_field}
447 @preisintfield{integer_field}
448 @prehot{integer_field}
449 @pre bt_field_type_integer_get_signed() returns 1 for the parent
450 @ft of \p integer_field.
451 @postrefcountsame{integer_field}
453 @sa bt_field_integer_signed_get_value(): Returns the signed integral
454 value of a given integer field.
456 extern int bt_field_integer_signed_set_value(
457 struct bt_field
*integer_field
, int64_t value
);
460 @brief Returns the unsigned integral value of the @intfield
463 @param[in] integer_field Integer field of which to get the
464 unsigned integral value.
465 @param[out] value Returned unsigned integral value of
467 @returns 0 on success, or a negative value on
468 error, including if \p integer_field
469 has no integral value yet.
471 @prenotnull{integer_field}
473 @preisintfield{integer_field}
474 @pre bt_field_type_integer_get_signed() returns 0 for the parent
475 @ft of \p integer_field.
476 @pre \p integer_field contains an unsigned integral value previously
477 set with bt_field_integer_unsigned_set_value().
478 @postrefcountsame{integer_field}
480 @sa bt_field_integer_unsigned_set_value(): Sets the unsigned
481 integral value of a given integer field.
483 extern int bt_field_integer_unsigned_get_value(
484 struct bt_field
*integer_field
, uint64_t *value
);
487 @brief Sets the unsigned integral value of the @intfield
488 \p integer_field to \p value.
490 @param[in] integer_field Integer field of which to set
491 the unsigned integral value.
492 @param[in] value New unsigned integral value of
494 @returns 0 on success, or a negative value on error.
496 @prenotnull{integer_field}
497 @preisintfield{integer_field}
498 @prehot{integer_field}
499 @pre bt_field_type_integer_get_signed() returns 0 for the parent
500 @ft of \p integer_field.
501 @postrefcountsame{integer_field}
503 @sa bt_field_integer_unsigned_get_value(): Returns the unsigned
504 integral value of a given integer field.
506 extern int bt_field_integer_unsigned_set_value(
507 struct bt_field
*integer_field
, uint64_t value
);
512 @defgroup ctfirfloatfield CTF IR floating point number field
514 @brief CTF IR floating point number field.
517 #include <babeltrace/ctf-ir/fields.h>
520 A CTF IR <strong><em>floating point number field</em></strong> is a
521 @field which holds a floating point number value, and which is
522 described by a @floatft.
524 After you create a floating point number field with bt_field_create(), you
525 \em must set a floating point number value with
526 bt_field_floating_point_set_value() before you can get the
527 field's value with bt_field_floating_point_get_value().
529 @sa ctfirfloatfieldtype
532 @addtogroup ctfirfloatfield
537 @brief Returns the floating point number value of the @floatfield
540 @param[in] float_field Floating point number field of which to get the
541 floating point number value.
542 @param[out] value Returned floating point number value of
544 @returns 0 on success, or a negative value on error,
545 including if \p float_field has no floating
546 point number value yet.
548 @prenotnull{float_field}
550 @preisfloatfield{float_field}
551 @pre \p float_field contains a floating point number value previously
552 set with bt_field_floating_point_set_value().
553 @postrefcountsame{float_field}
555 @sa bt_field_floating_point_set_value(): Sets the floating point
556 number value of a given floating point number field.
558 extern int bt_field_floating_point_get_value(
559 struct bt_field
*float_field
, double *value
);
562 @brief Sets the floating point number value of the @floatfield
563 \p float_field to \p value.
565 @param[in] float_field Floating point number field of which to set
566 the floating point number value.
567 @param[in] value New floating point number value of
569 @returns 0 on success, or a negative value on error.
571 @prenotnull{float_field}
572 @preisfloatfield{float_field}
574 @postrefcountsame{float_field}
576 @sa bt_field_floating_point_get_value(): Returns the floating point
577 number value of a given floating point number field.
579 extern int bt_field_floating_point_set_value(
580 struct bt_field
*float_field
, double value
);
585 @defgroup ctfirenumfield CTF IR enumeration field
587 @brief CTF IR enumeration field.
590 #include <babeltrace/ctf-ir/fields.h>
593 A CTF IR <strong><em>enumeration field</em></strong> is a @field which
594 holds a @intfield, and which is described by a @enumft.
596 To set the current integral value of an enumeration field, you need to
597 get its wrapped @intfield with bt_field_enumeration_get_container(),
598 and then set the integral value with either
599 bt_field_integer_signed_set_value() or
600 bt_field_integer_unsigned_set_value().
602 Once you set the integral value of an enumeration field by following the
603 previous paragraph, you can get the mappings containing this value in
604 their range with bt_field_enumeration_get_mappings(). This function
605 returns a @enumftiter.
607 @sa ctfirenumfieldtype
610 @addtogroup ctfirenumfield
615 @brief Returns the @intfield, potentially creating it, wrapped by the
616 @enumfield \p enum_field.
618 This function creates the @intfield to return if it does not currently
621 @param[in] enum_field Enumeration field of which to get the wrapped
623 @returns Integer field wrapped by \p enum_field, or
626 @prenotnull{enum_field}
627 @preisenumfield{enum_field}
628 @postrefcountsame{enum_field}
629 @postsuccessrefcountretinc
631 extern struct bt_field
*bt_field_enumeration_get_container(
632 struct bt_field
*enum_field
);
635 @brief Returns a @enumftiter on all the mappings of the field type of
636 \p enum_field which contain the current integral value of the
637 @enumfield \p enum_field in their range.
639 This function is the equivalent of using
640 bt_field_type_enumeration_find_mappings_by_unsigned_value() or
641 bt_field_type_enumeration_find_mappings_by_signed_value() with the
642 current integral value of \p enum_field.
644 @param[in] enum_field Enumeration field of which to get the mappings
645 containing the current integral value of \p
646 enum_field in their range.
647 @returns @enumftiter on the set of mappings of the field
648 type of \p enum_field which contain the current
649 integral value of \p enum_field in their range,
650 or \c NULL if no mappings were found or on
653 @prenotnull{enum_field}
654 @preisenumfield{enum_field}
655 @pre The wrapped integer field of \p enum_field contains an integral
657 @postrefcountsame{enum_field}
658 @postsuccessrefcountret1
659 @post <strong>On success</strong>, the returned @enumftiter can iterate
660 on at least one mapping.
662 extern struct bt_field_type_enumeration_mapping_iterator
*
663 bt_field_enumeration_get_mappings(struct bt_field
*enum_field
);
668 @defgroup ctfirstringfield CTF IR string field
670 @brief CTF IR string field.
673 #include <babeltrace/ctf-ir/fields.h>
676 A CTF IR <strong><em>string field</em></strong> is a @field which holds
677 a string value, and which is described by a @stringft.
679 Use bt_field_string_set_value() to set the current string value
680 of a string field object. You can also use bt_field_string_append()
681 and bt_field_string_append_len() to append a string to the current
682 value of a string field.
684 After you create a string field with bt_field_create(), you
685 \em must set a string value with
686 bt_field_string_set_value(), bt_field_string_append(), or
687 bt_field_string_append_len() before you can get the
688 field's value with bt_field_string_get_value().
690 @sa ctfirstringfieldtype
693 @addtogroup ctfirstringfield
698 @brief Returns the string value of the @stringfield \p string_field.
700 On success, \p string_field remains the sole owner of the returned
703 @param[in] string_field String field field of which to get the
705 @returns String value, or \c NULL on error.
707 @prenotnull{string_field}
709 @preisstringfield{string_field}
710 @pre \p string_field contains a string value previously
711 set with bt_field_string_set_value(),
712 bt_field_string_append(), or
713 bt_field_string_append_len().
714 @postrefcountsame{string_field}
716 @sa bt_field_string_set_value(): Sets the string value of a given
719 extern const char *bt_field_string_get_value(struct bt_field
*string_field
);
722 @brief Sets the string value of the @stringfield \p string_field to
725 @param[in] string_field String field of which to set
727 @param[in] value New string value of \p string_field (copied
729 @returns 0 on success, or a negative value on error.
731 @prenotnull{string_field}
733 @preisstringfield{string_field}
734 @prehot{string_field}
735 @postrefcountsame{string_field}
737 @sa bt_field_string_get_value(): Returns the string value of a
740 extern int bt_field_string_set_value(struct bt_field
*string_field
,
744 @brief Appends the string \p value to the current string value of
745 the @stringfield \p string_field.
747 This function is the equivalent of:
750 bt_field_string_append_len(string_field, value, strlen(value));
753 @param[in] string_field String field of which to append \p value to
755 @param[in] value String to append to the current string value
756 of \p string_field (copied on success).
757 @returns 0 on success, or a negative value on error.
759 @prenotnull{string_field}
761 @preisstringfield{string_field}
762 @prehot{string_field}
763 @postrefcountsame{string_field}
765 @sa bt_field_string_set_value(): Sets the string value of a given
768 extern int bt_field_string_append(struct bt_field
*string_field
,
772 @brief Appends the first \p length characters of \p value to the
773 current string value of the @stringfield \p string_field.
775 If \p string_field has no current string value, this function first
776 sets an empty string as the string value of \p string_field and then
777 appends the first \p length characters of \p value.
779 @param[in] string_field String field of which to append the first
780 \p length characters of \p value to
782 @param[in] value String containing the characters to append to
783 the current string value of \p string_field
785 @param[in] length Number of characters of \p value to append to
786 the current string value of \p string_field.
787 @returns 0 on success, or a negative value on error.
789 @prenotnull{string_field}
791 @preisstringfield{string_field}
792 @prehot{string_field}
793 @postrefcountsame{string_field}
795 @sa bt_field_string_set_value(): Sets the string value of a given
798 extern int bt_field_string_append_len(
799 struct bt_field
*string_field
, const char *value
,
800 unsigned int length
);
805 @defgroup ctfirstructfield CTF IR structure field
807 @brief CTF IR structure field.
810 #include <babeltrace/ctf-ir/fields.h>
813 A CTF IR <strong><em>structure field</em></strong> is a @field which
814 contains an ordered list of zero or more named @fields which can be
815 different @fts, and which is described by a @structft.
817 To set the value of a specific field of a structure field, you need to
818 first get the field with bt_field_structure_get_field_by_name() or
819 bt_field_structure_get_field_by_index(). If you already have a
820 field object, you can assign it to a specific name within a structure
821 field with bt_field_structure_set_field_by_name().
823 @sa ctfirstructfieldtype
826 @addtogroup ctfirstructfield
831 @brief Returns the @field named \p name, potentially creating it,
832 in the @structfield \p struct_field.
834 This function creates the @field to return if it does not currently
837 @param[in] struct_field Structure field of which to get the field
839 @param[in] name Name of the field to get from \p struct_field.
840 @returns Field named \p name in \p struct_field, or
843 @prenotnull{struct_field}
845 @preisstructfield{struct_field}
846 @postrefcountsame{struct_field}
847 @postsuccessrefcountretinc
849 @sa bt_field_structure_get_field_by_index(): Returns the field of a
850 given structure field by index.
851 @sa bt_field_structure_set_field_by_name(): Sets the field of a
852 given structure field by name.
854 extern struct bt_field
*bt_field_structure_get_field_by_name(
855 struct bt_field
*struct_field
, const char *name
);
858 @brief Returns the @field at index \p index in the @structfield
861 @param[in] struct_field Structure field of which to get the field
863 @param[in] index Index of the field to get in \p struct_field.
864 @returns Field at index \p index in \p struct_field, or
867 @prenotnull{struct_field}
868 @preisstructfield{struct_field}
869 @pre \p index is lesser than the number of fields contained in the
870 parent field type of \p struct_field (see
871 bt_field_type_structure_get_field_count()).
872 @postrefcountsame{struct_field}
873 @postsuccessrefcountretinc
875 @sa bt_field_structure_get_field_by_name(): Returns the field of a
876 given structure field by name.
877 @sa bt_field_structure_set_field_by_name(): Sets the field of a
878 given structure field by name.
880 extern struct bt_field
*bt_field_structure_get_field_by_index(
881 struct bt_field
*struct_field
, uint64_t index
);
884 @brief Sets the field of the @structfield \p struct_field named \p name
885 to the @field \p field.
887 If \p struct_field already contains a field named \p name, then it may
888 either be replaced by \p field and its reference count is decremented,
889 or \p field's value is assigned to it.
891 The field type of \p field, as returned by bt_field_get_type(),
892 \em must be equivalent to the field type returned by
893 bt_field_type_structure_get_field_type_by_name() with the field
894 type of \p struct_field and the same name, \p name.
896 bt_trace_get_packet_header_type() for the parent trace class of
899 @param[in] struct_field Structure field of which to set the field
901 @param[in] name Name of the field to set in \p struct_field.
902 @param[in] field Field named \p name to set in \p struct_field.
903 @returns 0 on success, or -1 on error.
905 @prenotnull{struct_field}
908 @prehot{struct_field}
909 @preisstructfield{struct_field}
910 @pre \p field has a field type equivalent to the field type returned by
911 bt_field_type_structure_get_field_type_by_name() for the
912 field type of \p struct_field with the name \p name.
913 @postrefcountsame{struct_field}
914 @post <strong>On success, the field in \p struct_field named \p name</strong>
915 may either be replaced by \p field or have the same value as \p field.
916 @postsuccessrefcountinc{field}
918 @sa bt_field_structure_get_field_by_index(): Returns the field of a
919 given structure field by index.
920 @sa bt_field_structure_get_field_by_name(): Returns the field of a
921 given structure field by name.
923 extern int bt_field_structure_set_field_by_name(
924 struct bt_field
*struct_field
,
925 const char *name
, struct bt_field
*field
);
930 @defgroup ctfirarrayfield CTF IR array field
932 @brief CTF IR array field.
935 #include <babeltrace/ctf-ir/fields.h>
938 A CTF IR <strong><em>array field</em></strong> is a @field which
939 contains an ordered list of zero or more @fields sharing the same @ft,
940 and which is described by a @arrayft.
942 To set the value of a specific field of an array field, you need to
943 first get the field with bt_field_array_get_field().
945 @sa ctfirarrayfieldtype
948 @addtogroup ctfirarrayfield
953 @brief Returns the @field at index \p index, potentially creating it,
954 in the @arrayfield \p array_field.
956 This function creates the @field to return if it does not currently
959 @param[in] array_field Array field of which to get the field
961 @param[in] index Index of the field to get in \p array_field.
962 @returns Field at index \p index in \p array_field, or
965 @prenotnull{array_field}
966 @preisarrayfield{array_field}
967 @pre \p index is lesser than bt_field_type_array_get_length() called
968 on the field type of \p array_field.
969 @postrefcountsame{array_field}
970 @postsuccessrefcountretinc
972 extern struct bt_field
*bt_field_array_get_field(
973 struct bt_field
*array_field
, uint64_t index
);
978 @defgroup ctfirseqfield CTF IR sequence field
980 @brief CTF IR sequence field.
983 #include <babeltrace/ctf-ir/fields.h>
986 A CTF IR <strong><em>sequence field</em></strong> is a @field which
987 contains an ordered list of zero or more @fields sharing the same @ft,
988 and which is described by a @seqft.
990 Before you can get a specific field of a sequence field with
991 bt_field_sequence_get_field(), you need to set its current length
992 @intfield with bt_field_sequence_set_length(). The integral value of
993 the length field of a sequence field indicates the number of fields
996 @sa ctfirseqfieldtype
999 @addtogroup ctfirseqfield
1004 @brief Returns the @field at index \p index, potentially creating it,
1005 in the @seqfield \p sequence_field.
1007 This function creates the @field to return if it does not currently
1010 @param[in] sequence_field Sequence field of which to get the field
1012 @param[in] index Index of the field to get in
1014 @returns Field at index \p index in
1015 \p sequence_field, or \c NULL on error.
1017 @prenotnull{sequence_field}
1018 @preisseqfield{sequence_field}
1019 @pre \p sequence_field has a length field previously set with
1020 bt_field_sequence_set_length().
1021 @pre \p index is lesser than the current integral value of the current
1022 length field of \p sequence_field (see
1023 bt_field_sequence_get_length()).
1024 @postrefcountsame{sequence_field}
1025 @postsuccessrefcountretinc
1027 extern struct bt_field
*bt_field_sequence_get_field(
1028 struct bt_field
*sequence_field
, uint64_t index
);
1031 @brief Returns the length @intfield of the @seqfield \p sequence_field.
1033 The current integral value of the returned length field indicates the
1034 number of fields contained in \p sequence_field.
1036 @param[in] sequence_field Sequence field of which to get the
1038 @returns Length field of \p sequence_field, or
1041 @prenotnull{sequence_field}
1042 @preisseqfield{sequence_field}
1043 @pre \p sequence_field has a length field previously set with
1044 bt_field_sequence_set_length().
1045 @postrefcountsame{sequence_field}
1046 @postsuccessrefcountretinc
1047 @post <strong>On success</strong>, the returned field is a @intfield.
1049 @sa bt_field_sequence_set_length(): Sets the length field of a given
1052 extern struct bt_field
*bt_field_sequence_get_length(
1053 struct bt_field
*sequence_field
);
1056 @brief Sets the length @intfield of the @seqfield \p sequence_field
1059 The current integral value of \p length_field indicates the number of
1060 fields contained in \p sequence_field.
1062 @param[in] sequence_field Sequence field of which to set the
1064 @param[in] length_field Length field of \p sequence_field.
1065 @returns 0 on success, or a negative value on error.
1067 @prenotnull{sequence_field}
1068 @prenotnull{length_field}
1069 @preisseqfield{sequence_field}
1070 @preisintfield{length_field}
1071 @prehot{sequence_field}
1072 @postrefcountsame{sequence_field}
1073 @postsuccessrefcountinc{length_field}
1075 @sa bt_field_sequence_get_length(): Returns the length field of a
1076 given sequence field.
1078 extern int bt_field_sequence_set_length(struct bt_field
*sequence_field
,
1079 struct bt_field
*length_field
);
1084 @defgroup ctfirvarfield CTF IR variant field
1085 @ingroup ctfirfields
1086 @brief CTF IR variant field.
1089 #include <babeltrace/ctf-ir/fields.h>
1092 A CTF IR <strong><em>variant field</em></strong> is a @field which
1093 contains a current @field amongst one or more choices, and which is
1094 described by a @varft.
1096 Use bt_field_variant_get_field() to get the @field selected by
1097 a specific tag @enumfield. Once you call this function, you can call
1098 bt_field_variant_get_current_field() afterwards to get this last
1101 @sa ctfirvarfieldtype
1104 @addtogroup ctfirvarfield
1109 @brief Returns the @field, potentially creating it, selected by the
1110 tag @intfield \p tag_field in the @varfield \p variant_field.
1112 This function creates the @field to return if it does not currently
1115 Once you call this function, you can call
1116 bt_field_variant_get_current_field() to get the same field again,
1117 and you can call bt_field_variant_get_tag() to get \p tag_field.
1119 @param[in] variant_field Variant field of which to get the field
1120 selected by \p tag_field.
1121 @param[in] tag_field Tag field.
1122 @returns Field selected by \p tag_field in
1123 \p variant_field, or \c NULL on error.
1125 @prenotnull{variant_field}
1126 @prenotnull{tag_field}
1127 @preisvarfield{variant_field}
1128 @preisenumfield{tag_field}
1129 @postrefcountsame{variant_field}
1130 @postsuccessrefcountinc{tag_field}
1131 @postsuccessrefcountretinc
1133 extern struct bt_field
*bt_field_variant_get_field(
1134 struct bt_field
*variant_field
,
1135 struct bt_field
*tag_field
);
1138 @brief Returns the currently selected @field of the @varfield
1141 @param[in] variant_field Variant field of which to get the
1142 currently selected field.
1143 @returns Currently selected field of
1144 \p variant_field, or \c NULL if there's
1145 no selected field or on error.
1147 @prenotnull{variant_field}
1148 @preisvarfield{variant_field}
1149 @pre \p variant_field contains has a current selected field previously
1150 set with bt_field_variant_get_field().
1151 @postrefcountsame{variant_field}
1152 @postsuccessrefcountretinc
1154 extern struct bt_field
*bt_field_variant_get_current_field(
1155 struct bt_field
*variant_field
);
1158 @brief Returns the tag @enumfield of the @varfield \p variant_field.
1160 @param[in] variant_field Variant field of which to get the
1162 @returns Tag field of \p variant_field, or
1165 @prenotnull{variant_field}
1166 @preisvarfield{variant_field}
1167 @pre \p variant_field contains has a current selected field previously
1168 set with bt_field_variant_get_field().
1169 @postrefcountsame{variant_field}
1170 @postsuccessrefcountretinc
1171 @post <strong>On success</strong>, the returned field is a @enumfield.
1173 extern struct bt_field
*bt_field_variant_get_tag(
1174 struct bt_field
*variant_field
);
1182 #endif /* BABELTRACE_CTF_IR_FIELDS_H */