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 You can get a reference to the @ft which was used to create a field with
92 bt_ctf_field_get_type(). You can get the
93 \link #bt_ctf_type_id type ID\endlink of this field type directly with
94 bt_ctf_field_get_type_id().
96 You can get a deep copy of a field with bt_ctf_field_copy(). The field
97 copy, and its contained field copies if it's the case, have the same
98 field type as the originals.
100 As with any Babeltrace object, CTF IR field objects have
101 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
102 counts</a>. See \ref refs to learn more about the reference counting
103 management of Babeltrace objects.
105 The functions which freeze CTF IR \link ctfirpacket packet\endlink and
106 \link ctfirevent event\endlink objects also freeze their root field
107 objects. You cannot modify a frozen field object: it is considered
108 immutable, except for \link refs reference counting\endlink.
113 @brief CTF IR fields type and functions.
116 @addtogroup ctfirfields
122 @brief A CTF IR field.
126 struct bt_ctf_event_class
;
128 struct bt_ctf_field_type
;
129 struct bt_ctf_field_type_enum_iter
;
132 @name Creation and parent field type access functions
137 @brief Creates an uninitialized @field described by the @ft
140 On success, \p field_type becomes the parent of the created field
143 On success, this function creates an \em uninitialized field: it has
144 no value. You need to set the value of the created field with one of the
145 its specific setters.
147 @param[in] field_type Field type which describes the field to create.
148 @returns Created field object, or \c NULL on error.
150 @prenotnull{field_type}
151 @postsuccessrefcountret1
152 @postsuccessfrozen{field_type}
154 extern struct bt_ctf_field
*bt_ctf_field_create(
155 struct bt_ctf_field_type
*field_type
);
158 @brief Returns the parent @ft of the @field \p field.
160 This function returns a reference to the field type which was used to
161 create the field object in the first place with bt_ctf_field_create().
163 @param[in] field Field of which to get the parent field type.
164 @returns Parent field type of \p event,
168 @postrefcountsame{field}
169 @postsuccessrefcountretinc
171 extern struct bt_ctf_field_type
*bt_ctf_field_get_type(
172 struct bt_ctf_field
*field
);
177 @name Type information
182 @brief Returns the type ID of the @ft of the @field \p field.
184 @param[in] field Field of which to get the type ID of its
186 @returns Type ID of the parent field type of \p field,
187 or #BT_CTF_TYPE_ID_UNKNOWN on error.
190 @postrefcountsame{field}
192 @sa #bt_ctf_type_id: CTF IR field type ID.
193 @sa bt_ctf_field_is_integer(): Returns whether or not a given field is a
195 @sa bt_ctf_field_is_floating_point(): Returns whether or not a given
196 field is a @floatfield.
197 @sa bt_ctf_field_is_enumeration(): Returns whether or not a given field
199 @sa bt_ctf_field_is_string(): Returns whether or not a given field is a
201 @sa bt_ctf_field_is_structure(): Returns whether or not a given field is
203 @sa bt_ctf_field_is_array(): Returns whether or not a given field is a
205 @sa bt_ctf_field_is_sequence(): Returns whether or not a given field is
207 @sa bt_ctf_field_is_variant(): Returns whether or not a given field is a
210 extern enum bt_ctf_type_id
bt_ctf_field_get_type_id(struct bt_ctf_field
*field
);
213 * bt_ctf_field_signed_integer_get_value: get a signed integer field's value
215 * Get a signed integer field's value.
217 * @param integer Signed integer field instance.
218 * @param value Pointer to a signed integer where the value will be stored.
220 * Returns 0 on success, a negative value on error.
222 extern int bt_ctf_field_signed_integer_get_value(struct bt_ctf_field
*integer
,
226 @brief Returns whether or not the @field \p field is a @intfield.
228 @param[in] field Field to check (can be \c NULL).
229 @returns 1 if \p field is an integer field, or 0
230 otherwise (including if \p field is
234 @postrefcountsame{field}
236 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
239 extern int bt_ctf_field_is_integer(struct bt_ctf_field
*field
);
242 @brief Returns whether or not the @field \p field is a @floatfield.
244 @param[in] field Field to check (can be \c NULL).
245 @returns 1 if \p field is a floating point number field,
246 or 0 otherwise (including if \p field is
250 @postrefcountsame{field}
252 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
255 extern int bt_ctf_field_is_floating_point(struct bt_ctf_field
*field
);
258 @brief Returns whether or not the @field \p field is a @enumfield.
260 @param[in] field Field to check (can be \c NULL).
261 @returns 1 if \p field is an enumeration field, or 0
262 otherwise (including if \p field is
266 @postrefcountsame{field}
268 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
271 extern int bt_ctf_field_is_enumeration(struct bt_ctf_field
*field
);
274 @brief Returns whether or not the @field \p field is a @stringfield.
276 @param[in] field Field to check (can be \c NULL).
277 @returns 1 if \p field is a string field, or 0
278 otherwise (including if \p field is
282 @postrefcountsame{field}
284 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
287 extern int bt_ctf_field_is_string(struct bt_ctf_field
*field
);
290 @brief Returns whether or not the @field \p field is a @structfield.
292 @param[in] field Field to check (can be \c NULL).
293 @returns 1 if \p field is a structure field, or 0
294 otherwise (including if \p field is
298 @postrefcountsame{field}
300 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
303 extern int bt_ctf_field_is_structure(struct bt_ctf_field
*field
);
306 @brief Returns whether or not the @field \p field is a @arrayfield.
308 @param[in] field Field to check (can be \c NULL).
309 @returns 1 if \p field is an array field, or 0
310 otherwise (including if \p field is
314 @postrefcountsame{field}
316 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
319 extern int bt_ctf_field_is_array(struct bt_ctf_field
*field
);
322 @brief Returns whether or not the @field \p field is a @seqfield.
324 @param[in] field Field to check (can be \c NULL).
325 @returns 1 if \p field is a sequence field, or 0
326 otherwise (including if \p field is
330 @postrefcountsame{field}
332 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
335 extern int bt_ctf_field_is_sequence(struct bt_ctf_field
*field
);
338 @brief Returns whether or not the @field \p field is a @varfield.
340 @param[in] field Field to check (can be \c NULL).
341 @returns 1 if \p field is a variant field, or 0
342 otherwise (including if \p field is
346 @postrefcountsame{field}
348 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
351 extern int bt_ctf_field_is_variant(struct bt_ctf_field
*field
);
356 @name Misc. functions
361 @brief Creates a \em deep copy of the @field \p field.
363 You can copy a frozen field: the resulting copy is <em>not frozen</em>.
365 @param[in] field Field to copy.
366 @returns Deep copy of \p field on success,
370 @postrefcountsame{field}
371 @postsuccessrefcountret1
372 @post <strong>On success</strong>, the returned field is not frozen.
374 extern struct bt_ctf_field
*bt_ctf_field_copy(struct bt_ctf_field
*field
);
381 @defgroup ctfirintfield CTF IR integer field
383 @brief CTF IR integer field.
386 #include <babeltrace/ctf-ir/fields.h>
389 A CTF IR <strong><em>integer field</em></strong> is a @field which
390 holds a signed or unsigned integral value, and which is described by
393 An integer field object is considered \em unsigned if
394 bt_ctf_field_type_integer_get_signed() on its parent field type returns
395 0. Otherwise it is considered \em signed. You \em must use
396 bt_ctf_field_unsigned_integer_get_value() and
397 bt_ctf_field_unsigned_integer_set_value() with an unsigned integer
398 field, and bt_ctf_field_signed_integer_get_value() and
399 bt_ctf_field_signed_integer_set_value() with a signed integer field.
401 After you create an integer field with bt_ctf_field_create(), you
402 \em must set an integral value with
403 bt_ctf_field_unsigned_integer_set_value() or
404 bt_ctf_field_signed_integer_set_value() before you can get the
405 field's value with bt_ctf_field_unsigned_integer_get_value() or
406 bt_ctf_field_signed_integer_get_value().
408 @sa ctfirintfieldtype
411 @addtogroup ctfirintfield
416 @brief Returns the signed integral value of the @intfield
419 @param[in] integer_field Integer field of which to get the
420 signed integral value.
421 @param[out] value Returned signed integral value of
423 @returns 0 on success, or a negative value on
424 error, including if \p integer_field
425 has no integral value yet.
427 @prenotnull{integer_field}
429 @preisintfield{integer_field}
430 @pre bt_ctf_field_type_integer_get_signed() returns 1 for the parent
431 @ft of \p integer_field.
432 @pre \p integer_field contains a signed integral value previously
433 set with bt_ctf_field_signed_integer_set_value().
434 @postrefcountsame{integer_field}
436 @sa bt_ctf_field_signed_integer_set_value(): Sets the signed integral
437 value of a given integer field.
439 extern int bt_ctf_field_signed_integer_get_value(
440 struct bt_ctf_field
*integer_field
, int64_t *value
);
443 @brief Sets the signed integral value of the @intfield
444 \p integer_field to \p value.
446 @param[in] integer_field Integer field of which to set
447 the signed integral value.
448 @param[in] value New signed integral value of
450 @returns 0 on success, or a negative value on error.
452 @prenotnull{integer_field}
453 @preisintfield{integer_field}
454 @prehot{integer_field}
455 @pre bt_ctf_field_type_integer_get_signed() returns 1 for the parent
456 @ft of \p integer_field.
457 @postrefcountsame{integer_field}
459 @sa bt_ctf_field_signed_integer_get_value(): Returns the signed integral
460 value of a given integer field.
462 extern int bt_ctf_field_signed_integer_set_value(
463 struct bt_ctf_field
*integer_field
, int64_t value
);
466 @brief Returns the unsigned integral value of the @intfield
469 @param[in] integer_field Integer field of which to get the
470 unsigned integral value.
471 @param[out] value Returned unsigned integral value of
473 @returns 0 on success, or a negative value on
474 error, including if \p integer_field
475 has no integral value yet.
477 @prenotnull{integer_field}
479 @preisintfield{integer_field}
480 @pre bt_ctf_field_type_integer_get_signed() returns 0 for the parent
481 @ft of \p integer_field.
482 @pre \p integer_field contains an unsigned integral value previously
483 set with bt_ctf_field_unsigned_integer_set_value().
484 @postrefcountsame{integer_field}
486 @sa bt_ctf_field_unsigned_integer_set_value(): Sets the unsigned
487 integral value of a given integer field.
489 extern int bt_ctf_field_unsigned_integer_get_value(
490 struct bt_ctf_field
*integer_field
, uint64_t *value
);
493 @brief Sets the unsigned integral value of the @intfield
494 \p integer_field to \p value.
496 @param[in] integer_field Integer field of which to set
497 the unsigned integral value.
498 @param[in] value New unsigned integral value of
500 @returns 0 on success, or a negative value on error.
502 @prenotnull{integer_field}
503 @preisintfield{integer_field}
504 @prehot{integer_field}
505 @pre bt_ctf_field_type_integer_get_signed() returns 0 for the parent
506 @ft of \p integer_field.
507 @postrefcountsame{integer_field}
509 @sa bt_ctf_field_unsigned_integer_get_value(): Returns the unsigned
510 integral value of a given integer field.
512 extern int bt_ctf_field_unsigned_integer_set_value(
513 struct bt_ctf_field
*integer_field
, uint64_t value
);
518 @defgroup ctfirfloatfield CTF IR floating point number field
520 @brief CTF IR floating point number field.
523 #include <babeltrace/ctf-ir/fields.h>
526 A CTF IR <strong><em>floating point number field</em></strong> is a
527 @field which holds a floating point number value, and which is
528 described by a @floatft.
530 After you create a floating point number field with bt_ctf_field_create(), you
531 \em must set a floating point number value with
532 bt_ctf_field_floating_point_set_value() before you can get the
533 field's value with bt_ctf_field_floating_point_get_value().
535 @sa ctfirfloatfieldtype
538 @addtogroup ctfirfloatfield
543 @brief Returns the floating point number value of the @floatfield
546 @param[in] float_field Floating point number field of which to get the
547 floating point number value.
548 @param[out] value Returned floating point number value of
550 @returns 0 on success, or a negative value on error,
551 including if \p float_field has no floating
552 point number value yet.
554 @prenotnull{float_field}
556 @preisfloatfield{float_field}
557 @pre \p float_field contains a floating point number value previously
558 set with bt_ctf_field_floating_point_set_value().
559 @postrefcountsame{float_field}
561 @sa bt_ctf_field_floating_point_set_value(): Sets the floating point
562 number value of a given floating point number field.
564 extern int bt_ctf_field_floating_point_get_value(
565 struct bt_ctf_field
*float_field
, double *value
);
568 @brief Sets the floating point number value of the @floatfield
569 \p float_field to \p value.
571 @param[in] float_field Floating point number field of which to set
572 the floating point number value.
573 @param[in] value New floating point number value of
575 @returns 0 on success, or a negative value on error.
577 @prenotnull{float_field}
578 @preisfloatfield{float_field}
580 @postrefcountsame{float_field}
582 @sa bt_ctf_field_floating_point_get_value(): Returns the floating point
583 number value of a given floating point number field.
585 extern int bt_ctf_field_floating_point_set_value(
586 struct bt_ctf_field
*float_field
,
592 @defgroup ctfirenumfield CTF IR enumeration field
594 @brief CTF IR enumeration field.
597 #include <babeltrace/ctf-ir/fields.h>
600 A CTF IR <strong><em>enumeration field</em></strong> is a @field which
601 holds a @intfield, and which is described by a @enumft.
603 To set the current integral value of an enumeration field, you need to
604 get its wrapped @intfield with bt_ctf_field_enumeration_get_container(),
605 and then set the integral value with either
606 bt_ctf_field_signed_integer_set_value() or
607 bt_ctf_field_unsigned_integer_set_value().
609 Once you set the integral value of an enumeration field by following the
610 previous paragraph, you can get the name of the mapping containing this
611 value in the enumeration field with
612 bt_ctf_field_enumeration_get_mapping_name().
614 @sa ctfirenumfieldtype
617 @addtogroup ctfirenumfield
622 @brief Returns the @intfield, potentially creating it, wrapped by the
623 @enumfield \p enum_field.
625 This function creates the @intfield to return if it does not currently
628 @param[in] enum_field Enumeration field of which to get the wrapped
630 @returns Integer field wrapped by \p enum_field, or
633 @prenotnull{enum_field}
634 @preisenumfield{enum_field}
635 @postrefcountsame{enum_field}
636 @postsuccessrefcountretinc
638 extern struct bt_ctf_field
*bt_ctf_field_enumeration_get_container(
639 struct bt_ctf_field
*enum_field
);
642 @brief Returns the name of the mapping selected by the current integral
643 value of the @enumfield \p enum_field.
645 On success, \p enum_field remains the sole owner of the returned
648 @param[in] enum_field Enumeration field of which to get the name of
649 mapping associated to its current integral
651 @returns Name of the mapping associated to the current
652 integral value of \p enum_field, or \c NULL
655 @prenotnull{enum_field}
656 @preisenumfield{enum_field}
657 @pre The wrapped integer field of \p enum_field contains an integral
659 @postrefcountsame{enum_field}
661 extern const char *bt_ctf_field_enumeration_get_mapping_name(
662 struct bt_ctf_field
*enum_field
);
667 @defgroup ctfirstringfield CTF IR string field
669 @brief CTF IR string field.
672 #include <babeltrace/ctf-ir/fields.h>
675 A CTF IR <strong><em>string field</em></strong> is a @field which holds
676 a string value, and which is described by a @stringft.
678 Use bt_ctf_field_string_set_value() to set the current string value
679 of a string field object. You can also use bt_ctf_field_string_append()
680 and bt_ctf_field_string_append_len() to append a string to the current
681 value of a string field.
683 After you create a string field with bt_ctf_field_create(), you
684 \em must set a string value with
685 bt_ctf_field_string_set_value(), bt_ctf_field_string_append(), or
686 bt_ctf_field_string_append_len() before you can get the
687 field's value with bt_ctf_field_string_get_value().
689 @sa ctfirstringfieldtype
692 @addtogroup ctfirstringfield
697 @brief Returns the string value of the @stringfield \p string_field.
699 On success, \p string_field remains the sole owner of the returned
702 @param[in] string_field String field field of which to get the
704 @returns String value, or \c NULL on error.
706 @prenotnull{string_field}
708 @preisstringfield{string_field}
709 @pre \p string_field contains a string value previously
710 set with bt_ctf_field_string_set_value(),
711 bt_ctf_field_string_append(), or
712 bt_ctf_field_string_append_len().
713 @postrefcountsame{string_field}
715 @sa bt_ctf_field_string_set_value(): Sets the string value of a given
718 extern const char *bt_ctf_field_string_get_value(
719 struct bt_ctf_field
*string_field
);
722 @brief Sets the string value of the @stringfield \p string_field to
725 @param[in] string_field String field of which to set
727 @param[in] value New string value of \p string_field (copied
729 @returns 0 on success, or a negative value on error.
731 @prenotnull{string_field}
733 @preisstringfield{string_field}
734 @prehot{string_field}
735 @postrefcountsame{string_field}
737 @sa bt_ctf_field_string_get_value(): Returns the string value of a
740 extern int bt_ctf_field_string_set_value(struct bt_ctf_field
*string_field
,
744 @brief Appends the string \p value to the current string value of
745 the @stringfield \p string_field.
747 This function is the equivalent of:
750 bt_ctf_field_string_append_len(string_field, value, strlen(value));
753 @param[in] string_field String field of which to append \p value to
755 @param[in] value String to append to the current string value
756 of \p string_field (copied on success).
757 @returns 0 on success, or a negative value on error.
759 @prenotnull{string_field}
761 @preisstringfield{string_field}
762 @prehot{string_field}
763 @postrefcountsame{string_field}
765 @sa bt_ctf_field_string_set_value(): Sets the string value of a given
768 extern int bt_ctf_field_string_append(struct bt_ctf_field
*string_field
,
772 @brief Appends the first \p length characters of \p value to the
773 current string value of the @stringfield \p string_field.
775 If \p string_field has no current string value, this function first
776 sets an empty string as the string value of \p string_field and then
777 appends the first \p length characters of \p value.
779 @param[in] string_field String field of which to append the first
780 \p length characters of \p value to
782 @param[in] value String containing the characters to append to
783 the current string value of \p string_field
785 @param[in] length Number of characters of \p value to append to
786 the current string value of \p string_field.
787 @returns 0 on success, or a negative value on error.
789 @prenotnull{string_field}
791 @preisstringfield{string_field}
792 @prehot{string_field}
793 @postrefcountsame{string_field}
795 @sa bt_ctf_field_string_set_value(): Sets the string value of a given
798 extern int bt_ctf_field_string_append_len(
799 struct bt_ctf_field
*string_field
, const char *value
,
800 unsigned int length
);
805 @defgroup ctfirstructfield CTF IR structure field
807 @brief CTF IR structure field.
810 #include <babeltrace/ctf-ir/fields.h>
813 A CTF IR <strong><em>structure field</em></strong> is a @field which
814 contains an ordered list of zero or more named @fields which can be
815 different @fts, and which is described by a @structft.
817 To set the value of a specific field of a structure field, you need to
818 first get the field with bt_ctf_field_structure_get_field() or
819 bt_ctf_field_structure_get_field_by_index().
821 @sa ctfirstructfieldtype
824 @addtogroup ctfirstructfield
829 @brief Returns the @field named \p name, potentially creating it,
830 in the @structfield \p struct_field.
832 This function creates the @field to return if it does not currently
835 @param[in] struct_field Structure field of which to get the field
837 @param[in] name Name of the field to get from \p struct_field.
838 @returns Field named \p name in \p struct_field, or
841 @prenotnull{struct_field}
843 @preisstructfield{struct_field}
844 @postrefcountsame{struct_field}
845 @postsuccessrefcountretinc
847 @sa bt_ctf_field_structure_get_field_by_index(): Returns the field of a
848 given structure field by index.
850 extern struct bt_ctf_field
*bt_ctf_field_structure_get_field(
851 struct bt_ctf_field
*struct_field
, const char *name
);
854 @brief Returns the @field at index \p index in the @structfield
857 @param[in] struct_field Structure field of which to get the field
859 @param[in] index Index of the field to get in \p struct_field.
860 @returns Field at index \p index in \p struct_field, or
863 @prenotnull{struct_field}
864 @preisstructfield{struct_field}
865 @pre \p index is lesser than the number of fields contained in the
866 parent field type of \p struct_field (see
867 bt_ctf_field_type_structure_get_field_count()).
868 @postrefcountsame{struct_field}
869 @postsuccessrefcountretinc
871 @sa bt_ctf_field_structure_get_field(): Returns the field of a
872 given structure field by name.
874 extern struct bt_ctf_field
*bt_ctf_field_structure_get_field_by_index(
875 struct bt_ctf_field
*struct_field
, int index
);
880 @defgroup ctfirarrayfield CTF IR array field
882 @brief CTF IR array field.
885 #include <babeltrace/ctf-ir/fields.h>
888 A CTF IR <strong><em>array field</em></strong> is a @field which
889 contains an ordered list of zero or more @fields sharing the same @ft,
890 and which is described by a @arrayft.
892 To set the value of a specific field of an array field, you need to
893 first get the field with bt_ctf_field_array_get_field().
895 @sa ctfirarrayfieldtype
898 @addtogroup ctfirarrayfield
903 @brief Returns the @field at index \p index, potentially creating it,
904 in the @arrayfield \p array_field.
906 This function creates the @field to return if it does not currently
909 @param[in] array_field Array field of which to get the field
911 @param[in] index Index of the field to get in \p array_field.
912 @returns Field at index \p index in \p array_field, or
915 @prenotnull{array_field}
916 @preisarrayfield{array_field}
917 @pre \p index is lesser than bt_ctf_field_type_array_get_length() called
918 on the field type of \p array_field.
919 @postrefcountsame{array_field}
920 @postsuccessrefcountretinc
922 extern struct bt_ctf_field
*bt_ctf_field_array_get_field(
923 struct bt_ctf_field
*array_field
, uint64_t index
);
928 @defgroup ctfirseqfield CTF IR sequence field
930 @brief CTF IR sequence field.
933 #include <babeltrace/ctf-ir/fields.h>
936 A CTF IR <strong><em>sequence field</em></strong> is a @field which
937 contains an ordered list of zero or more @fields sharing the same @ft,
938 and which is described by a @seqft.
940 Before you can get a specific field of a sequence field with
941 bt_ctf_field_sequence_get_field(), you need to set its current length
942 @intfield with bt_ctf_field_sequence_set_length(). The integral value of
943 the length field of a sequence field indicates the number of fields
946 @sa ctfirseqfieldtype
949 @addtogroup ctfirseqfield
954 @brief Returns the @field at index \p index, potentially creating it,
955 in the @seqfield \p sequence_field.
957 This function creates the @field to return if it does not currently
960 @param[in] sequence_field Sequence field of which to get the field
962 @param[in] index Index of the field to get in
964 @returns Field at index \p index in
965 \p sequence_field, or \c NULL on error.
967 @prenotnull{sequence_field}
968 @preisseqfield{sequence_field}
969 @pre \p sequence_field has a length field previously set with
970 bt_ctf_field_sequence_set_length().
971 @pre \p index is lesser than the current integral value of the current
972 length field of \p sequence_field (see
973 bt_ctf_field_sequence_get_length()).
974 @postrefcountsame{sequence_field}
975 @postsuccessrefcountretinc
977 extern struct bt_ctf_field
*bt_ctf_field_sequence_get_field(
978 struct bt_ctf_field
*sequence_field
, uint64_t index
);
981 @brief Returns the length @intfield of the @seqfield \p sequence_field.
983 The current integral value of the returned length field indicates the
984 number of fields contained in \p sequence_field.
986 @param[in] sequence_field Sequence field of which to get the
988 @returns Length field of \p sequence_field, or
991 @prenotnull{sequence_field}
992 @preisseqfield{sequence_field}
993 @pre \p sequence_field has a length field previously set with
994 bt_ctf_field_sequence_set_length().
995 @postrefcountsame{sequence_field}
996 @postsuccessrefcountretinc
997 @post <strong>On success</strong>, the returned field is a @intfield.
999 @sa bt_ctf_field_sequence_set_length(): Sets the length field of a given
1002 extern struct bt_ctf_field
*bt_ctf_field_sequence_get_length(
1003 struct bt_ctf_field
*sequence_field
);
1006 @brief Sets the length @intfield of the @seqfield \p sequence_field
1009 The current integral value of \p length_field indicates the number of
1010 fields contained in \p sequence_field.
1012 @param[in] sequence_field Sequence field of which to set the
1014 @param[in] length_field Length field of \p sequence_field.
1015 @returns 0 on success, or a negative value on error.
1017 @prenotnull{sequence_field}
1018 @prenotnull{length_field}
1019 @preisseqfield{sequence_field}
1020 @preisintfield{length_field}
1021 @prehot{sequence_field}
1022 @postrefcountsame{sequence_field}
1023 @postsuccessrefcountinc{length_field}
1025 @sa bt_ctf_field_sequence_get_length(): Returns the length field of a
1026 given sequence field.
1028 extern int bt_ctf_field_sequence_set_length(struct bt_ctf_field
*sequence_field
,
1029 struct bt_ctf_field
*length_field
);
1034 @defgroup ctfirvarfield CTF IR variant field
1035 @ingroup ctfirfields
1036 @brief CTF IR variant field.
1039 #include <babeltrace/ctf-ir/fields.h>
1042 A CTF IR <strong><em>variant field</em></strong> is a @field which
1043 contains a current @field amongst one or more choices, and which is
1044 described by a @varft.
1046 Use bt_ctf_field_variant_get_field() to get the @field selected by
1047 a specific tag @enumfield. Once you call this function, you can call
1048 bt_ctf_field_variant_get_current_field() afterwards to get this last
1051 @sa ctfirvarfieldtype
1054 @addtogroup ctfirvarfield
1059 @brief Returns the @field, potentially creating it, selected by the
1060 tag @intfield \p tag_field in the @varfield \p variant_field.
1062 This function creates the @field to return if it does not currently
1065 Once you call this function, you can call
1066 bt_ctf_field_variant_get_current_field() to get the same field again,
1067 and you can call bt_ctf_field_variant_get_tag() to get \p tag_field.
1069 @param[in] variant_field Variant field of which to get the field
1070 selected by \p tag_field.
1071 @param[in] tag_field Tag field.
1072 @returns Field selected by \p tag_field in
1073 \p variant_field, or \c NULL on error.
1075 @prenotnull{variant_field}
1076 @prenotnull{tag_field}
1077 @preisvarfield{variant_field}
1078 @preisenumfield{tag_field}
1079 @postrefcountsame{variant_field}
1080 @postsuccessrefcountinc{tag_field}
1081 @postsuccessrefcountretinc
1083 extern struct bt_ctf_field
*bt_ctf_field_variant_get_field(
1084 struct bt_ctf_field
*variant_field
,
1085 struct bt_ctf_field
*tag_field
);
1088 @brief Returns the currently selected @field of the @varfield
1091 @param[in] variant_field Variant field of which to get the
1092 currently selected field.
1093 @returns Currently selected field of
1094 \p variant_field, or \c NULL if there's
1095 no selected field or on error.
1097 @prenotnull{variant_field}
1098 @preisvarfield{variant_field}
1099 @pre \p variant_field contains has a current selected field previously
1100 set with bt_ctf_field_variant_get_field().
1101 @postrefcountsame{variant_field}
1102 @postsuccessrefcountretinc
1104 extern struct bt_ctf_field
*bt_ctf_field_variant_get_current_field(
1105 struct bt_ctf_field
*variant_field
);
1108 @brief Returns the tag @enumfield of the @varfield \p variant_field.
1110 @param[in] variant_field Variant field of which to get the
1112 @returns Tag field of \p variant_field, or
1115 @prenotnull{variant_field}
1116 @preisvarfield{variant_field}
1117 @pre \p variant_field contains has a current selected field previously
1118 set with bt_ctf_field_variant_get_field().
1119 @postrefcountsame{variant_field}
1120 @postsuccessrefcountretinc
1121 @post <strong>On success</strong>, the returned field is a @enumfield.
1123 extern struct bt_ctf_field
*bt_ctf_field_variant_get_tag(
1124 struct bt_ctf_field
*variant_field
);
1128 const char *bt_ctf_field_enumeration_get_single_mapping_name(
1129 struct bt_ctf_field
*field
);
1135 #endif /* BABELTRACE_CTF_IR_FIELDS_H */