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/ref.h>
40 #include <babeltrace/types.h>
49 @defgroup ctfirfields CTF IR fields
54 #include <babeltrace/ctf-ir/fields.h>
57 A CTF IR <strong><em>field</em></strong> is an object which holds a
58 concrete value, and which is described by a @ft.
60 In the CTF IR hierarchy, you can set the root fields of two objects:
63 - Trace packet header field: bt_packet_set_header().
64 - Stream packet context field: bt_packet_set_context().
66 - Stream event header field: bt_event_set_header().
67 - Stream event context field: bt_event_set_stream_event_context().
68 - Event context field: bt_event_set_event_context().
69 - Event payload field: bt_event_set_payload_field().
71 There are two categories of fields:
73 - <strong>Basic fields</strong>:
74 - @intfield: contains an integral value.
75 - @floatfield: contains a floating point number value.
76 - @enumfield: contains an integer field which contains an integral
78 - @stringfield: contains a string value.
79 - <strong>Compound fields</strong>:
80 - @structfield: contains an ordered list of named fields
81 (possibly with different @fts).
82 - @arrayfield: contains an ordered list of fields which share
84 - @seqfield: contains an ordered list of fields which share
86 - @varfield: contains a single, current field.
88 You can create a field object from a @ft object with
89 bt_field_create(). The enumeration and compound fields create their
90 contained fields with the following getters if such fields do not exist
93 - bt_field_enumeration_get_container()
94 - bt_field_structure_get_field_by_name()
95 - bt_field_array_get_field()
96 - bt_field_sequence_get_field()
97 - bt_field_variant_get_field()
99 If you already have a field object, you can also assign it to a specific
100 name within a @structfield with
101 bt_field_structure_set_field_by_name().
103 You can get a reference to the @ft which was used to create a field with
104 bt_field_get_type(). You can get the
105 \link #bt_field_type_id type ID\endlink of this field type directly with
106 bt_field_get_type_id().
108 You can get a deep copy of a field with bt_field_copy(). The field
109 copy, and its contained field copies if it's the case, have the same
110 field type as the originals.
112 As with any Babeltrace object, CTF IR field objects have
113 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
114 counts</a>. See \ref refs to learn more about the reference counting
115 management of Babeltrace objects.
117 The functions which freeze CTF IR \link ctfirpacket packet\endlink and
118 \link ctfirevent event\endlink objects also freeze their root field
119 objects. You cannot modify a frozen field object: it is considered
120 immutable, except for \link refs reference counting\endlink.
125 @brief CTF IR fields type and functions.
128 @addtogroup ctfirfields
134 @brief A CTF IR field.
138 struct bt_event_class
;
140 struct bt_field_type
;
141 struct bt_field_type_enumeration_mapping_iterator
;
144 @name Creation and parent field type access functions
148 extern struct bt_field_type
*bt_field_borrow_type(struct bt_field
*field
);
151 @brief Returns the parent @ft of the @field \p field.
153 This function returns a reference to the field type which was used to
154 create the field object in the first place with bt_field_create().
156 @param[in] field Field of which to get the parent field type.
157 @returns Parent field type of \p event,
161 @postrefcountsame{field}
162 @postsuccessrefcountretinc
165 struct bt_field_type
*bt_field_get_type(struct bt_field
*field
)
167 return bt_get(bt_field_borrow_type(field
));
173 @name Type information
178 @brief Returns the type ID of the @ft of the @field \p field.
180 @param[in] field Field of which to get the type ID of its
182 @returns Type ID of the parent field type of \p field,
183 or #BT_FIELD_TYPE_ID_UNKNOWN on error.
186 @postrefcountsame{field}
188 @sa #bt_field_type_id: CTF IR field type ID.
189 @sa bt_field_is_integer(): Returns whether or not a given field is a
191 @sa bt_field_is_floating_point(): Returns whether or not a given
192 field is a @floatfield.
193 @sa bt_field_is_enumeration(): Returns whether or not a given field
195 @sa bt_field_is_string(): Returns whether or not a given field is a
197 @sa bt_field_is_structure(): Returns whether or not a given field is
199 @sa bt_field_is_array(): Returns whether or not a given field is a
201 @sa bt_field_is_sequence(): Returns whether or not a given field is
203 @sa bt_field_is_variant(): Returns whether or not a given field is a
206 extern enum bt_field_type_id
bt_field_get_type_id(struct bt_field
*field
);
209 @brief Returns whether or not the @field \p field is a @intfield.
211 @param[in] field Field to check (can be \c NULL).
212 @returns #BT_TRUE if \p field is an integer field, or
213 #BT_FALSE otherwise (including if \p field is
217 @postrefcountsame{field}
219 @sa bt_field_get_type_id(): Returns the type ID of a given
222 extern bt_bool
bt_field_is_integer(struct bt_field
*field
);
225 @brief Returns whether or not the @field \p field is a @floatfield.
227 @param[in] field Field to check (can be \c NULL).
228 @returns #BT_TRUE if \p field is a floating point number fiel
229 #BT_FALSE or 0 otherwise (including if \p field is
233 @postrefcountsame{field}
235 @sa bt_field_get_type_id(): Returns the type ID of a given
238 extern bt_bool
bt_field_is_floating_point(struct bt_field
*field
);
241 @brief Returns whether or not the @field \p field is a @enumfield.
243 @param[in] field Field to check (can be \c NULL).
244 @returns #BT_TRUE if \p field is an enumeration field, or
245 #BT_FALSE otherwise (including if \p field is
249 @postrefcountsame{field}
251 @sa bt_field_get_type_id(): Returns the type ID of a given
254 extern bt_bool
bt_field_is_enumeration(struct bt_field
*field
);
257 @brief Returns whether or not the @field \p field is a @stringfield.
259 @param[in] field Field to check (can be \c NULL).
260 @returns #BT_TRUE if \p field is a string field, or
261 #BT_FALSE otherwise (including if \p field is
265 @postrefcountsame{field}
267 @sa bt_field_get_type_id(): Returns the type ID of a given
270 extern bt_bool
bt_field_is_string(struct bt_field
*field
);
273 @brief Returns whether or not the @field \p field is a @structfield.
275 @param[in] field Field to check (can be \c NULL).
276 @returns #BT_TRUE if \p field is a structure field, or
277 #BT_FALSE otherwise (including if \p field is
281 @postrefcountsame{field}
283 @sa bt_field_get_type_id(): Returns the type ID of a given
286 extern bt_bool
bt_field_is_structure(struct bt_field
*field
);
289 @brief Returns whether or not the @field \p field is a @arrayfield.
291 @param[in] field Field to check (can be \c NULL).
292 @returns #BT_TRUE if \p field is an array field, or
293 #BT_FALSE otherwise (including if \p field is
297 @postrefcountsame{field}
299 @sa bt_field_get_type_id(): Returns the type ID of a given
302 extern bt_bool
bt_field_is_array(struct bt_field
*field
);
305 @brief Returns whether or not the @field \p field is a @seqfield.
307 @param[in] field Field to check (can be \c NULL).
308 @returns #BT_TRUE if \p field is a sequence field, or
309 #BT_FALSE otherwise (including if \p field is
313 @postrefcountsame{field}
315 @sa bt_field_get_type_id(): Returns the type ID of a given
318 extern bt_bool
bt_field_is_sequence(struct bt_field
*field
);
321 @brief Returns whether or not the @field \p field is a @varfield.
323 @param[in] field Field to check (can be \c NULL).
324 @returns #BT_TRUE if \p field is a variant field, or
325 #BT_FALSE otherwise (including if \p field is
329 @postrefcountsame{field}
331 @sa bt_field_get_type_id(): Returns the type ID of a given
334 extern bt_bool
bt_field_is_variant(struct bt_field
*field
);
339 @name Misc. functions
348 @defgroup ctfirintfield CTF IR integer field
350 @brief CTF IR integer field.
353 #include <babeltrace/ctf-ir/fields.h>
356 A CTF IR <strong><em>integer field</em></strong> is a @field which
357 holds a signed or unsigned integral value, and which is described by
360 An integer field object is considered \em unsigned if
361 bt_field_type_integer_get_signed() on its parent field type returns
362 0. Otherwise it is considered \em signed. You \em must use
363 bt_field_integer_unsigned_get_value() and
364 bt_field_integer_unsigned_set_value() with an unsigned integer
365 field, and bt_field_integer_signed_get_value() and
366 bt_field_integer_signed_set_value() with a signed integer field.
368 After you create an integer field with bt_field_create(), you
369 \em must set an integral value with
370 bt_field_integer_unsigned_set_value() or
371 bt_field_integer_signed_set_value() before you can get the
372 field's value with bt_field_integer_unsigned_get_value() or
373 bt_field_integer_signed_get_value().
375 @sa ctfirintfieldtype
378 @addtogroup ctfirintfield
383 @brief Returns the signed integral value of the @intfield
386 @param[in] integer_field Integer field of which to get the
387 signed integral value.
388 @param[out] value Returned signed integral value of
390 @returns 0 on success, or a negative value on
391 error, including if \p integer_field
392 has no integral value yet.
394 @prenotnull{integer_field}
396 @preisintfield{integer_field}
397 @pre bt_field_type_integer_get_signed() returns 1 for the parent
398 @ft of \p integer_field.
399 @pre \p integer_field contains a signed integral value previously
400 set with bt_field_integer_signed_set_value().
401 @postrefcountsame{integer_field}
403 @sa bt_field_integer_signed_set_value(): Sets the signed integral
404 value of a given integer field.
406 extern int bt_field_integer_signed_get_value(
407 struct bt_field
*integer_field
, int64_t *value
);
410 @brief Sets the signed integral value of the @intfield
411 \p integer_field to \p value.
413 @param[in] integer_field Integer field of which to set
414 the signed integral value.
415 @param[in] value New signed integral value of
417 @returns 0 on success, or a negative value on error.
419 @prenotnull{integer_field}
420 @preisintfield{integer_field}
421 @prehot{integer_field}
422 @pre bt_field_type_integer_get_signed() returns 1 for the parent
423 @ft of \p integer_field.
424 @postrefcountsame{integer_field}
426 @sa bt_field_integer_signed_get_value(): Returns the signed integral
427 value of a given integer field.
429 extern int bt_field_integer_signed_set_value(
430 struct bt_field
*integer_field
, int64_t value
);
433 @brief Returns the unsigned integral value of the @intfield
436 @param[in] integer_field Integer field of which to get the
437 unsigned integral value.
438 @param[out] value Returned unsigned integral value of
440 @returns 0 on success, or a negative value on
441 error, including if \p integer_field
442 has no integral value yet.
444 @prenotnull{integer_field}
446 @preisintfield{integer_field}
447 @pre bt_field_type_integer_get_signed() returns 0 for the parent
448 @ft of \p integer_field.
449 @pre \p integer_field contains an unsigned integral value previously
450 set with bt_field_integer_unsigned_set_value().
451 @postrefcountsame{integer_field}
453 @sa bt_field_integer_unsigned_set_value(): Sets the unsigned
454 integral value of a given integer field.
456 extern int bt_field_integer_unsigned_get_value(
457 struct bt_field
*integer_field
, uint64_t *value
);
460 @brief Sets the unsigned integral value of the @intfield
461 \p integer_field to \p value.
463 @param[in] integer_field Integer field of which to set
464 the unsigned integral value.
465 @param[in] value New unsigned integral value of
467 @returns 0 on success, or a negative value on error.
469 @prenotnull{integer_field}
470 @preisintfield{integer_field}
471 @prehot{integer_field}
472 @pre bt_field_type_integer_get_signed() returns 0 for the parent
473 @ft of \p integer_field.
474 @postrefcountsame{integer_field}
476 @sa bt_field_integer_unsigned_get_value(): Returns the unsigned
477 integral value of a given integer field.
479 extern int bt_field_integer_unsigned_set_value(
480 struct bt_field
*integer_field
, uint64_t value
);
485 @defgroup ctfirfloatfield CTF IR floating point number field
487 @brief CTF IR floating point number field.
490 #include <babeltrace/ctf-ir/fields.h>
493 A CTF IR <strong><em>floating point number field</em></strong> is a
494 @field which holds a floating point number value, and which is
495 described by a @floatft.
497 After you create a floating point number field with bt_field_create(), you
498 \em must set a floating point number value with
499 bt_field_floating_point_set_value() before you can get the
500 field's value with bt_field_floating_point_get_value().
502 @sa ctfirfloatfieldtype
505 @addtogroup ctfirfloatfield
510 @brief Returns the floating point number value of the @floatfield
513 @param[in] float_field Floating point number field of which to get the
514 floating point number value.
515 @param[out] value Returned floating point number value of
517 @returns 0 on success, or a negative value on error,
518 including if \p float_field has no floating
519 point number value yet.
521 @prenotnull{float_field}
523 @preisfloatfield{float_field}
524 @pre \p float_field contains a floating point number value previously
525 set with bt_field_floating_point_set_value().
526 @postrefcountsame{float_field}
528 @sa bt_field_floating_point_set_value(): Sets the floating point
529 number value of a given floating point number field.
531 extern int bt_field_floating_point_get_value(
532 struct bt_field
*float_field
, double *value
);
535 @brief Sets the floating point number value of the @floatfield
536 \p float_field to \p value.
538 @param[in] float_field Floating point number field of which to set
539 the floating point number value.
540 @param[in] value New floating point number value of
542 @returns 0 on success, or a negative value on error.
544 @prenotnull{float_field}
545 @preisfloatfield{float_field}
547 @postrefcountsame{float_field}
549 @sa bt_field_floating_point_get_value(): Returns the floating point
550 number value of a given floating point number field.
552 extern int bt_field_floating_point_set_value(
553 struct bt_field
*float_field
, double value
);
558 @brief Returns a @enumftiter on all the mappings of the field type of
559 \p enum_field which contain the current integral value of the
560 @enumfield \p enum_field in their range.
562 This function is the equivalent of using
563 bt_field_type_enumeration_find_mappings_by_unsigned_value() or
564 bt_field_type_enumeration_find_mappings_by_signed_value() with the
565 current integral value of \p enum_field.
567 @param[in] enum_field Enumeration field of which to get the mappings
568 containing the current integral value of \p
569 enum_field in their range.
570 @returns @enumftiter on the set of mappings of the field
571 type of \p enum_field which contain the current
572 integral value of \p enum_field in their range,
573 or \c NULL if no mappings were found or on
576 @prenotnull{enum_field}
577 @preisenumfield{enum_field}
578 @pre The wrapped integer field of \p enum_field contains an integral
580 @postrefcountsame{enum_field}
581 @postsuccessrefcountret1
582 @post <strong>On success</strong>, the returned @enumftiter can iterate
583 on at least one mapping.
585 extern struct bt_field_type_enumeration_mapping_iterator
*
586 bt_field_enumeration_get_mappings(struct bt_field
*enum_field
);
591 @defgroup ctfirstringfield CTF IR string field
593 @brief CTF IR string field.
596 #include <babeltrace/ctf-ir/fields.h>
599 A CTF IR <strong><em>string field</em></strong> is a @field which holds
600 a string value, and which is described by a @stringft.
602 Use bt_field_string_set_value() to set the current string value
603 of a string field object. You can also use bt_field_string_append()
604 and bt_field_string_append_len() to append a string to the current
605 value of a string field.
607 After you create a string field with bt_field_create(), you
608 \em must set a string value with
609 bt_field_string_set_value(), bt_field_string_append(), or
610 bt_field_string_append_len() before you can get the
611 field's value with bt_field_string_get_value().
613 @sa ctfirstringfieldtype
616 @addtogroup ctfirstringfield
621 @brief Returns the string value of the @stringfield \p string_field.
623 On success, \p string_field remains the sole owner of the returned
626 @param[in] string_field String field field of which to get the
628 @returns String value, or \c NULL on error.
630 @prenotnull{string_field}
632 @preisstringfield{string_field}
633 @pre \p string_field contains a string value previously
634 set with bt_field_string_set_value(),
635 bt_field_string_append(), or
636 bt_field_string_append_len().
637 @postrefcountsame{string_field}
639 @sa bt_field_string_set_value(): Sets the string value of a given
642 extern const char *bt_field_string_get_value(struct bt_field
*string_field
);
645 @brief Sets the string value of the @stringfield \p string_field to
648 @param[in] string_field String field of which to set
650 @param[in] value New string value of \p string_field (copied
652 @returns 0 on success, or a negative value on error.
654 @prenotnull{string_field}
656 @preisstringfield{string_field}
657 @prehot{string_field}
658 @postrefcountsame{string_field}
660 @sa bt_field_string_get_value(): Returns the string value of a
663 extern int bt_field_string_set_value(struct bt_field
*string_field
,
667 @brief Appends the string \p value to the current string value of
668 the @stringfield \p string_field.
670 This function is the equivalent of:
673 bt_field_string_append_len(string_field, value, strlen(value));
676 @param[in] string_field String field of which to append \p value to
678 @param[in] value String to append to the current string value
679 of \p string_field (copied on success).
680 @returns 0 on success, or a negative value on error.
682 @prenotnull{string_field}
684 @preisstringfield{string_field}
685 @prehot{string_field}
686 @postrefcountsame{string_field}
688 @sa bt_field_string_set_value(): Sets the string value of a given
691 extern int bt_field_string_append(struct bt_field
*string_field
,
695 @brief Appends the first \p length characters of \p value to the
696 current string value of the @stringfield \p string_field.
698 If \p string_field has no current string value, this function first
699 sets an empty string as the string value of \p string_field and then
700 appends the first \p length characters of \p value.
702 @param[in] string_field String field of which to append the first
703 \p length characters of \p value to
705 @param[in] value String containing the characters to append to
706 the current string value of \p string_field
708 @param[in] length Number of characters of \p value to append to
709 the current string value of \p string_field.
710 @returns 0 on success, or a negative value on error.
712 @prenotnull{string_field}
714 @preisstringfield{string_field}
715 @prehot{string_field}
716 @postrefcountsame{string_field}
718 @sa bt_field_string_set_value(): Sets the string value of a given
721 extern int bt_field_string_append_len(
722 struct bt_field
*string_field
, const char *value
,
723 unsigned int length
);
725 extern int bt_field_string_clear(struct bt_field
*string_field
);
730 @defgroup ctfirstructfield CTF IR structure field
732 @brief CTF IR structure field.
735 #include <babeltrace/ctf-ir/fields.h>
738 A CTF IR <strong><em>structure field</em></strong> is a @field which
739 contains an ordered list of zero or more named @fields which can be
740 different @fts, and which is described by a @structft.
742 To set the value of a specific field of a structure field, you need to
743 first get the field with bt_field_structure_get_field_by_name() or
744 bt_field_structure_get_field_by_index(). If you already have a
745 field object, you can assign it to a specific name within a structure
746 field with bt_field_structure_set_field_by_name().
748 @sa ctfirstructfieldtype
751 @addtogroup ctfirstructfield
755 extern struct bt_field
*bt_field_structure_borrow_field_by_name(
756 struct bt_field
*struct_field
, const char *name
);
758 extern struct bt_field
*bt_field_structure_borrow_field_by_index(
759 struct bt_field
*struct_field
, uint64_t index
);
764 @defgroup ctfirarrayfield CTF IR array field
766 @brief CTF IR array field.
769 #include <babeltrace/ctf-ir/fields.h>
772 A CTF IR <strong><em>array field</em></strong> is a @field which
773 contains an ordered list of zero or more @fields sharing the same @ft,
774 and which is described by a @arrayft.
776 To set the value of a specific field of an array field, you need to
777 first get the field with bt_field_array_get_field().
779 @sa ctfirarrayfieldtype
782 @addtogroup ctfirarrayfield
786 extern struct bt_field
*bt_field_array_borrow_field(
787 struct bt_field
*array_field
, uint64_t index
);
792 @defgroup ctfirseqfield CTF IR sequence field
794 @brief CTF IR sequence field.
797 #include <babeltrace/ctf-ir/fields.h>
800 A CTF IR <strong><em>sequence field</em></strong> is a @field which
801 contains an ordered list of zero or more @fields sharing the same @ft,
802 and which is described by a @seqft.
804 Before you can get a specific field of a sequence field with
805 bt_field_sequence_get_field(), you need to set its current length
806 @intfield with bt_field_sequence_set_length(). The integral value of
807 the length field of a sequence field indicates the number of fields
810 @sa ctfirseqfieldtype
813 @addtogroup ctfirseqfield
817 extern struct bt_field
*bt_field_sequence_borrow_field(
818 struct bt_field
*sequence_field
, uint64_t index
);
820 extern int64_t bt_field_sequence_get_length(struct bt_field
*sequence_field
);
823 @brief Sets the length @intfield of the @seqfield \p sequence_field
826 The current integral value of \p length_field indicates the number of
827 fields contained in \p sequence_field.
829 @param[in] sequence_field Sequence field of which to set the
831 @param[in] length_field Length field of \p sequence_field.
832 @returns 0 on success, or a negative value on error.
834 @prenotnull{sequence_field}
835 @prenotnull{length_field}
836 @preisseqfield{sequence_field}
837 @preisintfield{length_field}
838 @prehot{sequence_field}
839 @postrefcountsame{sequence_field}
840 @postsuccessrefcountinc{length_field}
842 @sa bt_field_sequence_get_length(): Returns the length field of a
843 given sequence field.
845 extern int bt_field_sequence_set_length(struct bt_field
*sequence_field
,
851 @defgroup ctfirvarfield CTF IR variant field
853 @brief CTF IR variant field.
856 #include <babeltrace/ctf-ir/fields.h>
859 A CTF IR <strong><em>variant field</em></strong> is a @field which
860 contains a current @field amongst one or more choices, and which is
861 described by a @varft.
863 Use bt_field_variant_get_field() to get the @field selected by
864 a specific tag @enumfield. Once you call this function, you can call
865 bt_field_variant_get_current_field() afterwards to get this last
868 @sa ctfirvarfieldtype
871 @addtogroup ctfirvarfield
875 extern int bt_field_variant_set_tag_signed(struct bt_field
*variant_field
,
878 extern int bt_field_variant_set_tag_unsigned(struct bt_field
*variant_field
,
881 extern int bt_field_variant_get_tag_signed(struct bt_field
*variant_field
,
884 extern int bt_field_variant_get_tag_unsigned(struct bt_field
*variant_field
,
887 extern struct bt_field
*bt_field_variant_borrow_current_field(
888 struct bt_field
*variant_field
);
896 #endif /* BABELTRACE_CTF_IR_FIELDS_H */