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
41 @defgroup ctfirfields CTF IR fields
46 #include <babeltrace/ctf-ir/fields.h>
49 A CTF IR <strong><em>field</em></strong> is an object which holds a
50 concrete value, and which is described by a @ft.
52 In the CTF IR hierarchy, you can set the root fields of two objects:
55 - Trace packet header field: bt_ctf_packet_set_header().
56 - Stream packet context field: bt_ctf_packet_set_context().
58 - Stream event header field: bt_ctf_event_set_header().
59 - Stream event context field: bt_ctf_event_set_stream_event_context().
60 - Event context field: bt_ctf_event_set_event_context().
61 - Event payload field: bt_ctf_event_set_payload_field().
63 There are two categories of fields:
65 - <strong>Basic fields</strong>:
66 - @intfield: contains an integral value.
67 - @floatfield: contains a floating point number value.
68 - @enumfield: contains an integer field which contains an integral
70 - @stringfield: contains a string value.
71 - <strong>Compound fields</strong>:
72 - @structfield: contains an ordered list of named fields
73 (possibly with different @fts).
74 - @arrayfield: contains an ordered list of fields which share
76 - @seqfield: contains an ordered list of fields which share
78 - @varfield: contains a single, current field.
80 You can create a field object from a @ft object with
81 bt_ctf_field_create(). The enumeration and compound fields create their
82 contained fields with the following getters if such fields do not exist
85 - bt_ctf_field_enumeration_get_container()
86 - bt_ctf_field_structure_get_field()
87 - bt_ctf_field_array_get_field()
88 - bt_ctf_field_sequence_get_field()
89 - bt_ctf_field_variant_get_field()
91 If you already have a field object, you can also assign it to a specific
92 name within a @structfield with bt_ctf_field_structure_set_field().
94 You can get a reference to the @ft which was used to create a field with
95 bt_ctf_field_get_type(). You can get the
96 \link #bt_ctf_type_id type ID\endlink of this field type directly with
97 bt_ctf_field_get_type_id().
99 You can get a deep copy of a field with bt_ctf_field_copy(). The field
100 copy, and its contained field copies if it's the case, have the same
101 field type as the originals.
103 As with any Babeltrace object, CTF IR field objects have
104 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
105 counts</a>. See \ref refs to learn more about the reference counting
106 management of Babeltrace objects.
108 The functions which freeze CTF IR \link ctfirpacket packet\endlink and
109 \link ctfirevent event\endlink objects also freeze their root field
110 objects. You cannot modify a frozen field object: it is considered
111 immutable, except for \link refs reference counting\endlink.
116 @brief CTF IR fields type and functions.
119 @addtogroup ctfirfields
125 @brief A CTF IR field.
129 struct bt_ctf_event_class
;
131 struct bt_ctf_field_type
;
132 struct bt_ctf_field_type_enumeration_mapping_iterator
;
135 @name Creation and parent field type access functions
140 @brief Creates an uninitialized @field described by the @ft
143 On success, \p field_type becomes the parent of the created field
146 On success, this function creates an \em uninitialized field: it has
147 no value. You need to set the value of the created field with one of the
148 its specific setters.
150 @param[in] field_type Field type which describes the field to create.
151 @returns Created field object, or \c NULL on error.
153 @prenotnull{field_type}
154 @postsuccessrefcountret1
155 @postsuccessfrozen{field_type}
157 extern struct bt_ctf_field
*bt_ctf_field_create(
158 struct bt_ctf_field_type
*field_type
);
161 @brief Returns the parent @ft of the @field \p field.
163 This function returns a reference to the field type which was used to
164 create the field object in the first place with bt_ctf_field_create().
166 @param[in] field Field of which to get the parent field type.
167 @returns Parent field type of \p event,
171 @postrefcountsame{field}
172 @postsuccessrefcountretinc
174 extern struct bt_ctf_field_type
*bt_ctf_field_get_type(
175 struct bt_ctf_field
*field
);
180 @name Type information
185 @brief Returns the type ID of the @ft of the @field \p field.
187 @param[in] field Field of which to get the type ID of its
189 @returns Type ID of the parent field type of \p field,
190 or #BT_CTF_TYPE_ID_UNKNOWN on error.
193 @postrefcountsame{field}
195 @sa #bt_ctf_type_id: CTF IR field type ID.
196 @sa bt_ctf_field_is_integer(): Returns whether or not a given field is a
198 @sa bt_ctf_field_is_floating_point(): Returns whether or not a given
199 field is a @floatfield.
200 @sa bt_ctf_field_is_enumeration(): Returns whether or not a given field
202 @sa bt_ctf_field_is_string(): Returns whether or not a given field is a
204 @sa bt_ctf_field_is_structure(): Returns whether or not a given field is
206 @sa bt_ctf_field_is_array(): Returns whether or not a given field is a
208 @sa bt_ctf_field_is_sequence(): Returns whether or not a given field is
210 @sa bt_ctf_field_is_variant(): Returns whether or not a given field is a
213 extern enum bt_ctf_type_id
bt_ctf_field_get_type_id(struct bt_ctf_field
*field
);
216 * bt_ctf_field_signed_integer_get_value: get a signed integer field's value
218 * Get a signed integer field's value.
220 * @param integer Signed integer field instance.
221 * @param value Pointer to a signed integer where the value will be stored.
223 * Returns 0 on success, a negative value on error.
225 extern int bt_ctf_field_signed_integer_get_value(struct bt_ctf_field
*integer
,
229 @brief Returns whether or not the @field \p field is a @intfield.
231 @param[in] field Field to check (can be \c NULL).
232 @returns 1 if \p field is an integer field, or 0
233 otherwise (including if \p field is
237 @postrefcountsame{field}
239 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
242 extern int bt_ctf_field_is_integer(struct bt_ctf_field
*field
);
245 @brief Returns whether or not the @field \p field is a @floatfield.
247 @param[in] field Field to check (can be \c NULL).
248 @returns 1 if \p field is a floating point number field,
249 or 0 otherwise (including if \p field is
253 @postrefcountsame{field}
255 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
258 extern int bt_ctf_field_is_floating_point(struct bt_ctf_field
*field
);
261 @brief Returns whether or not the @field \p field is a @enumfield.
263 @param[in] field Field to check (can be \c NULL).
264 @returns 1 if \p field is an enumeration field, or 0
265 otherwise (including if \p field is
269 @postrefcountsame{field}
271 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
274 extern int bt_ctf_field_is_enumeration(struct bt_ctf_field
*field
);
277 @brief Returns whether or not the @field \p field is a @stringfield.
279 @param[in] field Field to check (can be \c NULL).
280 @returns 1 if \p field is a string field, or 0
281 otherwise (including if \p field is
285 @postrefcountsame{field}
287 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
290 extern int bt_ctf_field_is_string(struct bt_ctf_field
*field
);
293 @brief Returns whether or not the @field \p field is a @structfield.
295 @param[in] field Field to check (can be \c NULL).
296 @returns 1 if \p field is a structure field, or 0
297 otherwise (including if \p field is
301 @postrefcountsame{field}
303 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
306 extern int bt_ctf_field_is_structure(struct bt_ctf_field
*field
);
309 @brief Returns whether or not the @field \p field is a @arrayfield.
311 @param[in] field Field to check (can be \c NULL).
312 @returns 1 if \p field is an array field, or 0
313 otherwise (including if \p field is
317 @postrefcountsame{field}
319 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
322 extern int bt_ctf_field_is_array(struct bt_ctf_field
*field
);
325 @brief Returns whether or not the @field \p field is a @seqfield.
327 @param[in] field Field to check (can be \c NULL).
328 @returns 1 if \p field is a sequence field, or 0
329 otherwise (including if \p field is
333 @postrefcountsame{field}
335 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
338 extern int bt_ctf_field_is_sequence(struct bt_ctf_field
*field
);
341 @brief Returns whether or not the @field \p field is a @varfield.
343 @param[in] field Field to check (can be \c NULL).
344 @returns 1 if \p field is a variant field, or 0
345 otherwise (including if \p field is
349 @postrefcountsame{field}
351 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
354 extern int bt_ctf_field_is_variant(struct bt_ctf_field
*field
);
359 @name Misc. functions
364 @brief Creates a \em deep copy of the @field \p field.
366 You can copy a frozen field: the resulting copy is <em>not frozen</em>.
368 @param[in] field Field to copy.
369 @returns Deep copy of \p field on success,
373 @postrefcountsame{field}
374 @postsuccessrefcountret1
375 @post <strong>On success</strong>, the returned field is not frozen.
377 extern struct bt_ctf_field
*bt_ctf_field_copy(struct bt_ctf_field
*field
);
384 @defgroup ctfirintfield CTF IR integer field
386 @brief CTF IR integer field.
389 #include <babeltrace/ctf-ir/fields.h>
392 A CTF IR <strong><em>integer field</em></strong> is a @field which
393 holds a signed or unsigned integral value, and which is described by
396 An integer field object is considered \em unsigned if
397 bt_ctf_field_type_integer_get_signed() on its parent field type returns
398 0. Otherwise it is considered \em signed. You \em must use
399 bt_ctf_field_unsigned_integer_get_value() and
400 bt_ctf_field_unsigned_integer_set_value() with an unsigned integer
401 field, and bt_ctf_field_signed_integer_get_value() and
402 bt_ctf_field_signed_integer_set_value() with a signed integer field.
404 After you create an integer field with bt_ctf_field_create(), you
405 \em must set an integral value with
406 bt_ctf_field_unsigned_integer_set_value() or
407 bt_ctf_field_signed_integer_set_value() before you can get the
408 field's value with bt_ctf_field_unsigned_integer_get_value() or
409 bt_ctf_field_signed_integer_get_value().
411 @sa ctfirintfieldtype
414 @addtogroup ctfirintfield
419 @brief Returns the signed integral value of the @intfield
422 @param[in] integer_field Integer field of which to get the
423 signed integral value.
424 @param[out] value Returned signed integral value of
426 @returns 0 on success, or a negative value on
427 error, including if \p integer_field
428 has no integral value yet.
430 @prenotnull{integer_field}
432 @preisintfield{integer_field}
433 @pre bt_ctf_field_type_integer_get_signed() returns 1 for the parent
434 @ft of \p integer_field.
435 @pre \p integer_field contains a signed integral value previously
436 set with bt_ctf_field_signed_integer_set_value().
437 @postrefcountsame{integer_field}
439 @sa bt_ctf_field_signed_integer_set_value(): Sets the signed integral
440 value of a given integer field.
442 extern int bt_ctf_field_signed_integer_get_value(
443 struct bt_ctf_field
*integer_field
, int64_t *value
);
446 @brief Sets the signed integral value of the @intfield
447 \p integer_field to \p value.
449 @param[in] integer_field Integer field of which to set
450 the signed integral value.
451 @param[in] value New signed integral value of
453 @returns 0 on success, or a negative value on error.
455 @prenotnull{integer_field}
456 @preisintfield{integer_field}
457 @prehot{integer_field}
458 @pre bt_ctf_field_type_integer_get_signed() returns 1 for the parent
459 @ft of \p integer_field.
460 @postrefcountsame{integer_field}
462 @sa bt_ctf_field_signed_integer_get_value(): Returns the signed integral
463 value of a given integer field.
465 extern int bt_ctf_field_signed_integer_set_value(
466 struct bt_ctf_field
*integer_field
, int64_t value
);
469 @brief Returns the unsigned integral value of the @intfield
472 @param[in] integer_field Integer field of which to get the
473 unsigned integral value.
474 @param[out] value Returned unsigned integral value of
476 @returns 0 on success, or a negative value on
477 error, including if \p integer_field
478 has no integral value yet.
480 @prenotnull{integer_field}
482 @preisintfield{integer_field}
483 @pre bt_ctf_field_type_integer_get_signed() returns 0 for the parent
484 @ft of \p integer_field.
485 @pre \p integer_field contains an unsigned integral value previously
486 set with bt_ctf_field_unsigned_integer_set_value().
487 @postrefcountsame{integer_field}
489 @sa bt_ctf_field_unsigned_integer_set_value(): Sets the unsigned
490 integral value of a given integer field.
492 extern int bt_ctf_field_unsigned_integer_get_value(
493 struct bt_ctf_field
*integer_field
, uint64_t *value
);
496 @brief Sets the unsigned integral value of the @intfield
497 \p integer_field to \p value.
499 @param[in] integer_field Integer field of which to set
500 the unsigned integral value.
501 @param[in] value New unsigned integral value of
503 @returns 0 on success, or a negative value on error.
505 @prenotnull{integer_field}
506 @preisintfield{integer_field}
507 @prehot{integer_field}
508 @pre bt_ctf_field_type_integer_get_signed() returns 0 for the parent
509 @ft of \p integer_field.
510 @postrefcountsame{integer_field}
512 @sa bt_ctf_field_unsigned_integer_get_value(): Returns the unsigned
513 integral value of a given integer field.
515 extern int bt_ctf_field_unsigned_integer_set_value(
516 struct bt_ctf_field
*integer_field
, uint64_t value
);
521 @defgroup ctfirfloatfield CTF IR floating point number field
523 @brief CTF IR floating point number field.
526 #include <babeltrace/ctf-ir/fields.h>
529 A CTF IR <strong><em>floating point number field</em></strong> is a
530 @field which holds a floating point number value, and which is
531 described by a @floatft.
533 After you create a floating point number field with bt_ctf_field_create(), you
534 \em must set a floating point number value with
535 bt_ctf_field_floating_point_set_value() before you can get the
536 field's value with bt_ctf_field_floating_point_get_value().
538 @sa ctfirfloatfieldtype
541 @addtogroup ctfirfloatfield
546 @brief Returns the floating point number value of the @floatfield
549 @param[in] float_field Floating point number field of which to get the
550 floating point number value.
551 @param[out] value Returned floating point number value of
553 @returns 0 on success, or a negative value on error,
554 including if \p float_field has no floating
555 point number value yet.
557 @prenotnull{float_field}
559 @preisfloatfield{float_field}
560 @pre \p float_field contains a floating point number value previously
561 set with bt_ctf_field_floating_point_set_value().
562 @postrefcountsame{float_field}
564 @sa bt_ctf_field_floating_point_set_value(): Sets the floating point
565 number value of a given floating point number field.
567 extern int bt_ctf_field_floating_point_get_value(
568 struct bt_ctf_field
*float_field
, double *value
);
571 @brief Sets the floating point number value of the @floatfield
572 \p float_field to \p value.
574 @param[in] float_field Floating point number field of which to set
575 the floating point number value.
576 @param[in] value New floating point number value of
578 @returns 0 on success, or a negative value on error.
580 @prenotnull{float_field}
581 @preisfloatfield{float_field}
583 @postrefcountsame{float_field}
585 @sa bt_ctf_field_floating_point_get_value(): Returns the floating point
586 number value of a given floating point number field.
588 extern int bt_ctf_field_floating_point_set_value(
589 struct bt_ctf_field
*float_field
,
595 @defgroup ctfirenumfield CTF IR enumeration field
597 @brief CTF IR enumeration field.
600 #include <babeltrace/ctf-ir/fields.h>
603 A CTF IR <strong><em>enumeration field</em></strong> is a @field which
604 holds a @intfield, and which is described by a @enumft.
606 To set the current integral value of an enumeration field, you need to
607 get its wrapped @intfield with bt_ctf_field_enumeration_get_container(),
608 and then set the integral value with either
609 bt_ctf_field_signed_integer_set_value() or
610 bt_ctf_field_unsigned_integer_set_value().
612 Once you set the integral value of an enumeration field by following the
613 previous paragraph, you can get the mappings containing this value in
614 their range with bt_ctf_field_enumeration_get_mappings(). This function
615 returns a @enumftiter.
617 @sa ctfirenumfieldtype
620 @addtogroup ctfirenumfield
625 @brief Returns the @intfield, potentially creating it, wrapped by the
626 @enumfield \p enum_field.
628 This function creates the @intfield to return if it does not currently
631 @param[in] enum_field Enumeration field of which to get the wrapped
633 @returns Integer field wrapped by \p enum_field, or
636 @prenotnull{enum_field}
637 @preisenumfield{enum_field}
638 @postrefcountsame{enum_field}
639 @postsuccessrefcountretinc
641 extern struct bt_ctf_field
*bt_ctf_field_enumeration_get_container(
642 struct bt_ctf_field
*enum_field
);
645 @brief Returns a @enumftiter on all the mappings of the field type of
646 \p enum_field which contain the current integral value of the
647 @enumfield \p enum_field in their range.
649 This function is the equivalent of using
650 bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value() or
651 bt_ctf_field_type_enumeration_find_mappings_by_signed_value() with the
652 current integral value of \p enum_field.
654 @param[in] enum_field Enumeration field of which to get the mappings
655 containing the current integral value of \p
656 enum_field in their range.
657 @returns @enumftiter on the set of mappings of the field
658 type of \p enum_field which contain the current
659 integral value of \p enum_field in their range,
660 or \c NULL if no mappings were found or on
663 @prenotnull{enum_field}
664 @preisenumfield{enum_field}
665 @pre The wrapped integer field of \p enum_field contains an integral
667 @postrefcountsame{enum_field}
668 @postsuccessrefcountret1
669 @post <strong>On success</strong>, the returned @enumftiter can iterate
670 on at least one mapping.
672 extern struct bt_ctf_field_type_enumeration_mapping_iterator
*
673 bt_ctf_field_enumeration_get_mappings(struct bt_ctf_field
*enum_field
);
678 @defgroup ctfirstringfield CTF IR string field
680 @brief CTF IR string field.
683 #include <babeltrace/ctf-ir/fields.h>
686 A CTF IR <strong><em>string field</em></strong> is a @field which holds
687 a string value, and which is described by a @stringft.
689 Use bt_ctf_field_string_set_value() to set the current string value
690 of a string field object. You can also use bt_ctf_field_string_append()
691 and bt_ctf_field_string_append_len() to append a string to the current
692 value of a string field.
694 After you create a string field with bt_ctf_field_create(), you
695 \em must set a string value with
696 bt_ctf_field_string_set_value(), bt_ctf_field_string_append(), or
697 bt_ctf_field_string_append_len() before you can get the
698 field's value with bt_ctf_field_string_get_value().
700 @sa ctfirstringfieldtype
703 @addtogroup ctfirstringfield
708 @brief Returns the string value of the @stringfield \p string_field.
710 On success, \p string_field remains the sole owner of the returned
713 @param[in] string_field String field field of which to get the
715 @returns String value, or \c NULL on error.
717 @prenotnull{string_field}
719 @preisstringfield{string_field}
720 @pre \p string_field contains a string value previously
721 set with bt_ctf_field_string_set_value(),
722 bt_ctf_field_string_append(), or
723 bt_ctf_field_string_append_len().
724 @postrefcountsame{string_field}
726 @sa bt_ctf_field_string_set_value(): Sets the string value of a given
729 extern const char *bt_ctf_field_string_get_value(
730 struct bt_ctf_field
*string_field
);
733 @brief Sets the string value of the @stringfield \p string_field to
736 @param[in] string_field String field of which to set
738 @param[in] value New string value of \p string_field (copied
740 @returns 0 on success, or a negative value on error.
742 @prenotnull{string_field}
744 @preisstringfield{string_field}
745 @prehot{string_field}
746 @postrefcountsame{string_field}
748 @sa bt_ctf_field_string_get_value(): Returns the string value of a
751 extern int bt_ctf_field_string_set_value(struct bt_ctf_field
*string_field
,
755 @brief Appends the string \p value to the current string value of
756 the @stringfield \p string_field.
758 This function is the equivalent of:
761 bt_ctf_field_string_append_len(string_field, value, strlen(value));
764 @param[in] string_field String field of which to append \p value to
766 @param[in] value String to append to the current string value
767 of \p string_field (copied on success).
768 @returns 0 on success, or a negative value on error.
770 @prenotnull{string_field}
772 @preisstringfield{string_field}
773 @prehot{string_field}
774 @postrefcountsame{string_field}
776 @sa bt_ctf_field_string_set_value(): Sets the string value of a given
779 extern int bt_ctf_field_string_append(struct bt_ctf_field
*string_field
,
783 @brief Appends the first \p length characters of \p value to the
784 current string value of the @stringfield \p string_field.
786 If \p string_field has no current string value, this function first
787 sets an empty string as the string value of \p string_field and then
788 appends the first \p length characters of \p value.
790 @param[in] string_field String field of which to append the first
791 \p length characters of \p value to
793 @param[in] value String containing the characters to append to
794 the current string value of \p string_field
796 @param[in] length Number of characters of \p value to append to
797 the current string value of \p string_field.
798 @returns 0 on success, or a negative value on error.
800 @prenotnull{string_field}
802 @preisstringfield{string_field}
803 @prehot{string_field}
804 @postrefcountsame{string_field}
806 @sa bt_ctf_field_string_set_value(): Sets the string value of a given
809 extern int bt_ctf_field_string_append_len(
810 struct bt_ctf_field
*string_field
, const char *value
,
811 unsigned int length
);
816 @defgroup ctfirstructfield CTF IR structure field
818 @brief CTF IR structure field.
821 #include <babeltrace/ctf-ir/fields.h>
824 A CTF IR <strong><em>structure field</em></strong> is a @field which
825 contains an ordered list of zero or more named @fields which can be
826 different @fts, and which is described by a @structft.
828 To set the value of a specific field of a structure field, you need to
829 first get the field with bt_ctf_field_structure_get_field() or
830 bt_ctf_field_structure_get_field_by_index(). If you already have a
831 field object, you can assign it to a specific name within a structure
832 field with bt_ctf_field_structure_set_field().
834 @sa ctfirstructfieldtype
837 @addtogroup ctfirstructfield
842 @brief Returns the @field named \p name, potentially creating it,
843 in the @structfield \p struct_field.
845 This function creates the @field to return if it does not currently
848 @param[in] struct_field Structure field of which to get the field
850 @param[in] name Name of the field to get from \p struct_field.
851 @returns Field named \p name in \p struct_field, or
854 @prenotnull{struct_field}
856 @preisstructfield{struct_field}
857 @postrefcountsame{struct_field}
858 @postsuccessrefcountretinc
860 @sa bt_ctf_field_structure_get_field_by_index(): Returns the field of a
861 given structure field by index.
862 @sa bt_ctf_field_structure_set_field(): Sets the field of a given
865 extern struct bt_ctf_field
*bt_ctf_field_structure_get_field(
866 struct bt_ctf_field
*struct_field
, const char *name
);
869 @brief Returns the @field at index \p index in the @structfield
872 @param[in] struct_field Structure field of which to get the field
874 @param[in] index Index of the field to get in \p struct_field.
875 @returns Field at index \p index in \p struct_field, or
878 @prenotnull{struct_field}
879 @preisstructfield{struct_field}
880 @pre \p index is lesser than the number of fields contained in the
881 parent field type of \p struct_field (see
882 bt_ctf_field_type_structure_get_field_count()).
883 @postrefcountsame{struct_field}
884 @postsuccessrefcountretinc
886 @sa bt_ctf_field_structure_get_field(): Returns the field of a
887 given structure field by name.
888 @sa bt_ctf_field_structure_set_field(): Sets the field of a given
891 extern struct bt_ctf_field
*bt_ctf_field_structure_get_field_by_index(
892 struct bt_ctf_field
*struct_field
, int index
);
895 @brief Sets the field of the @structfield \p struct_field named \p name
896 to the @field \p field.
898 If \p struct_field already contains a field named \p name, then its
899 reference count is decremented, and \p field replaces it.
901 The field type of \p field, as returned by bt_ctf_field_get_type(),
902 \em must be equivalent to the field type returned by
903 bt_ctf_field_type_structure_get_field_type_by_name() with the field
904 type of \p struct_field and the same name, \p name.
906 bt_ctf_trace_get_packet_header_type() for the parent trace class of
909 @param[in] struct_field Structure field of which to set the field
911 @param[in] name Name of the field to set in \p struct_field.
912 @param[in] field Field named \p name to set in \p struct_field.
913 @returns 0 on success, or -1 on error.
915 @prenotnull{struct_field}
918 @prehot{struct_field}
919 @preisstructfield{struct_field}
920 @pre \p field has a field type equivalent to the field type returned by
921 bt_ctf_field_type_structure_get_field_type_by_name() for the
922 field type of \p struct_field with the name \p name.
923 @postrefcountsame{struct_field}
924 @post <strong>On success, if there's an existing field in
925 \p struct_field named \p name</strong>, its reference count is
927 @postsuccessrefcountinc{field}
929 @sa bt_ctf_field_structure_get_field_by_index(): Returns the field of a
930 given structure field by index.
931 @sa bt_ctf_field_structure_get_field(): Returns the field of a
932 given structure field by name.
934 extern int bt_ctf_field_structure_set_field(struct bt_ctf_field
*struct_field
,
935 const char *name
, struct bt_ctf_field
*field
);
940 @defgroup ctfirarrayfield CTF IR array field
942 @brief CTF IR array field.
945 #include <babeltrace/ctf-ir/fields.h>
948 A CTF IR <strong><em>array field</em></strong> is a @field which
949 contains an ordered list of zero or more @fields sharing the same @ft,
950 and which is described by a @arrayft.
952 To set the value of a specific field of an array field, you need to
953 first get the field with bt_ctf_field_array_get_field().
955 @sa ctfirarrayfieldtype
958 @addtogroup ctfirarrayfield
963 @brief Returns the @field at index \p index, potentially creating it,
964 in the @arrayfield \p array_field.
966 This function creates the @field to return if it does not currently
969 @param[in] array_field Array field of which to get the field
971 @param[in] index Index of the field to get in \p array_field.
972 @returns Field at index \p index in \p array_field, or
975 @prenotnull{array_field}
976 @preisarrayfield{array_field}
977 @pre \p index is lesser than bt_ctf_field_type_array_get_length() called
978 on the field type of \p array_field.
979 @postrefcountsame{array_field}
980 @postsuccessrefcountretinc
982 extern struct bt_ctf_field
*bt_ctf_field_array_get_field(
983 struct bt_ctf_field
*array_field
, uint64_t index
);
988 @defgroup ctfirseqfield CTF IR sequence field
990 @brief CTF IR sequence field.
993 #include <babeltrace/ctf-ir/fields.h>
996 A CTF IR <strong><em>sequence field</em></strong> is a @field which
997 contains an ordered list of zero or more @fields sharing the same @ft,
998 and which is described by a @seqft.
1000 Before you can get a specific field of a sequence field with
1001 bt_ctf_field_sequence_get_field(), you need to set its current length
1002 @intfield with bt_ctf_field_sequence_set_length(). The integral value of
1003 the length field of a sequence field indicates the number of fields
1006 @sa ctfirseqfieldtype
1009 @addtogroup ctfirseqfield
1014 @brief Returns the @field at index \p index, potentially creating it,
1015 in the @seqfield \p sequence_field.
1017 This function creates the @field to return if it does not currently
1020 @param[in] sequence_field Sequence field of which to get the field
1022 @param[in] index Index of the field to get in
1024 @returns Field at index \p index in
1025 \p sequence_field, or \c NULL on error.
1027 @prenotnull{sequence_field}
1028 @preisseqfield{sequence_field}
1029 @pre \p sequence_field has a length field previously set with
1030 bt_ctf_field_sequence_set_length().
1031 @pre \p index is lesser than the current integral value of the current
1032 length field of \p sequence_field (see
1033 bt_ctf_field_sequence_get_length()).
1034 @postrefcountsame{sequence_field}
1035 @postsuccessrefcountretinc
1037 extern struct bt_ctf_field
*bt_ctf_field_sequence_get_field(
1038 struct bt_ctf_field
*sequence_field
, uint64_t index
);
1041 @brief Returns the length @intfield of the @seqfield \p sequence_field.
1043 The current integral value of the returned length field indicates the
1044 number of fields contained in \p sequence_field.
1046 @param[in] sequence_field Sequence field of which to get the
1048 @returns Length field of \p sequence_field, or
1051 @prenotnull{sequence_field}
1052 @preisseqfield{sequence_field}
1053 @pre \p sequence_field has a length field previously set with
1054 bt_ctf_field_sequence_set_length().
1055 @postrefcountsame{sequence_field}
1056 @postsuccessrefcountretinc
1057 @post <strong>On success</strong>, the returned field is a @intfield.
1059 @sa bt_ctf_field_sequence_set_length(): Sets the length field of a given
1062 extern struct bt_ctf_field
*bt_ctf_field_sequence_get_length(
1063 struct bt_ctf_field
*sequence_field
);
1066 @brief Sets the length @intfield of the @seqfield \p sequence_field
1069 The current integral value of \p length_field indicates the number of
1070 fields contained in \p sequence_field.
1072 @param[in] sequence_field Sequence field of which to set the
1074 @param[in] length_field Length field of \p sequence_field.
1075 @returns 0 on success, or a negative value on error.
1077 @prenotnull{sequence_field}
1078 @prenotnull{length_field}
1079 @preisseqfield{sequence_field}
1080 @preisintfield{length_field}
1081 @prehot{sequence_field}
1082 @postrefcountsame{sequence_field}
1083 @postsuccessrefcountinc{length_field}
1085 @sa bt_ctf_field_sequence_get_length(): Returns the length field of a
1086 given sequence field.
1088 extern int bt_ctf_field_sequence_set_length(struct bt_ctf_field
*sequence_field
,
1089 struct bt_ctf_field
*length_field
);
1094 @defgroup ctfirvarfield CTF IR variant field
1095 @ingroup ctfirfields
1096 @brief CTF IR variant field.
1099 #include <babeltrace/ctf-ir/fields.h>
1102 A CTF IR <strong><em>variant field</em></strong> is a @field which
1103 contains a current @field amongst one or more choices, and which is
1104 described by a @varft.
1106 Use bt_ctf_field_variant_get_field() to get the @field selected by
1107 a specific tag @enumfield. Once you call this function, you can call
1108 bt_ctf_field_variant_get_current_field() afterwards to get this last
1111 @sa ctfirvarfieldtype
1114 @addtogroup ctfirvarfield
1119 @brief Returns the @field, potentially creating it, selected by the
1120 tag @intfield \p tag_field in the @varfield \p variant_field.
1122 This function creates the @field to return if it does not currently
1125 Once you call this function, you can call
1126 bt_ctf_field_variant_get_current_field() to get the same field again,
1127 and you can call bt_ctf_field_variant_get_tag() to get \p tag_field.
1129 @param[in] variant_field Variant field of which to get the field
1130 selected by \p tag_field.
1131 @param[in] tag_field Tag field.
1132 @returns Field selected by \p tag_field in
1133 \p variant_field, or \c NULL on error.
1135 @prenotnull{variant_field}
1136 @prenotnull{tag_field}
1137 @preisvarfield{variant_field}
1138 @preisenumfield{tag_field}
1139 @postrefcountsame{variant_field}
1140 @postsuccessrefcountinc{tag_field}
1141 @postsuccessrefcountretinc
1143 extern struct bt_ctf_field
*bt_ctf_field_variant_get_field(
1144 struct bt_ctf_field
*variant_field
,
1145 struct bt_ctf_field
*tag_field
);
1148 @brief Returns the currently selected @field of the @varfield
1151 @param[in] variant_field Variant field of which to get the
1152 currently selected field.
1153 @returns Currently selected field of
1154 \p variant_field, or \c NULL if there's
1155 no selected field or on error.
1157 @prenotnull{variant_field}
1158 @preisvarfield{variant_field}
1159 @pre \p variant_field contains has a current selected field previously
1160 set with bt_ctf_field_variant_get_field().
1161 @postrefcountsame{variant_field}
1162 @postsuccessrefcountretinc
1164 extern struct bt_ctf_field
*bt_ctf_field_variant_get_current_field(
1165 struct bt_ctf_field
*variant_field
);
1168 @brief Returns the tag @enumfield of the @varfield \p variant_field.
1170 @param[in] variant_field Variant field of which to get the
1172 @returns Tag field of \p variant_field, or
1175 @prenotnull{variant_field}
1176 @preisvarfield{variant_field}
1177 @pre \p variant_field contains has a current selected field previously
1178 set with bt_ctf_field_variant_get_field().
1179 @postrefcountsame{variant_field}
1180 @postsuccessrefcountretinc
1181 @post <strong>On success</strong>, the returned field is a @enumfield.
1183 extern struct bt_ctf_field
*bt_ctf_field_variant_get_tag(
1184 struct bt_ctf_field
*variant_field
);
1192 #endif /* BABELTRACE_CTF_IR_FIELDS_H */