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>
43 struct bt_ctf_field_type
;
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_ctf_packet_set_header().
61 - Stream packet context field: bt_ctf_packet_set_context().
63 - Stream event header field: bt_ctf_event_set_header().
64 - Stream event context field: bt_ctf_event_set_stream_event_context().
65 - Event context field: bt_ctf_event_set_event_context().
66 - Event payload field: bt_ctf_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_ctf_field_create(). The enumeration and compound fields create their
87 contained fields with the following getters if such fields do not exist
90 - bt_ctf_field_enumeration_get_container()
91 - bt_ctf_field_structure_get_field_by_name()
92 - bt_ctf_field_array_get_field()
93 - bt_ctf_field_sequence_get_field()
94 - bt_ctf_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_ctf_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_ctf_field_get_type(). You can get the
102 \link #bt_ctf_field_type_id type ID\endlink of this field type directly with
103 bt_ctf_field_get_type_id().
105 You can get a deep copy of a field with bt_ctf_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_ctf_event_class
;
137 struct bt_ctf_field_type
;
138 struct bt_ctf_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_ctf_field
*bt_ctf_field_create(
164 struct bt_ctf_field_type
*field_type
);
167 @brief Returns the parent @ft of the @field \p field.
169 This function returns a reference to the field type which was used to
170 create the field object in the first place with bt_ctf_field_create().
172 @param[in] field Field of which to get the parent field type.
173 @returns Parent field type of \p event,
177 @postrefcountsame{field}
178 @postsuccessrefcountretinc
180 extern struct bt_ctf_field_type
*bt_ctf_field_get_type(
181 struct bt_ctf_field
*field
);
186 @name Type information
191 @brief Returns the type ID of the @ft of the @field \p field.
193 @param[in] field Field of which to get the type ID of its
195 @returns Type ID of the parent field type of \p field,
196 or #BT_CTF_FIELD_TYPE_ID_UNKNOWN on error.
199 @postrefcountsame{field}
201 @sa #bt_ctf_field_type_id: CTF IR field type ID.
202 @sa bt_ctf_field_is_integer(): Returns whether or not a given field is a
204 @sa bt_ctf_field_is_floating_point(): Returns whether or not a given
205 field is a @floatfield.
206 @sa bt_ctf_field_is_enumeration(): Returns whether or not a given field
208 @sa bt_ctf_field_is_string(): Returns whether or not a given field is a
210 @sa bt_ctf_field_is_structure(): Returns whether or not a given field is
212 @sa bt_ctf_field_is_array(): Returns whether or not a given field is a
214 @sa bt_ctf_field_is_sequence(): Returns whether or not a given field is
216 @sa bt_ctf_field_is_variant(): Returns whether or not a given field is a
219 extern enum bt_ctf_field_type_id
bt_ctf_field_get_type_id(struct bt_ctf_field
*field
);
222 * bt_ctf_field_signed_integer_get_value: get a signed integer field's value
224 * Get a signed integer field's value.
226 * @param integer Signed integer field instance.
227 * @param value Pointer to a signed integer where the value will be stored.
229 * Returns 0 on success, a negative value on error.
231 extern int bt_ctf_field_signed_integer_get_value(struct bt_ctf_field
*integer
,
235 @brief Returns whether or not the @field \p field is a @intfield.
237 @param[in] field Field to check (can be \c NULL).
238 @returns #BT_TRUE if \p field is an integer field, or
239 #BT_FALSE otherwise (including if \p field is
243 @postrefcountsame{field}
245 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
248 extern bt_bool
bt_ctf_field_is_integer(struct bt_ctf_field
*field
);
251 @brief Returns whether or not the @field \p field is a @floatfield.
253 @param[in] field Field to check (can be \c NULL).
254 @returns #BT_TRUE if \p field is a floating point number fiel
255 #BT_FALSE or 0 otherwise (including if \p field is
259 @postrefcountsame{field}
261 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
264 extern bt_bool
bt_ctf_field_is_floating_point(struct bt_ctf_field
*field
);
267 @brief Returns whether or not the @field \p field is a @enumfield.
269 @param[in] field Field to check (can be \c NULL).
270 @returns #BT_TRUE if \p field is an enumeration field, or
271 #BT_FALSE otherwise (including if \p field is
275 @postrefcountsame{field}
277 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
280 extern bt_bool
bt_ctf_field_is_enumeration(struct bt_ctf_field
*field
);
283 @brief Returns whether or not the @field \p field is a @stringfield.
285 @param[in] field Field to check (can be \c NULL).
286 @returns #BT_TRUE if \p field is a string field, or
287 #BT_FALSE otherwise (including if \p field is
291 @postrefcountsame{field}
293 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
296 extern bt_bool
bt_ctf_field_is_string(struct bt_ctf_field
*field
);
299 @brief Returns whether or not the @field \p field is a @structfield.
301 @param[in] field Field to check (can be \c NULL).
302 @returns #BT_TRUE if \p field is a structure field, or
303 #BT_FALSE otherwise (including if \p field is
307 @postrefcountsame{field}
309 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
312 extern bt_bool
bt_ctf_field_is_structure(struct bt_ctf_field
*field
);
315 @brief Returns whether or not the @field \p field is a @arrayfield.
317 @param[in] field Field to check (can be \c NULL).
318 @returns #BT_TRUE if \p field is an array field, or
319 #BT_FALSE otherwise (including if \p field is
323 @postrefcountsame{field}
325 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
328 extern bt_bool
bt_ctf_field_is_array(struct bt_ctf_field
*field
);
331 @brief Returns whether or not the @field \p field is a @seqfield.
333 @param[in] field Field to check (can be \c NULL).
334 @returns #BT_TRUE if \p field is a sequence field, or
335 #BT_FALSE otherwise (including if \p field is
339 @postrefcountsame{field}
341 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
344 extern bt_bool
bt_ctf_field_is_sequence(struct bt_ctf_field
*field
);
347 @brief Returns whether or not the @field \p field is a @varfield.
349 @param[in] field Field to check (can be \c NULL).
350 @returns #BT_TRUE if \p field is a variant field, or
351 #BT_FALSE otherwise (including if \p field is
355 @postrefcountsame{field}
357 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
360 extern bt_bool
bt_ctf_field_is_variant(struct bt_ctf_field
*field
);
365 @name Misc. functions
370 @brief Creates a \em deep copy of the @field \p field.
372 You can copy a frozen field: the resulting copy is <em>not frozen</em>.
374 @param[in] field Field to copy.
375 @returns Deep copy of \p field on success,
379 @postrefcountsame{field}
380 @postsuccessrefcountret1
381 @post <strong>On success</strong>, the returned field is not frozen.
383 extern struct bt_ctf_field
*bt_ctf_field_copy(struct bt_ctf_field
*field
);
390 @defgroup ctfirintfield CTF IR integer field
392 @brief CTF IR integer field.
395 #include <babeltrace/ctf-ir/fields.h>
398 A CTF IR <strong><em>integer field</em></strong> is a @field which
399 holds a signed or unsigned integral value, and which is described by
402 An integer field object is considered \em unsigned if
403 bt_ctf_field_type_integer_get_signed() on its parent field type returns
404 0. Otherwise it is considered \em signed. You \em must use
405 bt_ctf_field_unsigned_integer_get_value() and
406 bt_ctf_field_unsigned_integer_set_value() with an unsigned integer
407 field, and bt_ctf_field_signed_integer_get_value() and
408 bt_ctf_field_signed_integer_set_value() with a signed integer field.
410 After you create an integer field with bt_ctf_field_create(), you
411 \em must set an integral value with
412 bt_ctf_field_unsigned_integer_set_value() or
413 bt_ctf_field_signed_integer_set_value() before you can get the
414 field's value with bt_ctf_field_unsigned_integer_get_value() or
415 bt_ctf_field_signed_integer_get_value().
417 @sa ctfirintfieldtype
420 @addtogroup ctfirintfield
425 @brief Returns the signed integral value of the @intfield
428 @param[in] integer_field Integer field of which to get the
429 signed integral value.
430 @param[out] value Returned signed integral value of
432 @returns 0 on success, or a negative value on
433 error, including if \p integer_field
434 has no integral value yet.
436 @prenotnull{integer_field}
438 @preisintfield{integer_field}
439 @pre bt_ctf_field_type_integer_get_signed() returns 1 for the parent
440 @ft of \p integer_field.
441 @pre \p integer_field contains a signed integral value previously
442 set with bt_ctf_field_signed_integer_set_value().
443 @postrefcountsame{integer_field}
445 @sa bt_ctf_field_signed_integer_set_value(): Sets the signed integral
446 value of a given integer field.
448 extern int bt_ctf_field_signed_integer_get_value(
449 struct bt_ctf_field
*integer_field
, int64_t *value
);
452 @brief Sets the signed integral value of the @intfield
453 \p integer_field to \p value.
455 @param[in] integer_field Integer field of which to set
456 the signed integral value.
457 @param[in] value New signed integral value of
459 @returns 0 on success, or a negative value on error.
461 @prenotnull{integer_field}
462 @preisintfield{integer_field}
463 @prehot{integer_field}
464 @pre bt_ctf_field_type_integer_get_signed() returns 1 for the parent
465 @ft of \p integer_field.
466 @postrefcountsame{integer_field}
468 @sa bt_ctf_field_signed_integer_get_value(): Returns the signed integral
469 value of a given integer field.
471 extern int bt_ctf_field_signed_integer_set_value(
472 struct bt_ctf_field
*integer_field
, int64_t value
);
475 @brief Returns the unsigned integral value of the @intfield
478 @param[in] integer_field Integer field of which to get the
479 unsigned integral value.
480 @param[out] value Returned unsigned integral value of
482 @returns 0 on success, or a negative value on
483 error, including if \p integer_field
484 has no integral value yet.
486 @prenotnull{integer_field}
488 @preisintfield{integer_field}
489 @pre bt_ctf_field_type_integer_get_signed() returns 0 for the parent
490 @ft of \p integer_field.
491 @pre \p integer_field contains an unsigned integral value previously
492 set with bt_ctf_field_unsigned_integer_set_value().
493 @postrefcountsame{integer_field}
495 @sa bt_ctf_field_unsigned_integer_set_value(): Sets the unsigned
496 integral value of a given integer field.
498 extern int bt_ctf_field_unsigned_integer_get_value(
499 struct bt_ctf_field
*integer_field
, uint64_t *value
);
502 @brief Sets the unsigned integral value of the @intfield
503 \p integer_field to \p value.
505 @param[in] integer_field Integer field of which to set
506 the unsigned integral value.
507 @param[in] value New unsigned integral value of
509 @returns 0 on success, or a negative value on error.
511 @prenotnull{integer_field}
512 @preisintfield{integer_field}
513 @prehot{integer_field}
514 @pre bt_ctf_field_type_integer_get_signed() returns 0 for the parent
515 @ft of \p integer_field.
516 @postrefcountsame{integer_field}
518 @sa bt_ctf_field_unsigned_integer_get_value(): Returns the unsigned
519 integral value of a given integer field.
521 extern int bt_ctf_field_unsigned_integer_set_value(
522 struct bt_ctf_field
*integer_field
, uint64_t value
);
527 @defgroup ctfirfloatfield CTF IR floating point number field
529 @brief CTF IR floating point number field.
532 #include <babeltrace/ctf-ir/fields.h>
535 A CTF IR <strong><em>floating point number field</em></strong> is a
536 @field which holds a floating point number value, and which is
537 described by a @floatft.
539 After you create a floating point number field with bt_ctf_field_create(), you
540 \em must set a floating point number value with
541 bt_ctf_field_floating_point_set_value() before you can get the
542 field's value with bt_ctf_field_floating_point_get_value().
544 @sa ctfirfloatfieldtype
547 @addtogroup ctfirfloatfield
552 @brief Returns the floating point number value of the @floatfield
555 @param[in] float_field Floating point number field of which to get the
556 floating point number value.
557 @param[out] value Returned floating point number value of
559 @returns 0 on success, or a negative value on error,
560 including if \p float_field has no floating
561 point number value yet.
563 @prenotnull{float_field}
565 @preisfloatfield{float_field}
566 @pre \p float_field contains a floating point number value previously
567 set with bt_ctf_field_floating_point_set_value().
568 @postrefcountsame{float_field}
570 @sa bt_ctf_field_floating_point_set_value(): Sets the floating point
571 number value of a given floating point number field.
573 extern int bt_ctf_field_floating_point_get_value(
574 struct bt_ctf_field
*float_field
, double *value
);
577 @brief Sets the floating point number value of the @floatfield
578 \p float_field to \p value.
580 @param[in] float_field Floating point number field of which to set
581 the floating point number value.
582 @param[in] value New floating point number value of
584 @returns 0 on success, or a negative value on error.
586 @prenotnull{float_field}
587 @preisfloatfield{float_field}
589 @postrefcountsame{float_field}
591 @sa bt_ctf_field_floating_point_get_value(): Returns the floating point
592 number value of a given floating point number field.
594 extern int bt_ctf_field_floating_point_set_value(
595 struct bt_ctf_field
*float_field
,
601 @defgroup ctfirenumfield CTF IR enumeration field
603 @brief CTF IR enumeration field.
606 #include <babeltrace/ctf-ir/fields.h>
609 A CTF IR <strong><em>enumeration field</em></strong> is a @field which
610 holds a @intfield, and which is described by a @enumft.
612 To set the current integral value of an enumeration field, you need to
613 get its wrapped @intfield with bt_ctf_field_enumeration_get_container(),
614 and then set the integral value with either
615 bt_ctf_field_signed_integer_set_value() or
616 bt_ctf_field_unsigned_integer_set_value().
618 Once you set the integral value of an enumeration field by following the
619 previous paragraph, you can get the mappings containing this value in
620 their range with bt_ctf_field_enumeration_get_mappings(). This function
621 returns a @enumftiter.
623 @sa ctfirenumfieldtype
626 @addtogroup ctfirenumfield
631 @brief Returns the @intfield, potentially creating it, wrapped by the
632 @enumfield \p enum_field.
634 This function creates the @intfield to return if it does not currently
637 @param[in] enum_field Enumeration field of which to get the wrapped
639 @returns Integer field wrapped by \p enum_field, or
642 @prenotnull{enum_field}
643 @preisenumfield{enum_field}
644 @postrefcountsame{enum_field}
645 @postsuccessrefcountretinc
647 extern struct bt_ctf_field
*bt_ctf_field_enumeration_get_container(
648 struct bt_ctf_field
*enum_field
);
651 @brief Returns a @enumftiter on all the mappings of the field type of
652 \p enum_field which contain the current integral value of the
653 @enumfield \p enum_field in their range.
655 This function is the equivalent of using
656 bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value() or
657 bt_ctf_field_type_enumeration_find_mappings_by_signed_value() with the
658 current integral value of \p enum_field.
660 @param[in] enum_field Enumeration field of which to get the mappings
661 containing the current integral value of \p
662 enum_field in their range.
663 @returns @enumftiter on the set of mappings of the field
664 type of \p enum_field which contain the current
665 integral value of \p enum_field in their range,
666 or \c NULL if no mappings were found or on
669 @prenotnull{enum_field}
670 @preisenumfield{enum_field}
671 @pre The wrapped integer field of \p enum_field contains an integral
673 @postrefcountsame{enum_field}
674 @postsuccessrefcountret1
675 @post <strong>On success</strong>, the returned @enumftiter can iterate
676 on at least one mapping.
678 extern struct bt_ctf_field_type_enumeration_mapping_iterator
*
679 bt_ctf_field_enumeration_get_mappings(struct bt_ctf_field
*enum_field
);
684 @defgroup ctfirstringfield CTF IR string field
686 @brief CTF IR string field.
689 #include <babeltrace/ctf-ir/fields.h>
692 A CTF IR <strong><em>string field</em></strong> is a @field which holds
693 a string value, and which is described by a @stringft.
695 Use bt_ctf_field_string_set_value() to set the current string value
696 of a string field object. You can also use bt_ctf_field_string_append()
697 and bt_ctf_field_string_append_len() to append a string to the current
698 value of a string field.
700 After you create a string field with bt_ctf_field_create(), you
701 \em must set a string value with
702 bt_ctf_field_string_set_value(), bt_ctf_field_string_append(), or
703 bt_ctf_field_string_append_len() before you can get the
704 field's value with bt_ctf_field_string_get_value().
706 @sa ctfirstringfieldtype
709 @addtogroup ctfirstringfield
714 @brief Returns the string value of the @stringfield \p string_field.
716 On success, \p string_field remains the sole owner of the returned
719 @param[in] string_field String field field of which to get the
721 @returns String value, or \c NULL on error.
723 @prenotnull{string_field}
725 @preisstringfield{string_field}
726 @pre \p string_field contains a string value previously
727 set with bt_ctf_field_string_set_value(),
728 bt_ctf_field_string_append(), or
729 bt_ctf_field_string_append_len().
730 @postrefcountsame{string_field}
732 @sa bt_ctf_field_string_set_value(): Sets the string value of a given
735 extern const char *bt_ctf_field_string_get_value(
736 struct bt_ctf_field
*string_field
);
739 @brief Sets the string value of the @stringfield \p string_field to
742 @param[in] string_field String field of which to set
744 @param[in] value New string value of \p string_field (copied
746 @returns 0 on success, or a negative value on error.
748 @prenotnull{string_field}
750 @preisstringfield{string_field}
751 @prehot{string_field}
752 @postrefcountsame{string_field}
754 @sa bt_ctf_field_string_get_value(): Returns the string value of a
757 extern int bt_ctf_field_string_set_value(struct bt_ctf_field
*string_field
,
761 @brief Appends the string \p value to the current string value of
762 the @stringfield \p string_field.
764 This function is the equivalent of:
767 bt_ctf_field_string_append_len(string_field, value, strlen(value));
770 @param[in] string_field String field of which to append \p value to
772 @param[in] value String to append to the current string value
773 of \p string_field (copied on success).
774 @returns 0 on success, or a negative value on error.
776 @prenotnull{string_field}
778 @preisstringfield{string_field}
779 @prehot{string_field}
780 @postrefcountsame{string_field}
782 @sa bt_ctf_field_string_set_value(): Sets the string value of a given
785 extern int bt_ctf_field_string_append(struct bt_ctf_field
*string_field
,
789 @brief Appends the first \p length characters of \p value to the
790 current string value of the @stringfield \p string_field.
792 If \p string_field has no current string value, this function first
793 sets an empty string as the string value of \p string_field and then
794 appends the first \p length characters of \p value.
796 @param[in] string_field String field of which to append the first
797 \p length characters of \p value to
799 @param[in] value String containing the characters to append to
800 the current string value of \p string_field
802 @param[in] length Number of characters of \p value to append to
803 the current string value of \p string_field.
804 @returns 0 on success, or a negative value on error.
806 @prenotnull{string_field}
808 @preisstringfield{string_field}
809 @prehot{string_field}
810 @postrefcountsame{string_field}
812 @sa bt_ctf_field_string_set_value(): Sets the string value of a given
815 extern int bt_ctf_field_string_append_len(
816 struct bt_ctf_field
*string_field
, const char *value
,
817 unsigned int length
);
822 @defgroup ctfirstructfield CTF IR structure field
824 @brief CTF IR structure field.
827 #include <babeltrace/ctf-ir/fields.h>
830 A CTF IR <strong><em>structure field</em></strong> is a @field which
831 contains an ordered list of zero or more named @fields which can be
832 different @fts, and which is described by a @structft.
834 To set the value of a specific field of a structure field, you need to
835 first get the field with bt_ctf_field_structure_get_field_by_name() or
836 bt_ctf_field_structure_get_field_by_index(). If you already have a
837 field object, you can assign it to a specific name within a structure
838 field with bt_ctf_field_structure_set_field_by_name().
840 @sa ctfirstructfieldtype
843 @addtogroup ctfirstructfield
848 @brief Returns the @field named \p name, potentially creating it,
849 in the @structfield \p struct_field.
851 This function creates the @field to return if it does not currently
854 @param[in] struct_field Structure field of which to get the field
856 @param[in] name Name of the field to get from \p struct_field.
857 @returns Field named \p name in \p struct_field, or
860 @prenotnull{struct_field}
862 @preisstructfield{struct_field}
863 @postrefcountsame{struct_field}
864 @postsuccessrefcountretinc
866 @sa bt_ctf_field_structure_get_field_by_index(): Returns the field of a
867 given structure field by index.
868 @sa bt_ctf_field_structure_set_field_by_name(): Sets the field of a
869 given structure field by name.
871 extern struct bt_ctf_field
*bt_ctf_field_structure_get_field_by_name(
872 struct bt_ctf_field
*struct_field
, const char *name
);
874 /* Pre-2.0 CTF writer compatibility */
875 #define bt_ctf_field_structure_get_field bt_ctf_field_structure_get_field_by_name
878 @brief Returns the @field at index \p index in the @structfield
881 @param[in] struct_field Structure field of which to get the field
883 @param[in] index Index of the field to get in \p struct_field.
884 @returns Field at index \p index in \p struct_field, or
887 @prenotnull{struct_field}
888 @preisstructfield{struct_field}
889 @pre \p index is lesser than the number of fields contained in the
890 parent field type of \p struct_field (see
891 bt_ctf_field_type_structure_get_field_count()).
892 @postrefcountsame{struct_field}
893 @postsuccessrefcountretinc
895 @sa bt_ctf_field_structure_get_field_by_name(): Returns the field of a
896 given structure field by name.
897 @sa bt_ctf_field_structure_set_field_by_name(): Sets the field of a
898 given structure field by name.
900 extern struct bt_ctf_field
*bt_ctf_field_structure_get_field_by_index(
901 struct bt_ctf_field
*struct_field
, uint64_t index
);
904 @brief Sets the field of the @structfield \p struct_field named \p name
905 to the @field \p field.
907 If \p struct_field already contains a field named \p name, then its
908 reference count is decremented, and \p field replaces it.
910 The field type of \p field, as returned by bt_ctf_field_get_type(),
911 \em must be equivalent to the field type returned by
912 bt_ctf_field_type_structure_get_field_type_by_name() with the field
913 type of \p struct_field and the same name, \p name.
915 bt_ctf_trace_get_packet_header_type() for the parent trace class of
918 @param[in] struct_field Structure field of which to set the field
920 @param[in] name Name of the field to set in \p struct_field.
921 @param[in] field Field named \p name to set in \p struct_field.
922 @returns 0 on success, or -1 on error.
924 @prenotnull{struct_field}
927 @prehot{struct_field}
928 @preisstructfield{struct_field}
929 @pre \p field has a field type equivalent to the field type returned by
930 bt_ctf_field_type_structure_get_field_type_by_name() for the
931 field type of \p struct_field with the name \p name.
932 @postrefcountsame{struct_field}
933 @post <strong>On success, if there's an existing field in
934 \p struct_field named \p name</strong>, its reference count is
936 @postsuccessrefcountinc{field}
938 @sa bt_ctf_field_structure_get_field_by_index(): Returns the field of a
939 given structure field by index.
940 @sa bt_ctf_field_structure_get_field_by_name(): Returns the field of a
941 given structure field by name.
943 extern int bt_ctf_field_structure_set_field_by_name(
944 struct bt_ctf_field
*struct_field
,
945 const char *name
, struct bt_ctf_field
*field
);
950 @defgroup ctfirarrayfield CTF IR array field
952 @brief CTF IR array field.
955 #include <babeltrace/ctf-ir/fields.h>
958 A CTF IR <strong><em>array field</em></strong> is a @field which
959 contains an ordered list of zero or more @fields sharing the same @ft,
960 and which is described by a @arrayft.
962 To set the value of a specific field of an array field, you need to
963 first get the field with bt_ctf_field_array_get_field().
965 @sa ctfirarrayfieldtype
968 @addtogroup ctfirarrayfield
973 @brief Returns the @field at index \p index, potentially creating it,
974 in the @arrayfield \p array_field.
976 This function creates the @field to return if it does not currently
979 @param[in] array_field Array field of which to get the field
981 @param[in] index Index of the field to get in \p array_field.
982 @returns Field at index \p index in \p array_field, or
985 @prenotnull{array_field}
986 @preisarrayfield{array_field}
987 @pre \p index is lesser than bt_ctf_field_type_array_get_length() called
988 on the field type of \p array_field.
989 @postrefcountsame{array_field}
990 @postsuccessrefcountretinc
992 extern struct bt_ctf_field
*bt_ctf_field_array_get_field(
993 struct bt_ctf_field
*array_field
, uint64_t index
);
998 @defgroup ctfirseqfield CTF IR sequence field
1000 @brief CTF IR sequence field.
1003 #include <babeltrace/ctf-ir/fields.h>
1006 A CTF IR <strong><em>sequence field</em></strong> is a @field which
1007 contains an ordered list of zero or more @fields sharing the same @ft,
1008 and which is described by a @seqft.
1010 Before you can get a specific field of a sequence field with
1011 bt_ctf_field_sequence_get_field(), you need to set its current length
1012 @intfield with bt_ctf_field_sequence_set_length(). The integral value of
1013 the length field of a sequence field indicates the number of fields
1016 @sa ctfirseqfieldtype
1019 @addtogroup ctfirseqfield
1024 @brief Returns the @field at index \p index, potentially creating it,
1025 in the @seqfield \p sequence_field.
1027 This function creates the @field to return if it does not currently
1030 @param[in] sequence_field Sequence field of which to get the field
1032 @param[in] index Index of the field to get in
1034 @returns Field at index \p index in
1035 \p sequence_field, or \c NULL on error.
1037 @prenotnull{sequence_field}
1038 @preisseqfield{sequence_field}
1039 @pre \p sequence_field has a length field previously set with
1040 bt_ctf_field_sequence_set_length().
1041 @pre \p index is lesser than the current integral value of the current
1042 length field of \p sequence_field (see
1043 bt_ctf_field_sequence_get_length()).
1044 @postrefcountsame{sequence_field}
1045 @postsuccessrefcountretinc
1047 extern struct bt_ctf_field
*bt_ctf_field_sequence_get_field(
1048 struct bt_ctf_field
*sequence_field
, uint64_t index
);
1051 @brief Returns the length @intfield of the @seqfield \p sequence_field.
1053 The current integral value of the returned length field indicates the
1054 number of fields contained in \p sequence_field.
1056 @param[in] sequence_field Sequence field of which to get the
1058 @returns Length field of \p sequence_field, or
1061 @prenotnull{sequence_field}
1062 @preisseqfield{sequence_field}
1063 @pre \p sequence_field has a length field previously set with
1064 bt_ctf_field_sequence_set_length().
1065 @postrefcountsame{sequence_field}
1066 @postsuccessrefcountretinc
1067 @post <strong>On success</strong>, the returned field is a @intfield.
1069 @sa bt_ctf_field_sequence_set_length(): Sets the length field of a given
1072 extern struct bt_ctf_field
*bt_ctf_field_sequence_get_length(
1073 struct bt_ctf_field
*sequence_field
);
1076 @brief Sets the length @intfield of the @seqfield \p sequence_field
1079 The current integral value of \p length_field indicates the number of
1080 fields contained in \p sequence_field.
1082 @param[in] sequence_field Sequence field of which to set the
1084 @param[in] length_field Length field of \p sequence_field.
1085 @returns 0 on success, or a negative value on error.
1087 @prenotnull{sequence_field}
1088 @prenotnull{length_field}
1089 @preisseqfield{sequence_field}
1090 @preisintfield{length_field}
1091 @prehot{sequence_field}
1092 @postrefcountsame{sequence_field}
1093 @postsuccessrefcountinc{length_field}
1095 @sa bt_ctf_field_sequence_get_length(): Returns the length field of a
1096 given sequence field.
1098 extern int bt_ctf_field_sequence_set_length(struct bt_ctf_field
*sequence_field
,
1099 struct bt_ctf_field
*length_field
);
1104 @defgroup ctfirvarfield CTF IR variant field
1105 @ingroup ctfirfields
1106 @brief CTF IR variant field.
1109 #include <babeltrace/ctf-ir/fields.h>
1112 A CTF IR <strong><em>variant field</em></strong> is a @field which
1113 contains a current @field amongst one or more choices, and which is
1114 described by a @varft.
1116 Use bt_ctf_field_variant_get_field() to get the @field selected by
1117 a specific tag @enumfield. Once you call this function, you can call
1118 bt_ctf_field_variant_get_current_field() afterwards to get this last
1121 @sa ctfirvarfieldtype
1124 @addtogroup ctfirvarfield
1129 @brief Returns the @field, potentially creating it, selected by the
1130 tag @intfield \p tag_field in the @varfield \p variant_field.
1132 This function creates the @field to return if it does not currently
1135 Once you call this function, you can call
1136 bt_ctf_field_variant_get_current_field() to get the same field again,
1137 and you can call bt_ctf_field_variant_get_tag() to get \p tag_field.
1139 @param[in] variant_field Variant field of which to get the field
1140 selected by \p tag_field.
1141 @param[in] tag_field Tag field.
1142 @returns Field selected by \p tag_field in
1143 \p variant_field, or \c NULL on error.
1145 @prenotnull{variant_field}
1146 @prenotnull{tag_field}
1147 @preisvarfield{variant_field}
1148 @preisenumfield{tag_field}
1149 @postrefcountsame{variant_field}
1150 @postsuccessrefcountinc{tag_field}
1151 @postsuccessrefcountretinc
1153 extern struct bt_ctf_field
*bt_ctf_field_variant_get_field(
1154 struct bt_ctf_field
*variant_field
,
1155 struct bt_ctf_field
*tag_field
);
1158 @brief Returns the currently selected @field of the @varfield
1161 @param[in] variant_field Variant field of which to get the
1162 currently selected field.
1163 @returns Currently selected field of
1164 \p variant_field, or \c NULL if there's
1165 no selected field or on error.
1167 @prenotnull{variant_field}
1168 @preisvarfield{variant_field}
1169 @pre \p variant_field contains has a current selected field previously
1170 set with bt_ctf_field_variant_get_field().
1171 @postrefcountsame{variant_field}
1172 @postsuccessrefcountretinc
1174 extern struct bt_ctf_field
*bt_ctf_field_variant_get_current_field(
1175 struct bt_ctf_field
*variant_field
);
1178 @brief Returns the tag @enumfield of the @varfield \p variant_field.
1180 @param[in] variant_field Variant field of which to get the
1182 @returns Tag field of \p variant_field, or
1185 @prenotnull{variant_field}
1186 @preisvarfield{variant_field}
1187 @pre \p variant_field contains has a current selected field previously
1188 set with bt_ctf_field_variant_get_field().
1189 @postrefcountsame{variant_field}
1190 @postsuccessrefcountretinc
1191 @post <strong>On success</strong>, the returned field is a @enumfield.
1193 extern struct bt_ctf_field
*bt_ctf_field_variant_get_tag(
1194 struct bt_ctf_field
*variant_field
);
1202 #endif /* BABELTRACE_CTF_IR_FIELDS_H */