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
35 #include <babeltrace/ctf-ir/field-types.h>
36 #include <babeltrace/types.h>
43 @defgroup ctfirfields CTF IR fields
48 #include <babeltrace/ctf-ir/fields.h>
51 A CTF IR <strong><em>field</em></strong> is an object which holds a
52 concrete value, and which is described by a @ft.
54 In the CTF IR hierarchy, you can set the root fields of two objects:
57 - Trace packet header field: bt_ctf_packet_set_header().
58 - Stream packet context field: bt_ctf_packet_set_context().
60 - Stream event header field: bt_ctf_event_set_header().
61 - Stream event context field: bt_ctf_event_set_stream_event_context().
62 - Event context field: bt_ctf_event_set_event_context().
63 - Event payload field: bt_ctf_event_set_payload_field().
65 There are two categories of fields:
67 - <strong>Basic fields</strong>:
68 - @intfield: contains an integral value.
69 - @floatfield: contains a floating point number value.
70 - @enumfield: contains an integer field which contains an integral
72 - @stringfield: contains a string value.
73 - <strong>Compound fields</strong>:
74 - @structfield: contains an ordered list of named fields
75 (possibly with different @fts).
76 - @arrayfield: contains an ordered list of fields which share
78 - @seqfield: contains an ordered list of fields which share
80 - @varfield: contains a single, current field.
82 You can create a field object from a @ft object with
83 bt_ctf_field_create(). The enumeration and compound fields create their
84 contained fields with the following getters if such fields do not exist
87 - bt_ctf_field_enumeration_get_container()
88 - bt_ctf_field_structure_get_field_by_name()
89 - bt_ctf_field_array_get_field()
90 - bt_ctf_field_sequence_get_field()
91 - bt_ctf_field_variant_get_field()
93 If you already have a field object, you can also assign it to a specific
94 name within a @structfield with
95 bt_ctf_field_structure_set_field_by_name().
97 You can get a reference to the @ft which was used to create a field with
98 bt_ctf_field_get_type(). You can get the
99 \link #bt_ctf_field_type_id type ID\endlink of this field type directly with
100 bt_ctf_field_get_type_id().
102 You can get a deep copy of a field with bt_ctf_field_copy(). The field
103 copy, and its contained field copies if it's the case, have the same
104 field type as the originals.
106 As with any Babeltrace object, CTF IR field objects have
107 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
108 counts</a>. See \ref refs to learn more about the reference counting
109 management of Babeltrace objects.
111 The functions which freeze CTF IR \link ctfirpacket packet\endlink and
112 \link ctfirevent event\endlink objects also freeze their root field
113 objects. You cannot modify a frozen field object: it is considered
114 immutable, except for \link refs reference counting\endlink.
119 @brief CTF IR fields type and functions.
122 @addtogroup ctfirfields
128 @brief A CTF IR field.
132 struct bt_ctf_event_class
;
134 struct bt_ctf_field_type
;
135 struct bt_ctf_field_type_enumeration_mapping_iterator
;
138 @name Creation and parent field type access functions
143 @brief Creates an uninitialized @field described by the @ft
146 On success, \p field_type becomes the parent of the created field
149 On success, this function creates an \em uninitialized field: it has
150 no value. You need to set the value of the created field with one of the
151 its specific setters.
153 @param[in] field_type Field type which describes the field to create.
154 @returns Created field object, or \c NULL on error.
156 @prenotnull{field_type}
157 @postsuccessrefcountret1
158 @postsuccessfrozen{field_type}
160 extern struct bt_ctf_field
*bt_ctf_field_create(
161 struct bt_ctf_field_type
*field_type
);
164 @brief Returns the parent @ft of the @field \p field.
166 This function returns a reference to the field type which was used to
167 create the field object in the first place with bt_ctf_field_create().
169 @param[in] field Field of which to get the parent field type.
170 @returns Parent field type of \p event,
174 @postrefcountsame{field}
175 @postsuccessrefcountretinc
177 extern struct bt_ctf_field_type
*bt_ctf_field_get_type(
178 struct bt_ctf_field
*field
);
183 @name Type information
188 @brief Returns the type ID of the @ft of the @field \p field.
190 @param[in] field Field of which to get the type ID of its
192 @returns Type ID of the parent field type of \p field,
193 or #BT_CTF_FIELD_TYPE_ID_UNKNOWN on error.
196 @postrefcountsame{field}
198 @sa #bt_ctf_field_type_id: CTF IR field type ID.
199 @sa bt_ctf_field_is_integer(): Returns whether or not a given field is a
201 @sa bt_ctf_field_is_floating_point(): Returns whether or not a given
202 field is a @floatfield.
203 @sa bt_ctf_field_is_enumeration(): Returns whether or not a given field
205 @sa bt_ctf_field_is_string(): Returns whether or not a given field is a
207 @sa bt_ctf_field_is_structure(): Returns whether or not a given field is
209 @sa bt_ctf_field_is_array(): Returns whether or not a given field is a
211 @sa bt_ctf_field_is_sequence(): Returns whether or not a given field is
213 @sa bt_ctf_field_is_variant(): Returns whether or not a given field is a
216 extern enum bt_ctf_field_type_id
bt_ctf_field_get_type_id(struct bt_ctf_field
*field
);
219 * bt_ctf_field_signed_integer_get_value: get a signed integer field's value
221 * Get a signed integer field's value.
223 * @param integer Signed integer field instance.
224 * @param value Pointer to a signed integer where the value will be stored.
226 * Returns 0 on success, a negative value on error.
228 extern int bt_ctf_field_signed_integer_get_value(struct bt_ctf_field
*integer
,
232 @brief Returns whether or not the @field \p field is a @intfield.
234 @param[in] field Field to check (can be \c NULL).
235 @returns #BT_TRUE if \p field is an integer field, or
236 #BT_FALSE otherwise (including if \p field is
240 @postrefcountsame{field}
242 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
245 extern bt_bool
bt_ctf_field_is_integer(struct bt_ctf_field
*field
);
248 @brief Returns whether or not the @field \p field is a @floatfield.
250 @param[in] field Field to check (can be \c NULL).
251 @returns #BT_TRUE if \p field is a floating point number fiel
252 #BT_FALSE or 0 otherwise (including if \p field is
256 @postrefcountsame{field}
258 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
261 extern bt_bool
bt_ctf_field_is_floating_point(struct bt_ctf_field
*field
);
264 @brief Returns whether or not the @field \p field is a @enumfield.
266 @param[in] field Field to check (can be \c NULL).
267 @returns #BT_TRUE if \p field is an enumeration field, or
268 #BT_FALSE otherwise (including if \p field is
272 @postrefcountsame{field}
274 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
277 extern bt_bool
bt_ctf_field_is_enumeration(struct bt_ctf_field
*field
);
280 @brief Returns whether or not the @field \p field is a @stringfield.
282 @param[in] field Field to check (can be \c NULL).
283 @returns #BT_TRUE if \p field is a string field, or
284 #BT_FALSE otherwise (including if \p field is
288 @postrefcountsame{field}
290 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
293 extern bt_bool
bt_ctf_field_is_string(struct bt_ctf_field
*field
);
296 @brief Returns whether or not the @field \p field is a @structfield.
298 @param[in] field Field to check (can be \c NULL).
299 @returns #BT_TRUE if \p field is a structure field, or
300 #BT_FALSE otherwise (including if \p field is
304 @postrefcountsame{field}
306 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
309 extern bt_bool
bt_ctf_field_is_structure(struct bt_ctf_field
*field
);
312 @brief Returns whether or not the @field \p field is a @arrayfield.
314 @param[in] field Field to check (can be \c NULL).
315 @returns #BT_TRUE if \p field is an array field, or
316 #BT_FALSE otherwise (including if \p field is
320 @postrefcountsame{field}
322 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
325 extern bt_bool
bt_ctf_field_is_array(struct bt_ctf_field
*field
);
328 @brief Returns whether or not the @field \p field is a @seqfield.
330 @param[in] field Field to check (can be \c NULL).
331 @returns #BT_TRUE if \p field is a sequence field, or
332 #BT_FALSE otherwise (including if \p field is
336 @postrefcountsame{field}
338 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
341 extern bt_bool
bt_ctf_field_is_sequence(struct bt_ctf_field
*field
);
344 @brief Returns whether or not the @field \p field is a @varfield.
346 @param[in] field Field to check (can be \c NULL).
347 @returns #BT_TRUE if \p field is a variant field, or
348 #BT_FALSE otherwise (including if \p field is
352 @postrefcountsame{field}
354 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
357 extern bt_bool
bt_ctf_field_is_variant(struct bt_ctf_field
*field
);
362 @name Misc. functions
367 @brief Creates a \em deep copy of the @field \p field.
369 You can copy a frozen field: the resulting copy is <em>not frozen</em>.
371 @param[in] field Field to copy.
372 @returns Deep copy of \p field on success,
376 @postrefcountsame{field}
377 @postsuccessrefcountret1
378 @post <strong>On success</strong>, the returned field is not frozen.
380 extern struct bt_ctf_field
*bt_ctf_field_copy(struct bt_ctf_field
*field
);
387 @defgroup ctfirintfield CTF IR integer field
389 @brief CTF IR integer field.
392 #include <babeltrace/ctf-ir/fields.h>
395 A CTF IR <strong><em>integer field</em></strong> is a @field which
396 holds a signed or unsigned integral value, and which is described by
399 An integer field object is considered \em unsigned if
400 bt_ctf_field_type_integer_get_signed() on its parent field type returns
401 0. Otherwise it is considered \em signed. You \em must use
402 bt_ctf_field_unsigned_integer_get_value() and
403 bt_ctf_field_unsigned_integer_set_value() with an unsigned integer
404 field, and bt_ctf_field_signed_integer_get_value() and
405 bt_ctf_field_signed_integer_set_value() with a signed integer field.
407 After you create an integer field with bt_ctf_field_create(), you
408 \em must set an integral value with
409 bt_ctf_field_unsigned_integer_set_value() or
410 bt_ctf_field_signed_integer_set_value() before you can get the
411 field's value with bt_ctf_field_unsigned_integer_get_value() or
412 bt_ctf_field_signed_integer_get_value().
414 @sa ctfirintfieldtype
417 @addtogroup ctfirintfield
422 @brief Returns the signed integral value of the @intfield
425 @param[in] integer_field Integer field of which to get the
426 signed integral value.
427 @param[out] value Returned signed integral value of
429 @returns 0 on success, or a negative value on
430 error, including if \p integer_field
431 has no integral value yet.
433 @prenotnull{integer_field}
435 @preisintfield{integer_field}
436 @pre bt_ctf_field_type_integer_get_signed() returns 1 for the parent
437 @ft of \p integer_field.
438 @pre \p integer_field contains a signed integral value previously
439 set with bt_ctf_field_signed_integer_set_value().
440 @postrefcountsame{integer_field}
442 @sa bt_ctf_field_signed_integer_set_value(): Sets the signed integral
443 value of a given integer field.
445 extern int bt_ctf_field_signed_integer_get_value(
446 struct bt_ctf_field
*integer_field
, int64_t *value
);
449 @brief Sets the signed integral value of the @intfield
450 \p integer_field to \p value.
452 @param[in] integer_field Integer field of which to set
453 the signed integral value.
454 @param[in] value New signed integral value of
456 @returns 0 on success, or a negative value on error.
458 @prenotnull{integer_field}
459 @preisintfield{integer_field}
460 @prehot{integer_field}
461 @pre bt_ctf_field_type_integer_get_signed() returns 1 for the parent
462 @ft of \p integer_field.
463 @postrefcountsame{integer_field}
465 @sa bt_ctf_field_signed_integer_get_value(): Returns the signed integral
466 value of a given integer field.
468 extern int bt_ctf_field_signed_integer_set_value(
469 struct bt_ctf_field
*integer_field
, int64_t value
);
472 @brief Returns the unsigned integral value of the @intfield
475 @param[in] integer_field Integer field of which to get the
476 unsigned integral value.
477 @param[out] value Returned unsigned integral value of
479 @returns 0 on success, or a negative value on
480 error, including if \p integer_field
481 has no integral value yet.
483 @prenotnull{integer_field}
485 @preisintfield{integer_field}
486 @pre bt_ctf_field_type_integer_get_signed() returns 0 for the parent
487 @ft of \p integer_field.
488 @pre \p integer_field contains an unsigned integral value previously
489 set with bt_ctf_field_unsigned_integer_set_value().
490 @postrefcountsame{integer_field}
492 @sa bt_ctf_field_unsigned_integer_set_value(): Sets the unsigned
493 integral value of a given integer field.
495 extern int bt_ctf_field_unsigned_integer_get_value(
496 struct bt_ctf_field
*integer_field
, uint64_t *value
);
499 @brief Sets the unsigned integral value of the @intfield
500 \p integer_field to \p value.
502 @param[in] integer_field Integer field of which to set
503 the unsigned integral value.
504 @param[in] value New unsigned integral value of
506 @returns 0 on success, or a negative value on error.
508 @prenotnull{integer_field}
509 @preisintfield{integer_field}
510 @prehot{integer_field}
511 @pre bt_ctf_field_type_integer_get_signed() returns 0 for the parent
512 @ft of \p integer_field.
513 @postrefcountsame{integer_field}
515 @sa bt_ctf_field_unsigned_integer_get_value(): Returns the unsigned
516 integral value of a given integer field.
518 extern int bt_ctf_field_unsigned_integer_set_value(
519 struct bt_ctf_field
*integer_field
, uint64_t value
);
524 @defgroup ctfirfloatfield CTF IR floating point number field
526 @brief CTF IR floating point number field.
529 #include <babeltrace/ctf-ir/fields.h>
532 A CTF IR <strong><em>floating point number field</em></strong> is a
533 @field which holds a floating point number value, and which is
534 described by a @floatft.
536 After you create a floating point number field with bt_ctf_field_create(), you
537 \em must set a floating point number value with
538 bt_ctf_field_floating_point_set_value() before you can get the
539 field's value with bt_ctf_field_floating_point_get_value().
541 @sa ctfirfloatfieldtype
544 @addtogroup ctfirfloatfield
549 @brief Returns the floating point number value of the @floatfield
552 @param[in] float_field Floating point number field of which to get the
553 floating point number value.
554 @param[out] value Returned floating point number value of
556 @returns 0 on success, or a negative value on error,
557 including if \p float_field has no floating
558 point number value yet.
560 @prenotnull{float_field}
562 @preisfloatfield{float_field}
563 @pre \p float_field contains a floating point number value previously
564 set with bt_ctf_field_floating_point_set_value().
565 @postrefcountsame{float_field}
567 @sa bt_ctf_field_floating_point_set_value(): Sets the floating point
568 number value of a given floating point number field.
570 extern int bt_ctf_field_floating_point_get_value(
571 struct bt_ctf_field
*float_field
, double *value
);
574 @brief Sets the floating point number value of the @floatfield
575 \p float_field to \p value.
577 @param[in] float_field Floating point number field of which to set
578 the floating point number value.
579 @param[in] value New floating point number value of
581 @returns 0 on success, or a negative value on error.
583 @prenotnull{float_field}
584 @preisfloatfield{float_field}
586 @postrefcountsame{float_field}
588 @sa bt_ctf_field_floating_point_get_value(): Returns the floating point
589 number value of a given floating point number field.
591 extern int bt_ctf_field_floating_point_set_value(
592 struct bt_ctf_field
*float_field
,
598 @defgroup ctfirenumfield CTF IR enumeration field
600 @brief CTF IR enumeration field.
603 #include <babeltrace/ctf-ir/fields.h>
606 A CTF IR <strong><em>enumeration field</em></strong> is a @field which
607 holds a @intfield, and which is described by a @enumft.
609 To set the current integral value of an enumeration field, you need to
610 get its wrapped @intfield with bt_ctf_field_enumeration_get_container(),
611 and then set the integral value with either
612 bt_ctf_field_signed_integer_set_value() or
613 bt_ctf_field_unsigned_integer_set_value().
615 Once you set the integral value of an enumeration field by following the
616 previous paragraph, you can get the mappings containing this value in
617 their range with bt_ctf_field_enumeration_get_mappings(). This function
618 returns a @enumftiter.
620 @sa ctfirenumfieldtype
623 @addtogroup ctfirenumfield
628 @brief Returns the @intfield, potentially creating it, wrapped by the
629 @enumfield \p enum_field.
631 This function creates the @intfield to return if it does not currently
634 @param[in] enum_field Enumeration field of which to get the wrapped
636 @returns Integer field wrapped by \p enum_field, or
639 @prenotnull{enum_field}
640 @preisenumfield{enum_field}
641 @postrefcountsame{enum_field}
642 @postsuccessrefcountretinc
644 extern struct bt_ctf_field
*bt_ctf_field_enumeration_get_container(
645 struct bt_ctf_field
*enum_field
);
648 @brief Returns a @enumftiter on all the mappings of the field type of
649 \p enum_field which contain the current integral value of the
650 @enumfield \p enum_field in their range.
652 This function is the equivalent of using
653 bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value() or
654 bt_ctf_field_type_enumeration_find_mappings_by_signed_value() with the
655 current integral value of \p enum_field.
657 @param[in] enum_field Enumeration field of which to get the mappings
658 containing the current integral value of \p
659 enum_field in their range.
660 @returns @enumftiter on the set of mappings of the field
661 type of \p enum_field which contain the current
662 integral value of \p enum_field in their range,
663 or \c NULL if no mappings were found or on
666 @prenotnull{enum_field}
667 @preisenumfield{enum_field}
668 @pre The wrapped integer field of \p enum_field contains an integral
670 @postrefcountsame{enum_field}
671 @postsuccessrefcountret1
672 @post <strong>On success</strong>, the returned @enumftiter can iterate
673 on at least one mapping.
675 extern struct bt_ctf_field_type_enumeration_mapping_iterator
*
676 bt_ctf_field_enumeration_get_mappings(struct bt_ctf_field
*enum_field
);
681 @defgroup ctfirstringfield CTF IR string field
683 @brief CTF IR string field.
686 #include <babeltrace/ctf-ir/fields.h>
689 A CTF IR <strong><em>string field</em></strong> is a @field which holds
690 a string value, and which is described by a @stringft.
692 Use bt_ctf_field_string_set_value() to set the current string value
693 of a string field object. You can also use bt_ctf_field_string_append()
694 and bt_ctf_field_string_append_len() to append a string to the current
695 value of a string field.
697 After you create a string field with bt_ctf_field_create(), you
698 \em must set a string value with
699 bt_ctf_field_string_set_value(), bt_ctf_field_string_append(), or
700 bt_ctf_field_string_append_len() before you can get the
701 field's value with bt_ctf_field_string_get_value().
703 @sa ctfirstringfieldtype
706 @addtogroup ctfirstringfield
711 @brief Returns the string value of the @stringfield \p string_field.
713 On success, \p string_field remains the sole owner of the returned
716 @param[in] string_field String field field of which to get the
718 @returns String value, or \c NULL on error.
720 @prenotnull{string_field}
722 @preisstringfield{string_field}
723 @pre \p string_field contains a string value previously
724 set with bt_ctf_field_string_set_value(),
725 bt_ctf_field_string_append(), or
726 bt_ctf_field_string_append_len().
727 @postrefcountsame{string_field}
729 @sa bt_ctf_field_string_set_value(): Sets the string value of a given
732 extern const char *bt_ctf_field_string_get_value(
733 struct bt_ctf_field
*string_field
);
736 @brief Sets the string value of the @stringfield \p string_field to
739 @param[in] string_field String field of which to set
741 @param[in] value New string value of \p string_field (copied
743 @returns 0 on success, or a negative value on error.
745 @prenotnull{string_field}
747 @preisstringfield{string_field}
748 @prehot{string_field}
749 @postrefcountsame{string_field}
751 @sa bt_ctf_field_string_get_value(): Returns the string value of a
754 extern int bt_ctf_field_string_set_value(struct bt_ctf_field
*string_field
,
758 @brief Appends the string \p value to the current string value of
759 the @stringfield \p string_field.
761 This function is the equivalent of:
764 bt_ctf_field_string_append_len(string_field, value, strlen(value));
767 @param[in] string_field String field of which to append \p value to
769 @param[in] value String to append to the current string value
770 of \p string_field (copied on success).
771 @returns 0 on success, or a negative value on error.
773 @prenotnull{string_field}
775 @preisstringfield{string_field}
776 @prehot{string_field}
777 @postrefcountsame{string_field}
779 @sa bt_ctf_field_string_set_value(): Sets the string value of a given
782 extern int bt_ctf_field_string_append(struct bt_ctf_field
*string_field
,
786 @brief Appends the first \p length characters of \p value to the
787 current string value of the @stringfield \p string_field.
789 If \p string_field has no current string value, this function first
790 sets an empty string as the string value of \p string_field and then
791 appends the first \p length characters of \p value.
793 @param[in] string_field String field of which to append the first
794 \p length characters of \p value to
796 @param[in] value String containing the characters to append to
797 the current string value of \p string_field
799 @param[in] length Number of characters of \p value to append to
800 the current string value of \p string_field.
801 @returns 0 on success, or a negative value on error.
803 @prenotnull{string_field}
805 @preisstringfield{string_field}
806 @prehot{string_field}
807 @postrefcountsame{string_field}
809 @sa bt_ctf_field_string_set_value(): Sets the string value of a given
812 extern int bt_ctf_field_string_append_len(
813 struct bt_ctf_field
*string_field
, const char *value
,
814 unsigned int length
);
819 @defgroup ctfirstructfield CTF IR structure field
821 @brief CTF IR structure field.
824 #include <babeltrace/ctf-ir/fields.h>
827 A CTF IR <strong><em>structure field</em></strong> is a @field which
828 contains an ordered list of zero or more named @fields which can be
829 different @fts, and which is described by a @structft.
831 To set the value of a specific field of a structure field, you need to
832 first get the field with bt_ctf_field_structure_get_field_by_name() or
833 bt_ctf_field_structure_get_field_by_index(). If you already have a
834 field object, you can assign it to a specific name within a structure
835 field with bt_ctf_field_structure_set_field_by_name().
837 @sa ctfirstructfieldtype
840 @addtogroup ctfirstructfield
845 @brief Returns the @field named \p name, potentially creating it,
846 in the @structfield \p struct_field.
848 This function creates the @field to return if it does not currently
851 @param[in] struct_field Structure field of which to get the field
853 @param[in] name Name of the field to get from \p struct_field.
854 @returns Field named \p name in \p struct_field, or
857 @prenotnull{struct_field}
859 @preisstructfield{struct_field}
860 @postrefcountsame{struct_field}
861 @postsuccessrefcountretinc
863 @sa bt_ctf_field_structure_get_field_by_index(): Returns the field of a
864 given structure field by index.
865 @sa bt_ctf_field_structure_set_field_by_name(): Sets the field of a
866 given structure field by name.
868 extern struct bt_ctf_field
*bt_ctf_field_structure_get_field_by_name(
869 struct bt_ctf_field
*struct_field
, const char *name
);
871 /* Pre-2.0 CTF writer compatibility */
872 #define bt_ctf_field_structure_get_field bt_ctf_field_structure_get_field_by_name
875 @brief Returns the @field at index \p index in the @structfield
878 @param[in] struct_field Structure field of which to get the field
880 @param[in] index Index of the field to get in \p struct_field.
881 @returns Field at index \p index in \p struct_field, or
884 @prenotnull{struct_field}
885 @preisstructfield{struct_field}
886 @pre \p index is lesser than the number of fields contained in the
887 parent field type of \p struct_field (see
888 bt_ctf_field_type_structure_get_field_count()).
889 @postrefcountsame{struct_field}
890 @postsuccessrefcountretinc
892 @sa bt_ctf_field_structure_get_field_by_name(): Returns the field of a
893 given structure field by name.
894 @sa bt_ctf_field_structure_set_field_by_name(): Sets the field of a
895 given structure field by name.
897 extern struct bt_ctf_field
*bt_ctf_field_structure_get_field_by_index(
898 struct bt_ctf_field
*struct_field
, uint64_t index
);
901 @brief Sets the field of the @structfield \p struct_field named \p name
902 to the @field \p field.
904 If \p struct_field already contains a field named \p name, then its
905 reference count is decremented, and \p field replaces it.
907 The field type of \p field, as returned by bt_ctf_field_get_type(),
908 \em must be equivalent to the field type returned by
909 bt_ctf_field_type_structure_get_field_type_by_name() with the field
910 type of \p struct_field and the same name, \p name.
912 bt_ctf_trace_get_packet_header_type() for the parent trace class of
915 @param[in] struct_field Structure field of which to set the field
917 @param[in] name Name of the field to set in \p struct_field.
918 @param[in] field Field named \p name to set in \p struct_field.
919 @returns 0 on success, or -1 on error.
921 @prenotnull{struct_field}
924 @prehot{struct_field}
925 @preisstructfield{struct_field}
926 @pre \p field has a field type equivalent to the field type returned by
927 bt_ctf_field_type_structure_get_field_type_by_name() for the
928 field type of \p struct_field with the name \p name.
929 @postrefcountsame{struct_field}
930 @post <strong>On success, if there's an existing field in
931 \p struct_field named \p name</strong>, its reference count is
933 @postsuccessrefcountinc{field}
935 @sa bt_ctf_field_structure_get_field_by_index(): Returns the field of a
936 given structure field by index.
937 @sa bt_ctf_field_structure_get_field_by_name(): Returns the field of a
938 given structure field by name.
940 extern int bt_ctf_field_structure_set_field_by_name(
941 struct bt_ctf_field
*struct_field
,
942 const char *name
, struct bt_ctf_field
*field
);
947 @defgroup ctfirarrayfield CTF IR array field
949 @brief CTF IR array field.
952 #include <babeltrace/ctf-ir/fields.h>
955 A CTF IR <strong><em>array field</em></strong> is a @field which
956 contains an ordered list of zero or more @fields sharing the same @ft,
957 and which is described by a @arrayft.
959 To set the value of a specific field of an array field, you need to
960 first get the field with bt_ctf_field_array_get_field().
962 @sa ctfirarrayfieldtype
965 @addtogroup ctfirarrayfield
970 @brief Returns the @field at index \p index, potentially creating it,
971 in the @arrayfield \p array_field.
973 This function creates the @field to return if it does not currently
976 @param[in] array_field Array field of which to get the field
978 @param[in] index Index of the field to get in \p array_field.
979 @returns Field at index \p index in \p array_field, or
982 @prenotnull{array_field}
983 @preisarrayfield{array_field}
984 @pre \p index is lesser than bt_ctf_field_type_array_get_length() called
985 on the field type of \p array_field.
986 @postrefcountsame{array_field}
987 @postsuccessrefcountretinc
989 extern struct bt_ctf_field
*bt_ctf_field_array_get_field(
990 struct bt_ctf_field
*array_field
, uint64_t index
);
995 @defgroup ctfirseqfield CTF IR sequence field
997 @brief CTF IR sequence field.
1000 #include <babeltrace/ctf-ir/fields.h>
1003 A CTF IR <strong><em>sequence field</em></strong> is a @field which
1004 contains an ordered list of zero or more @fields sharing the same @ft,
1005 and which is described by a @seqft.
1007 Before you can get a specific field of a sequence field with
1008 bt_ctf_field_sequence_get_field(), you need to set its current length
1009 @intfield with bt_ctf_field_sequence_set_length(). The integral value of
1010 the length field of a sequence field indicates the number of fields
1013 @sa ctfirseqfieldtype
1016 @addtogroup ctfirseqfield
1021 @brief Returns the @field at index \p index, potentially creating it,
1022 in the @seqfield \p sequence_field.
1024 This function creates the @field to return if it does not currently
1027 @param[in] sequence_field Sequence field of which to get the field
1029 @param[in] index Index of the field to get in
1031 @returns Field at index \p index in
1032 \p sequence_field, or \c NULL on error.
1034 @prenotnull{sequence_field}
1035 @preisseqfield{sequence_field}
1036 @pre \p sequence_field has a length field previously set with
1037 bt_ctf_field_sequence_set_length().
1038 @pre \p index is lesser than the current integral value of the current
1039 length field of \p sequence_field (see
1040 bt_ctf_field_sequence_get_length()).
1041 @postrefcountsame{sequence_field}
1042 @postsuccessrefcountretinc
1044 extern struct bt_ctf_field
*bt_ctf_field_sequence_get_field(
1045 struct bt_ctf_field
*sequence_field
, uint64_t index
);
1048 @brief Returns the length @intfield of the @seqfield \p sequence_field.
1050 The current integral value of the returned length field indicates the
1051 number of fields contained in \p sequence_field.
1053 @param[in] sequence_field Sequence field of which to get the
1055 @returns Length field of \p sequence_field, or
1058 @prenotnull{sequence_field}
1059 @preisseqfield{sequence_field}
1060 @pre \p sequence_field has a length field previously set with
1061 bt_ctf_field_sequence_set_length().
1062 @postrefcountsame{sequence_field}
1063 @postsuccessrefcountretinc
1064 @post <strong>On success</strong>, the returned field is a @intfield.
1066 @sa bt_ctf_field_sequence_set_length(): Sets the length field of a given
1069 extern struct bt_ctf_field
*bt_ctf_field_sequence_get_length(
1070 struct bt_ctf_field
*sequence_field
);
1073 @brief Sets the length @intfield of the @seqfield \p sequence_field
1076 The current integral value of \p length_field indicates the number of
1077 fields contained in \p sequence_field.
1079 @param[in] sequence_field Sequence field of which to set the
1081 @param[in] length_field Length field of \p sequence_field.
1082 @returns 0 on success, or a negative value on error.
1084 @prenotnull{sequence_field}
1085 @prenotnull{length_field}
1086 @preisseqfield{sequence_field}
1087 @preisintfield{length_field}
1088 @prehot{sequence_field}
1089 @postrefcountsame{sequence_field}
1090 @postsuccessrefcountinc{length_field}
1092 @sa bt_ctf_field_sequence_get_length(): Returns the length field of a
1093 given sequence field.
1095 extern int bt_ctf_field_sequence_set_length(struct bt_ctf_field
*sequence_field
,
1096 struct bt_ctf_field
*length_field
);
1101 @defgroup ctfirvarfield CTF IR variant field
1102 @ingroup ctfirfields
1103 @brief CTF IR variant field.
1106 #include <babeltrace/ctf-ir/fields.h>
1109 A CTF IR <strong><em>variant field</em></strong> is a @field which
1110 contains a current @field amongst one or more choices, and which is
1111 described by a @varft.
1113 Use bt_ctf_field_variant_get_field() to get the @field selected by
1114 a specific tag @enumfield. Once you call this function, you can call
1115 bt_ctf_field_variant_get_current_field() afterwards to get this last
1118 @sa ctfirvarfieldtype
1121 @addtogroup ctfirvarfield
1126 @brief Returns the @field, potentially creating it, selected by the
1127 tag @intfield \p tag_field in the @varfield \p variant_field.
1129 This function creates the @field to return if it does not currently
1132 Once you call this function, you can call
1133 bt_ctf_field_variant_get_current_field() to get the same field again,
1134 and you can call bt_ctf_field_variant_get_tag() to get \p tag_field.
1136 @param[in] variant_field Variant field of which to get the field
1137 selected by \p tag_field.
1138 @param[in] tag_field Tag field.
1139 @returns Field selected by \p tag_field in
1140 \p variant_field, or \c NULL on error.
1142 @prenotnull{variant_field}
1143 @prenotnull{tag_field}
1144 @preisvarfield{variant_field}
1145 @preisenumfield{tag_field}
1146 @postrefcountsame{variant_field}
1147 @postsuccessrefcountinc{tag_field}
1148 @postsuccessrefcountretinc
1150 extern struct bt_ctf_field
*bt_ctf_field_variant_get_field(
1151 struct bt_ctf_field
*variant_field
,
1152 struct bt_ctf_field
*tag_field
);
1155 @brief Returns the currently selected @field of the @varfield
1158 @param[in] variant_field Variant field of which to get the
1159 currently selected field.
1160 @returns Currently selected field of
1161 \p variant_field, or \c NULL if there's
1162 no selected field or on error.
1164 @prenotnull{variant_field}
1165 @preisvarfield{variant_field}
1166 @pre \p variant_field contains has a current selected field previously
1167 set with bt_ctf_field_variant_get_field().
1168 @postrefcountsame{variant_field}
1169 @postsuccessrefcountretinc
1171 extern struct bt_ctf_field
*bt_ctf_field_variant_get_current_field(
1172 struct bt_ctf_field
*variant_field
);
1175 @brief Returns the tag @enumfield of the @varfield \p variant_field.
1177 @param[in] variant_field Variant field of which to get the
1179 @returns Tag field of \p variant_field, or
1182 @prenotnull{variant_field}
1183 @preisvarfield{variant_field}
1184 @pre \p variant_field contains has a current selected field previously
1185 set with bt_ctf_field_variant_get_field().
1186 @postrefcountsame{variant_field}
1187 @postsuccessrefcountretinc
1188 @post <strong>On success</strong>, the returned field is a @enumfield.
1190 extern struct bt_ctf_field
*bt_ctf_field_variant_get_tag(
1191 struct bt_ctf_field
*variant_field
);
1199 #endif /* BABELTRACE_CTF_IR_FIELDS_H */