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>
42 @defgroup ctfirfields CTF IR fields
47 #include <babeltrace/ctf-ir/fields.h>
50 A CTF IR <strong><em>field</em></strong> is an object which holds a
51 concrete value, and which is described by a @ft.
53 In the CTF IR hierarchy, you can set the root fields of two objects:
56 - Trace packet header field: bt_ctf_packet_set_header().
57 - Stream packet context field: bt_ctf_packet_set_context().
59 - Stream event header field: bt_ctf_event_set_header().
60 - Stream event context field: bt_ctf_event_set_stream_event_context().
61 - Event context field: bt_ctf_event_set_event_context().
62 - Event payload field: bt_ctf_event_set_payload_field().
64 There are two categories of fields:
66 - <strong>Basic fields</strong>:
67 - @intfield: contains an integral value.
68 - @floatfield: contains a floating point number value.
69 - @enumfield: contains an integer field which contains an integral
71 - @stringfield: contains a string value.
72 - <strong>Compound fields</strong>:
73 - @structfield: contains an ordered list of named fields
74 (possibly with different @fts).
75 - @arrayfield: contains an ordered list of fields which share
77 - @seqfield: contains an ordered list of fields which share
79 - @varfield: contains a single, current field.
81 You can create a field object from a @ft object with
82 bt_ctf_field_create(). The enumeration and compound fields create their
83 contained fields with the following getters if such fields do not exist
86 - bt_ctf_field_enumeration_get_container()
87 - bt_ctf_field_structure_get_field()
88 - bt_ctf_field_array_get_field()
89 - bt_ctf_field_sequence_get_field()
90 - bt_ctf_field_variant_get_field()
92 If you already have a field object, you can also assign it to a specific
93 name within a @structfield with bt_ctf_field_structure_set_field().
95 You can get a reference to the @ft which was used to create a field with
96 bt_ctf_field_get_type(). You can get the
97 \link #bt_ctf_field_type_id type ID\endlink of this field type directly with
98 bt_ctf_field_get_type_id().
100 You can get a deep copy of a field with bt_ctf_field_copy(). The field
101 copy, and its contained field copies if it's the case, have the same
102 field type as the originals.
104 As with any Babeltrace object, CTF IR field objects have
105 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
106 counts</a>. See \ref refs to learn more about the reference counting
107 management of Babeltrace objects.
109 The functions which freeze CTF IR \link ctfirpacket packet\endlink and
110 \link ctfirevent event\endlink objects also freeze their root field
111 objects. You cannot modify a frozen field object: it is considered
112 immutable, except for \link refs reference counting\endlink.
117 @brief CTF IR fields type and functions.
120 @addtogroup ctfirfields
126 @brief A CTF IR field.
130 struct bt_ctf_event_class
;
132 struct bt_ctf_field_type
;
133 struct bt_ctf_field_type_enumeration_mapping_iterator
;
136 @name Creation and parent field type access functions
141 @brief Creates an uninitialized @field described by the @ft
144 On success, \p field_type becomes the parent of the created field
147 On success, this function creates an \em uninitialized field: it has
148 no value. You need to set the value of the created field with one of the
149 its specific setters.
151 @param[in] field_type Field type which describes the field to create.
152 @returns Created field object, or \c NULL on error.
154 @prenotnull{field_type}
155 @postsuccessrefcountret1
156 @postsuccessfrozen{field_type}
158 extern struct bt_ctf_field
*bt_ctf_field_create(
159 struct bt_ctf_field_type
*field_type
);
162 @brief Returns the parent @ft of the @field \p field.
164 This function returns a reference to the field type which was used to
165 create the field object in the first place with bt_ctf_field_create().
167 @param[in] field Field of which to get the parent field type.
168 @returns Parent field type of \p event,
172 @postrefcountsame{field}
173 @postsuccessrefcountretinc
175 extern struct bt_ctf_field_type
*bt_ctf_field_get_type(
176 struct bt_ctf_field
*field
);
181 @name Type information
186 @brief Returns the type ID of the @ft of the @field \p field.
188 @param[in] field Field of which to get the type ID of its
190 @returns Type ID of the parent field type of \p field,
191 or #BT_CTF_FIELD_TYPE_ID_UNKNOWN on error.
194 @postrefcountsame{field}
196 @sa #bt_ctf_field_type_id: CTF IR field type ID.
197 @sa bt_ctf_field_is_integer(): Returns whether or not a given field is a
199 @sa bt_ctf_field_is_floating_point(): Returns whether or not a given
200 field is a @floatfield.
201 @sa bt_ctf_field_is_enumeration(): Returns whether or not a given field
203 @sa bt_ctf_field_is_string(): Returns whether or not a given field is a
205 @sa bt_ctf_field_is_structure(): Returns whether or not a given field is
207 @sa bt_ctf_field_is_array(): Returns whether or not a given field is a
209 @sa bt_ctf_field_is_sequence(): Returns whether or not a given field is
211 @sa bt_ctf_field_is_variant(): Returns whether or not a given field is a
214 extern enum bt_ctf_field_type_id
bt_ctf_field_get_type_id(struct bt_ctf_field
*field
);
217 * bt_ctf_field_signed_integer_get_value: get a signed integer field's value
219 * Get a signed integer field's value.
221 * @param integer Signed integer field instance.
222 * @param value Pointer to a signed integer where the value will be stored.
224 * Returns 0 on success, a negative value on error.
226 extern int bt_ctf_field_signed_integer_get_value(struct bt_ctf_field
*integer
,
230 @brief Returns whether or not the @field \p field is a @intfield.
232 @param[in] field Field to check (can be \c NULL).
233 @returns 1 if \p field is an integer field, or 0
234 otherwise (including if \p field is
238 @postrefcountsame{field}
240 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
243 extern int bt_ctf_field_is_integer(struct bt_ctf_field
*field
);
246 @brief Returns whether or not the @field \p field is a @floatfield.
248 @param[in] field Field to check (can be \c NULL).
249 @returns 1 if \p field is a floating point number field,
250 or 0 otherwise (including if \p field is
254 @postrefcountsame{field}
256 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
259 extern int bt_ctf_field_is_floating_point(struct bt_ctf_field
*field
);
262 @brief Returns whether or not the @field \p field is a @enumfield.
264 @param[in] field Field to check (can be \c NULL).
265 @returns 1 if \p field is an enumeration field, or 0
266 otherwise (including if \p field is
270 @postrefcountsame{field}
272 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
275 extern int bt_ctf_field_is_enumeration(struct bt_ctf_field
*field
);
278 @brief Returns whether or not the @field \p field is a @stringfield.
280 @param[in] field Field to check (can be \c NULL).
281 @returns 1 if \p field is a string field, or 0
282 otherwise (including if \p field is
286 @postrefcountsame{field}
288 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
291 extern int bt_ctf_field_is_string(struct bt_ctf_field
*field
);
294 @brief Returns whether or not the @field \p field is a @structfield.
296 @param[in] field Field to check (can be \c NULL).
297 @returns 1 if \p field is a structure field, or 0
298 otherwise (including if \p field is
302 @postrefcountsame{field}
304 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
307 extern int bt_ctf_field_is_structure(struct bt_ctf_field
*field
);
310 @brief Returns whether or not the @field \p field is a @arrayfield.
312 @param[in] field Field to check (can be \c NULL).
313 @returns 1 if \p field is an array field, or 0
314 otherwise (including if \p field is
318 @postrefcountsame{field}
320 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
323 extern int bt_ctf_field_is_array(struct bt_ctf_field
*field
);
326 @brief Returns whether or not the @field \p field is a @seqfield.
328 @param[in] field Field to check (can be \c NULL).
329 @returns 1 if \p field is a sequence field, or 0
330 otherwise (including if \p field is
334 @postrefcountsame{field}
336 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
339 extern int bt_ctf_field_is_sequence(struct bt_ctf_field
*field
);
342 @brief Returns whether or not the @field \p field is a @varfield.
344 @param[in] field Field to check (can be \c NULL).
345 @returns 1 if \p field is a variant field, or 0
346 otherwise (including if \p field is
350 @postrefcountsame{field}
352 @sa bt_ctf_field_get_type_id(): Returns the type ID of a given
355 extern int bt_ctf_field_is_variant(struct bt_ctf_field
*field
);
360 @name Misc. functions
365 @brief Creates a \em deep copy of the @field \p field.
367 You can copy a frozen field: the resulting copy is <em>not frozen</em>.
369 @param[in] field Field to copy.
370 @returns Deep copy of \p field on success,
374 @postrefcountsame{field}
375 @postsuccessrefcountret1
376 @post <strong>On success</strong>, the returned field is not frozen.
378 extern struct bt_ctf_field
*bt_ctf_field_copy(struct bt_ctf_field
*field
);
385 @defgroup ctfirintfield CTF IR integer field
387 @brief CTF IR integer field.
390 #include <babeltrace/ctf-ir/fields.h>
393 A CTF IR <strong><em>integer field</em></strong> is a @field which
394 holds a signed or unsigned integral value, and which is described by
397 An integer field object is considered \em unsigned if
398 bt_ctf_field_type_integer_get_signed() on its parent field type returns
399 0. Otherwise it is considered \em signed. You \em must use
400 bt_ctf_field_unsigned_integer_get_value() and
401 bt_ctf_field_unsigned_integer_set_value() with an unsigned integer
402 field, and bt_ctf_field_signed_integer_get_value() and
403 bt_ctf_field_signed_integer_set_value() with a signed integer field.
405 After you create an integer field with bt_ctf_field_create(), you
406 \em must set an integral value with
407 bt_ctf_field_unsigned_integer_set_value() or
408 bt_ctf_field_signed_integer_set_value() before you can get the
409 field's value with bt_ctf_field_unsigned_integer_get_value() or
410 bt_ctf_field_signed_integer_get_value().
412 @sa ctfirintfieldtype
415 @addtogroup ctfirintfield
420 @brief Returns the signed integral value of the @intfield
423 @param[in] integer_field Integer field of which to get the
424 signed integral value.
425 @param[out] value Returned signed integral value of
427 @returns 0 on success, or a negative value on
428 error, including if \p integer_field
429 has no integral value yet.
431 @prenotnull{integer_field}
433 @preisintfield{integer_field}
434 @pre bt_ctf_field_type_integer_get_signed() returns 1 for the parent
435 @ft of \p integer_field.
436 @pre \p integer_field contains a signed integral value previously
437 set with bt_ctf_field_signed_integer_set_value().
438 @postrefcountsame{integer_field}
440 @sa bt_ctf_field_signed_integer_set_value(): Sets the signed integral
441 value of a given integer field.
443 extern int bt_ctf_field_signed_integer_get_value(
444 struct bt_ctf_field
*integer_field
, int64_t *value
);
447 @brief Sets the signed integral value of the @intfield
448 \p integer_field to \p value.
450 @param[in] integer_field Integer field of which to set
451 the signed integral value.
452 @param[in] value New signed integral value of
454 @returns 0 on success, or a negative value on error.
456 @prenotnull{integer_field}
457 @preisintfield{integer_field}
458 @prehot{integer_field}
459 @pre bt_ctf_field_type_integer_get_signed() returns 1 for the parent
460 @ft of \p integer_field.
461 @postrefcountsame{integer_field}
463 @sa bt_ctf_field_signed_integer_get_value(): Returns the signed integral
464 value of a given integer field.
466 extern int bt_ctf_field_signed_integer_set_value(
467 struct bt_ctf_field
*integer_field
, int64_t value
);
470 @brief Returns the unsigned integral value of the @intfield
473 @param[in] integer_field Integer field of which to get the
474 unsigned integral value.
475 @param[out] value Returned unsigned integral value of
477 @returns 0 on success, or a negative value on
478 error, including if \p integer_field
479 has no integral value yet.
481 @prenotnull{integer_field}
483 @preisintfield{integer_field}
484 @pre bt_ctf_field_type_integer_get_signed() returns 0 for the parent
485 @ft of \p integer_field.
486 @pre \p integer_field contains an unsigned integral value previously
487 set with bt_ctf_field_unsigned_integer_set_value().
488 @postrefcountsame{integer_field}
490 @sa bt_ctf_field_unsigned_integer_set_value(): Sets the unsigned
491 integral value of a given integer field.
493 extern int bt_ctf_field_unsigned_integer_get_value(
494 struct bt_ctf_field
*integer_field
, uint64_t *value
);
497 @brief Sets the unsigned integral value of the @intfield
498 \p integer_field to \p value.
500 @param[in] integer_field Integer field of which to set
501 the unsigned integral value.
502 @param[in] value New unsigned integral value of
504 @returns 0 on success, or a negative value on error.
506 @prenotnull{integer_field}
507 @preisintfield{integer_field}
508 @prehot{integer_field}
509 @pre bt_ctf_field_type_integer_get_signed() returns 0 for the parent
510 @ft of \p integer_field.
511 @postrefcountsame{integer_field}
513 @sa bt_ctf_field_unsigned_integer_get_value(): Returns the unsigned
514 integral value of a given integer field.
516 extern int bt_ctf_field_unsigned_integer_set_value(
517 struct bt_ctf_field
*integer_field
, uint64_t value
);
522 @defgroup ctfirfloatfield CTF IR floating point number field
524 @brief CTF IR floating point number field.
527 #include <babeltrace/ctf-ir/fields.h>
530 A CTF IR <strong><em>floating point number field</em></strong> is a
531 @field which holds a floating point number value, and which is
532 described by a @floatft.
534 After you create a floating point number field with bt_ctf_field_create(), you
535 \em must set a floating point number value with
536 bt_ctf_field_floating_point_set_value() before you can get the
537 field's value with bt_ctf_field_floating_point_get_value().
539 @sa ctfirfloatfieldtype
542 @addtogroup ctfirfloatfield
547 @brief Returns the floating point number value of the @floatfield
550 @param[in] float_field Floating point number field of which to get the
551 floating point number value.
552 @param[out] value Returned floating point number value of
554 @returns 0 on success, or a negative value on error,
555 including if \p float_field has no floating
556 point number value yet.
558 @prenotnull{float_field}
560 @preisfloatfield{float_field}
561 @pre \p float_field contains a floating point number value previously
562 set with bt_ctf_field_floating_point_set_value().
563 @postrefcountsame{float_field}
565 @sa bt_ctf_field_floating_point_set_value(): Sets the floating point
566 number value of a given floating point number field.
568 extern int bt_ctf_field_floating_point_get_value(
569 struct bt_ctf_field
*float_field
, double *value
);
572 @brief Sets the floating point number value of the @floatfield
573 \p float_field to \p value.
575 @param[in] float_field Floating point number field of which to set
576 the floating point number value.
577 @param[in] value New floating point number value of
579 @returns 0 on success, or a negative value on error.
581 @prenotnull{float_field}
582 @preisfloatfield{float_field}
584 @postrefcountsame{float_field}
586 @sa bt_ctf_field_floating_point_get_value(): Returns the floating point
587 number value of a given floating point number field.
589 extern int bt_ctf_field_floating_point_set_value(
590 struct bt_ctf_field
*float_field
,
596 @defgroup ctfirenumfield CTF IR enumeration field
598 @brief CTF IR enumeration field.
601 #include <babeltrace/ctf-ir/fields.h>
604 A CTF IR <strong><em>enumeration field</em></strong> is a @field which
605 holds a @intfield, and which is described by a @enumft.
607 To set the current integral value of an enumeration field, you need to
608 get its wrapped @intfield with bt_ctf_field_enumeration_get_container(),
609 and then set the integral value with either
610 bt_ctf_field_signed_integer_set_value() or
611 bt_ctf_field_unsigned_integer_set_value().
613 Once you set the integral value of an enumeration field by following the
614 previous paragraph, you can get the mappings containing this value in
615 their range with bt_ctf_field_enumeration_get_mappings(). This function
616 returns a @enumftiter.
618 @sa ctfirenumfieldtype
621 @addtogroup ctfirenumfield
626 @brief Returns the @intfield, potentially creating it, wrapped by the
627 @enumfield \p enum_field.
629 This function creates the @intfield to return if it does not currently
632 @param[in] enum_field Enumeration field of which to get the wrapped
634 @returns Integer field wrapped by \p enum_field, or
637 @prenotnull{enum_field}
638 @preisenumfield{enum_field}
639 @postrefcountsame{enum_field}
640 @postsuccessrefcountretinc
642 extern struct bt_ctf_field
*bt_ctf_field_enumeration_get_container(
643 struct bt_ctf_field
*enum_field
);
646 @brief Returns a @enumftiter on all the mappings of the field type of
647 \p enum_field which contain the current integral value of the
648 @enumfield \p enum_field in their range.
650 This function is the equivalent of using
651 bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value() or
652 bt_ctf_field_type_enumeration_find_mappings_by_signed_value() with the
653 current integral value of \p enum_field.
655 @param[in] enum_field Enumeration field of which to get the mappings
656 containing the current integral value of \p
657 enum_field in their range.
658 @returns @enumftiter on the set of mappings of the field
659 type of \p enum_field which contain the current
660 integral value of \p enum_field in their range,
661 or \c NULL if no mappings were found or on
664 @prenotnull{enum_field}
665 @preisenumfield{enum_field}
666 @pre The wrapped integer field of \p enum_field contains an integral
668 @postrefcountsame{enum_field}
669 @postsuccessrefcountret1
670 @post <strong>On success</strong>, the returned @enumftiter can iterate
671 on at least one mapping.
673 extern struct bt_ctf_field_type_enumeration_mapping_iterator
*
674 bt_ctf_field_enumeration_get_mappings(struct bt_ctf_field
*enum_field
);
679 @defgroup ctfirstringfield CTF IR string field
681 @brief CTF IR string field.
684 #include <babeltrace/ctf-ir/fields.h>
687 A CTF IR <strong><em>string field</em></strong> is a @field which holds
688 a string value, and which is described by a @stringft.
690 Use bt_ctf_field_string_set_value() to set the current string value
691 of a string field object. You can also use bt_ctf_field_string_append()
692 and bt_ctf_field_string_append_len() to append a string to the current
693 value of a string field.
695 After you create a string field with bt_ctf_field_create(), you
696 \em must set a string value with
697 bt_ctf_field_string_set_value(), bt_ctf_field_string_append(), or
698 bt_ctf_field_string_append_len() before you can get the
699 field's value with bt_ctf_field_string_get_value().
701 @sa ctfirstringfieldtype
704 @addtogroup ctfirstringfield
709 @brief Returns the string value of the @stringfield \p string_field.
711 On success, \p string_field remains the sole owner of the returned
714 @param[in] string_field String field field of which to get the
716 @returns String value, or \c NULL on error.
718 @prenotnull{string_field}
720 @preisstringfield{string_field}
721 @pre \p string_field contains a string value previously
722 set with bt_ctf_field_string_set_value(),
723 bt_ctf_field_string_append(), or
724 bt_ctf_field_string_append_len().
725 @postrefcountsame{string_field}
727 @sa bt_ctf_field_string_set_value(): Sets the string value of a given
730 extern const char *bt_ctf_field_string_get_value(
731 struct bt_ctf_field
*string_field
);
734 @brief Sets the string value of the @stringfield \p string_field to
737 @param[in] string_field String field of which to set
739 @param[in] value New string value of \p string_field (copied
741 @returns 0 on success, or a negative value on error.
743 @prenotnull{string_field}
745 @preisstringfield{string_field}
746 @prehot{string_field}
747 @postrefcountsame{string_field}
749 @sa bt_ctf_field_string_get_value(): Returns the string value of a
752 extern int bt_ctf_field_string_set_value(struct bt_ctf_field
*string_field
,
756 @brief Appends the string \p value to the current string value of
757 the @stringfield \p string_field.
759 This function is the equivalent of:
762 bt_ctf_field_string_append_len(string_field, value, strlen(value));
765 @param[in] string_field String field of which to append \p value to
767 @param[in] value String to append to the current string value
768 of \p string_field (copied on success).
769 @returns 0 on success, or a negative value on error.
771 @prenotnull{string_field}
773 @preisstringfield{string_field}
774 @prehot{string_field}
775 @postrefcountsame{string_field}
777 @sa bt_ctf_field_string_set_value(): Sets the string value of a given
780 extern int bt_ctf_field_string_append(struct bt_ctf_field
*string_field
,
784 @brief Appends the first \p length characters of \p value to the
785 current string value of the @stringfield \p string_field.
787 If \p string_field has no current string value, this function first
788 sets an empty string as the string value of \p string_field and then
789 appends the first \p length characters of \p value.
791 @param[in] string_field String field of which to append the first
792 \p length characters of \p value to
794 @param[in] value String containing the characters to append to
795 the current string value of \p string_field
797 @param[in] length Number of characters of \p value to append to
798 the current string value of \p string_field.
799 @returns 0 on success, or a negative value on error.
801 @prenotnull{string_field}
803 @preisstringfield{string_field}
804 @prehot{string_field}
805 @postrefcountsame{string_field}
807 @sa bt_ctf_field_string_set_value(): Sets the string value of a given
810 extern int bt_ctf_field_string_append_len(
811 struct bt_ctf_field
*string_field
, const char *value
,
812 unsigned int length
);
817 @defgroup ctfirstructfield CTF IR structure field
819 @brief CTF IR structure field.
822 #include <babeltrace/ctf-ir/fields.h>
825 A CTF IR <strong><em>structure field</em></strong> is a @field which
826 contains an ordered list of zero or more named @fields which can be
827 different @fts, and which is described by a @structft.
829 To set the value of a specific field of a structure field, you need to
830 first get the field with bt_ctf_field_structure_get_field() or
831 bt_ctf_field_structure_get_field_by_index(). If you already have a
832 field object, you can assign it to a specific name within a structure
833 field with bt_ctf_field_structure_set_field().
835 @sa ctfirstructfieldtype
838 @addtogroup ctfirstructfield
843 @brief Returns the @field named \p name, potentially creating it,
844 in the @structfield \p struct_field.
846 This function creates the @field to return if it does not currently
849 @param[in] struct_field Structure field of which to get the field
851 @param[in] name Name of the field to get from \p struct_field.
852 @returns Field named \p name in \p struct_field, or
855 @prenotnull{struct_field}
857 @preisstructfield{struct_field}
858 @postrefcountsame{struct_field}
859 @postsuccessrefcountretinc
861 @sa bt_ctf_field_structure_get_field_by_index(): Returns the field of a
862 given structure field by index.
863 @sa bt_ctf_field_structure_set_field(): Sets the field of a given
866 extern struct bt_ctf_field
*bt_ctf_field_structure_get_field_by_name(
867 struct bt_ctf_field
*struct_field
, const char *name
);
869 /* Pre-2.0 CTF writer compatibility */
870 #define bt_ctf_field_structure_get_field bt_ctf_field_structure_get_field_by_name
873 @brief Returns the @field at index \p index in the @structfield
876 @param[in] struct_field Structure field of which to get the field
878 @param[in] index Index of the field to get in \p struct_field.
879 @returns Field at index \p index in \p struct_field, or
882 @prenotnull{struct_field}
883 @preisstructfield{struct_field}
884 @pre \p index is lesser than the number of fields contained in the
885 parent field type of \p struct_field (see
886 bt_ctf_field_type_structure_get_field_count()).
887 @postrefcountsame{struct_field}
888 @postsuccessrefcountretinc
890 @sa bt_ctf_field_structure_get_field(): Returns the field of a
891 given structure field by name.
892 @sa bt_ctf_field_structure_set_field(): Sets the field of a given
895 extern struct bt_ctf_field
*bt_ctf_field_structure_get_field_by_index(
896 struct bt_ctf_field
*struct_field
, uint64_t index
);
899 @brief Sets the field of the @structfield \p struct_field named \p name
900 to the @field \p field.
902 If \p struct_field already contains a field named \p name, then its
903 reference count is decremented, and \p field replaces it.
905 The field type of \p field, as returned by bt_ctf_field_get_type(),
906 \em must be equivalent to the field type returned by
907 bt_ctf_field_type_structure_get_field_type_by_name() with the field
908 type of \p struct_field and the same name, \p name.
910 bt_ctf_trace_get_packet_header_type() for the parent trace class of
913 @param[in] struct_field Structure field of which to set the field
915 @param[in] name Name of the field to set in \p struct_field.
916 @param[in] field Field named \p name to set in \p struct_field.
917 @returns 0 on success, or -1 on error.
919 @prenotnull{struct_field}
922 @prehot{struct_field}
923 @preisstructfield{struct_field}
924 @pre \p field has a field type equivalent to the field type returned by
925 bt_ctf_field_type_structure_get_field_type_by_name() for the
926 field type of \p struct_field with the name \p name.
927 @postrefcountsame{struct_field}
928 @post <strong>On success, if there's an existing field in
929 \p struct_field named \p name</strong>, its reference count is
931 @postsuccessrefcountinc{field}
933 @sa bt_ctf_field_structure_get_field_by_index(): Returns the field of a
934 given structure field by index.
935 @sa bt_ctf_field_structure_get_field(): Returns the field of a
936 given structure field by name.
938 extern int bt_ctf_field_structure_set_field(struct bt_ctf_field
*struct_field
,
939 const char *name
, struct bt_ctf_field
*field
);
944 @defgroup ctfirarrayfield CTF IR array field
946 @brief CTF IR array field.
949 #include <babeltrace/ctf-ir/fields.h>
952 A CTF IR <strong><em>array field</em></strong> is a @field which
953 contains an ordered list of zero or more @fields sharing the same @ft,
954 and which is described by a @arrayft.
956 To set the value of a specific field of an array field, you need to
957 first get the field with bt_ctf_field_array_get_field().
959 @sa ctfirarrayfieldtype
962 @addtogroup ctfirarrayfield
967 @brief Returns the @field at index \p index, potentially creating it,
968 in the @arrayfield \p array_field.
970 This function creates the @field to return if it does not currently
973 @param[in] array_field Array field of which to get the field
975 @param[in] index Index of the field to get in \p array_field.
976 @returns Field at index \p index in \p array_field, or
979 @prenotnull{array_field}
980 @preisarrayfield{array_field}
981 @pre \p index is lesser than bt_ctf_field_type_array_get_length() called
982 on the field type of \p array_field.
983 @postrefcountsame{array_field}
984 @postsuccessrefcountretinc
986 extern struct bt_ctf_field
*bt_ctf_field_array_get_field(
987 struct bt_ctf_field
*array_field
, uint64_t index
);
992 @defgroup ctfirseqfield CTF IR sequence field
994 @brief CTF IR sequence field.
997 #include <babeltrace/ctf-ir/fields.h>
1000 A CTF IR <strong><em>sequence field</em></strong> is a @field which
1001 contains an ordered list of zero or more @fields sharing the same @ft,
1002 and which is described by a @seqft.
1004 Before you can get a specific field of a sequence field with
1005 bt_ctf_field_sequence_get_field(), you need to set its current length
1006 @intfield with bt_ctf_field_sequence_set_length(). The integral value of
1007 the length field of a sequence field indicates the number of fields
1010 @sa ctfirseqfieldtype
1013 @addtogroup ctfirseqfield
1018 @brief Returns the @field at index \p index, potentially creating it,
1019 in the @seqfield \p sequence_field.
1021 This function creates the @field to return if it does not currently
1024 @param[in] sequence_field Sequence field of which to get the field
1026 @param[in] index Index of the field to get in
1028 @returns Field at index \p index in
1029 \p sequence_field, or \c NULL on error.
1031 @prenotnull{sequence_field}
1032 @preisseqfield{sequence_field}
1033 @pre \p sequence_field has a length field previously set with
1034 bt_ctf_field_sequence_set_length().
1035 @pre \p index is lesser than the current integral value of the current
1036 length field of \p sequence_field (see
1037 bt_ctf_field_sequence_get_length()).
1038 @postrefcountsame{sequence_field}
1039 @postsuccessrefcountretinc
1041 extern struct bt_ctf_field
*bt_ctf_field_sequence_get_field(
1042 struct bt_ctf_field
*sequence_field
, uint64_t index
);
1045 @brief Returns the length @intfield of the @seqfield \p sequence_field.
1047 The current integral value of the returned length field indicates the
1048 number of fields contained in \p sequence_field.
1050 @param[in] sequence_field Sequence field of which to get the
1052 @returns Length field of \p sequence_field, or
1055 @prenotnull{sequence_field}
1056 @preisseqfield{sequence_field}
1057 @pre \p sequence_field has a length field previously set with
1058 bt_ctf_field_sequence_set_length().
1059 @postrefcountsame{sequence_field}
1060 @postsuccessrefcountretinc
1061 @post <strong>On success</strong>, the returned field is a @intfield.
1063 @sa bt_ctf_field_sequence_set_length(): Sets the length field of a given
1066 extern struct bt_ctf_field
*bt_ctf_field_sequence_get_length(
1067 struct bt_ctf_field
*sequence_field
);
1070 @brief Sets the length @intfield of the @seqfield \p sequence_field
1073 The current integral value of \p length_field indicates the number of
1074 fields contained in \p sequence_field.
1076 @param[in] sequence_field Sequence field of which to set the
1078 @param[in] length_field Length field of \p sequence_field.
1079 @returns 0 on success, or a negative value on error.
1081 @prenotnull{sequence_field}
1082 @prenotnull{length_field}
1083 @preisseqfield{sequence_field}
1084 @preisintfield{length_field}
1085 @prehot{sequence_field}
1086 @postrefcountsame{sequence_field}
1087 @postsuccessrefcountinc{length_field}
1089 @sa bt_ctf_field_sequence_get_length(): Returns the length field of a
1090 given sequence field.
1092 extern int bt_ctf_field_sequence_set_length(struct bt_ctf_field
*sequence_field
,
1093 struct bt_ctf_field
*length_field
);
1098 @defgroup ctfirvarfield CTF IR variant field
1099 @ingroup ctfirfields
1100 @brief CTF IR variant field.
1103 #include <babeltrace/ctf-ir/fields.h>
1106 A CTF IR <strong><em>variant field</em></strong> is a @field which
1107 contains a current @field amongst one or more choices, and which is
1108 described by a @varft.
1110 Use bt_ctf_field_variant_get_field() to get the @field selected by
1111 a specific tag @enumfield. Once you call this function, you can call
1112 bt_ctf_field_variant_get_current_field() afterwards to get this last
1115 @sa ctfirvarfieldtype
1118 @addtogroup ctfirvarfield
1123 @brief Returns the @field, potentially creating it, selected by the
1124 tag @intfield \p tag_field in the @varfield \p variant_field.
1126 This function creates the @field to return if it does not currently
1129 Once you call this function, you can call
1130 bt_ctf_field_variant_get_current_field() to get the same field again,
1131 and you can call bt_ctf_field_variant_get_tag() to get \p tag_field.
1133 @param[in] variant_field Variant field of which to get the field
1134 selected by \p tag_field.
1135 @param[in] tag_field Tag field.
1136 @returns Field selected by \p tag_field in
1137 \p variant_field, or \c NULL on error.
1139 @prenotnull{variant_field}
1140 @prenotnull{tag_field}
1141 @preisvarfield{variant_field}
1142 @preisenumfield{tag_field}
1143 @postrefcountsame{variant_field}
1144 @postsuccessrefcountinc{tag_field}
1145 @postsuccessrefcountretinc
1147 extern struct bt_ctf_field
*bt_ctf_field_variant_get_field(
1148 struct bt_ctf_field
*variant_field
,
1149 struct bt_ctf_field
*tag_field
);
1152 @brief Returns the currently selected @field of the @varfield
1155 @param[in] variant_field Variant field of which to get the
1156 currently selected field.
1157 @returns Currently selected field of
1158 \p variant_field, or \c NULL if there's
1159 no selected field or on error.
1161 @prenotnull{variant_field}
1162 @preisvarfield{variant_field}
1163 @pre \p variant_field contains has a current selected field previously
1164 set with bt_ctf_field_variant_get_field().
1165 @postrefcountsame{variant_field}
1166 @postsuccessrefcountretinc
1168 extern struct bt_ctf_field
*bt_ctf_field_variant_get_current_field(
1169 struct bt_ctf_field
*variant_field
);
1172 @brief Returns the tag @enumfield of the @varfield \p variant_field.
1174 @param[in] variant_field Variant field of which to get the
1176 @returns Tag field of \p variant_field, or
1179 @prenotnull{variant_field}
1180 @preisvarfield{variant_field}
1181 @pre \p variant_field contains has a current selected field previously
1182 set with bt_ctf_field_variant_get_field().
1183 @postrefcountsame{variant_field}
1184 @postsuccessrefcountretinc
1185 @post <strong>On success</strong>, the returned field is a @enumfield.
1187 extern struct bt_ctf_field
*bt_ctf_field_variant_get_tag(
1188 struct bt_ctf_field
*variant_field
);
1196 #endif /* BABELTRACE_CTF_IR_FIELDS_H */