include/babeltrace/ctf-ir/field-types.h

   1 #ifndef BABELTRACE_CTF_IR_FIELD_TYPES_H
   2 #define BABELTRACE_CTF_IR_FIELD_TYPES_H
   3
   4 /*
   5  * BabelTrace - CTF IR: Event field types
   6  *
   7  * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   8  *
   9  * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
  10  *
  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:
  17  *
  18  * The above copyright notice and this permission notice shall be included in
  19  * all copies or substantial portions of the Software.
  20  *
  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
  27  * SOFTWARE.
  28  *
  29  * The Common Trace Format (CTF) Specification is available at
  30  * http://www.efficios.com/ctf
  31  */
  32
  33 #include <stdint.h>
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 /**
  40 @defgroup ctfirfieldtypes CTF IR field types
  41 @ingroup ctfir
  42 @brief CTF IR field types.
  43
  44 @code
  45 #include <babeltrace/ctf-ir/field-types.h>
  46 @endcode
  47
  48 A CTF IR <strong><em>field type</em></strong> is a field type that you
  49 can use to create concrete @fields.
  50
  51 You can create a @field object from a CTF IR field type object
  52 with bt_ctf_field_create().
  53
  54 In the CTF IR hierarchy, you can set the root field types of three
  55 objects:
  56
  57 - \ref ctfirtraceclass
  58   - Trace packet header field type: bt_ctf_trace_set_packet_header_type().
  59 - \ref ctfirstreamclass
  60   - Stream packet context field type:
  61     bt_ctf_stream_class_set_packet_context_type().
  62   - Stream event header field type:
  63     bt_ctf_stream_class_set_event_header_type().
  64   - Stream event context field type:
  65     bt_ctf_stream_class_set_event_context_type().
  66 - \ref ctfireventclass
  67   - Event context field type: bt_ctf_event_class_set_context_type().
  68   - Event payload field type: bt_ctf_event_class_set_payload_type().
  69
  70 As of Babeltrace \btversion, those six previous "root" field types
  71 \em must be @structft objects.
  72
  73 If, at any level within a given root field type, you add a @seqft or a
  74 @varft, you do not need to specify its associated length
  75 or tag field type: the length or tag string is enough for the Babeltrace
  76 system to resolve the needed field type depending on where this
  77 dynamic field type is located within the whole hierarchy. It is
  78 guaranteed that this automatic resolving is performed for all the field
  79 types contained in a given
  80 \link ctfirstreamclass CTF IR stream class\endlink (and in its
  81 children \link ctfireventclass CTF IR event classes\endlink) once you
  82 add it to a \link ctfirtraceclass CTF IR trace class\endlink with
  83 bt_ctf_trace_add_stream_class(). Once a stream class is the child of
  84 a trace class, this automatic resolving is performed for the field
  85 types of an event class when you add it with
  86 bt_ctf_stream_class_add_event_class(). If the system cannot find a path
  87 to a field in the hierarchy for a dynamic field type, the adding
  88 function fails.
  89
  90 The standard CTF field types are:
  91
  92 <table>
  93   <tr>
  94     <th>Type ID
  95     <th>CTF IR field type
  96     <th>CTF IR field which you can create from this field type
  97   </tr>
  98   <tr>
  99     <td>#BT_CTF_TYPE_ID_INTEGER
 100     <td>\ref ctfirintfieldtype
 101     <td>\ref ctfirintfield
 102   </tr>
 103   <tr>
 104     <td>#BT_CTF_TYPE_ID_FLOAT
 105     <td>\ref ctfirfloatfieldtype
 106     <td>\ref ctfirfloatfield
 107   </tr>
 108   <tr>
 109     <td>#BT_CTF_TYPE_ID_ENUM
 110     <td>\ref ctfirenumfieldtype
 111     <td>\ref ctfirenumfield
 112   </tr>
 113   <tr>
 114     <td>#BT_CTF_TYPE_ID_STRING
 115     <td>\ref ctfirstringfieldtype
 116     <td>\ref ctfirstringfield
 117   </tr>
 118   <tr>
 119     <td>#BT_CTF_TYPE_ID_STRUCT
 120     <td>\ref ctfirstructfieldtype
 121     <td>\ref ctfirstructfield
 122   </tr>
 123   <tr>
 124     <td>#BT_CTF_TYPE_ID_ARRAY
 125     <td>\ref ctfirarrayfieldtype
 126     <td>\ref ctfirarrayfield
 127   </tr>
 128   <tr>
 129     <td>#BT_CTF_TYPE_ID_SEQUENCE
 130     <td>\ref ctfirseqfieldtype
 131     <td>\ref ctfirseqfield
 132   </tr>
 133   <tr>
 134     <td>#BT_CTF_TYPE_ID_VARIANT
 135     <td>\ref ctfirvarfieldtype
 136     <td>\ref ctfirvarfield
 137   </tr>
 138 </table>
 139
 140 Each field type has its own <strong>type ID</strong> (see
 141 #bt_ctf_type_id). You get the type ID of a field type object
 142 with bt_ctf_field_type_get_type_id().
 143
 144 You can get a deep copy of a field type with bt_ctf_field_type_copy().
 145 This function resets, in the field type copy, the resolved field type
 146 of the dynamic field types. The automatic resolving can be done again
 147 when you eventually call bt_ctf_event_create(),
 148 bt_ctf_stream_class_add_event_class(), or
 149 bt_ctf_trace_add_stream_class().
 150
 151 You \em must always use bt_ctf_field_type_compare() to compare two
 152 field types. Since some parts of the Babeltrace system can copy field
 153 types behind the scenes, you \em cannot rely on a simple field type
 154 pointer comparison.
 155
 156 As with any Babeltrace object, CTF IR field type objects have
 157 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
 158 counts</a>. See \ref refs to learn more about the reference counting
 159 management of Babeltrace objects.
 160
 161 The following functions can \em freeze field type objects:
 162
 163 - bt_ctf_field_create() freezes its field type parameter.
 164 - bt_ctf_stream_class_add_event_class(), if its
 165   \link ctfirstreamclass CTF IR stream class\endlink parameter has a
 166   \link ctfirtraceclass CTF IR trace class\endlink parent, freezes
 167   the root field types of its
 168   \link ctfireventclass CTF IR event class\endlink parameter.
 169 - bt_ctf_trace_add_stream_class() freezes the root field types of the
 170   whole trace class hierarchy (trace class, children stream classes,
 171   and their children event classes).
 172 - bt_ctf_writer_create_stream() freezes the root field types of the
 173   whole CTF writer's trace class hierarchy.
 174 - bt_ctf_event_create() freezes the root field types of its event class
 175   parameter and of ther parent stream class of this event class.
 176
 177 You cannot modify a frozen field type object: it is considered
 178 immutable, except for \link refs reference counting\endlink.
 179
 180 @sa ctfirfields
 181 @sa \ref ctfirfieldtypesexamples "Examples"
 182
 183 @file
 184 @brief CTF IR field types type and functions.
 185 @sa ctfirfieldtypes
 186
 187 @addtogroup ctfirfieldtypes
 188 @{
 189 */
 190
 191 /**
 192 @struct bt_ctf_field_type
 193 @brief A CTF IR field type.
 194 @sa ctfirfieldtypes
 195 */
 196 struct bt_ctf_field_type;
 197 struct bt_ctf_event_class;
 198 struct bt_ctf_event;
 199 struct bt_ctf_field;
 200 struct bt_ctf_field_path;
 201
 202 /** @cond DOCUMENT */
 203
 204 /*
 205  * Babeltrace 1.x enumerations that were also used in CTF writer's API.
 206  * They are left here for backward compatibility reasons, but
 207  * enum bt_ctf_type_id and enum bt_ctf_string_encoding should be used
 208  * in new code. Both new enumerations are compatible with their legacy
 209  * counterpart.
 210  */
 211 enum ctf_type_id {
 212         CTF_TYPE_UNKNOWN = 0,
 213         CTF_TYPE_INTEGER,
 214         CTF_TYPE_FLOAT,
 215         CTF_TYPE_ENUM,
 216         CTF_TYPE_STRING,
 217         CTF_TYPE_STRUCT,
 218         CTF_TYPE_UNTAGGED_VARIANT,
 219         CTF_TYPE_VARIANT,
 220         CTF_TYPE_ARRAY,
 221         CTF_TYPE_SEQUENCE,
 222         NR_CTF_TYPES,
 223 };
 224
 225 /*
 226  * Old enum.
 227  */
 228 enum ctf_string_encoding {
 229         CTF_STRING_NONE = 0,
 230         CTF_STRING_UTF8,
 231         CTF_STRING_ASCII,
 232         CTF_STRING_UNKNOWN,
 233 };
 234
 235 /** @endcond */
 236
 237 /**
 238 @brief  CTF scope.
 239 */
 240 enum bt_ctf_scope {
 241         /// Unknown, used for errors.
 242         BT_CTF_SCOPE_UNKNOWN = -1,
 243
 244         /// Trace packet header.
 245         BT_CTF_SCOPE_TRACE_PACKET_HEADER = 1,
 246
 247         /// Stream packet context.
 248         BT_CTF_SCOPE_STREAM_PACKET_CONTEXT = 2,
 249
 250         /// Stream event header.
 251         BT_CTF_SCOPE_STREAM_EVENT_HEADER = 3,
 252
 253         /// Stream event context.
 254         BT_CTF_SCOPE_STREAM_EVENT_CONTEXT = 4,
 255
 256         /// Event context.
 257         BT_CTF_SCOPE_EVENT_CONTEXT = 5,
 258
 259         /// Event payload.
 260         BT_CTF_SCOPE_EVENT_PAYLOAD = 6,
 261
 262         /// @cond DOCUMENT
 263         BT_CTF_SCOPE_ENV = 0,
 264         BT_CTF_SCOPE_EVENT_FIELDS = 6,
 265         /// @endcond
 266 };
 267
 268 /**
 269 @name Type information
 270 @{
 271 */
 272
 273 /**
 274 @brief  Type ID of a @ft.
 275 */
 276 enum bt_ctf_type_id {
 277         /// Unknown, used for errors.
 278         BT_CTF_TYPE_ID_UNKNOWN = CTF_TYPE_UNKNOWN,
 279
 280         /// \ref ctfirintfieldtype
 281         BT_CTF_TYPE_ID_INTEGER = CTF_TYPE_INTEGER,
 282
 283         /// \ref ctfirfloatfieldtype
 284         BT_CTF_TYPE_ID_FLOAT = CTF_TYPE_FLOAT,
 285
 286         /// \ref ctfirenumfieldtype
 287         BT_CTF_TYPE_ID_ENUM = CTF_TYPE_ENUM,
 288
 289         /// \ref ctfirstringfieldtype
 290         BT_CTF_TYPE_ID_STRING = CTF_TYPE_STRING,
 291
 292         /// \ref ctfirstructfieldtype
 293         BT_CTF_TYPE_ID_STRUCT = CTF_TYPE_STRUCT,
 294
 295         /// @cond DOCUMENT
 296         BT_CTF_TYPE_ID_UNTAGGED_VARIANT = CTF_TYPE_UNTAGGED_VARIANT,
 297         /// @endcond
 298
 299         /// \ref ctfirarrayfieldtype
 300         BT_CTF_TYPE_ID_ARRAY = CTF_TYPE_ARRAY,
 301
 302         /// \ref ctfirseqfieldtype
 303         BT_CTF_TYPE_ID_SEQUENCE = CTF_TYPE_SEQUENCE,
 304
 305         /// \ref ctfirvarfieldtype
 306         BT_CTF_TYPE_ID_VARIANT = CTF_TYPE_VARIANT,
 307
 308         /// Number of enumeration entries.
 309         BT_CTF_NR_TYPE_IDS = NR_CTF_TYPES,
 310 };
 311
 312 /**
 313 @brief  Returns the type ID of the @ft \p field_type.
 314
 315 @param[in] field_type   Field type of which to get the type ID.
 316 @returns                Type ID of \p field_type,
 317                         or #BT_CTF_TYPE_ID_UNKNOWN on error.
 318
 319 @prenotnull{field_type}
 320 @postrefcountsame{field_type}
 321
 322 @sa #bt_ctf_type_id: CTF IR field type ID.
 323 @sa bt_ctf_field_type_is_integer(): Returns whether or not a given
 324         field type is a @intft.
 325 @sa bt_ctf_field_type_is_floating_point(): Returns whether or not a
 326         given field type is a @floatft.
 327 @sa bt_ctf_field_type_is_enumeration(): Returns whether or not a given
 328         field type is a @enumft.
 329 @sa bt_ctf_field_type_is_string(): Returns whether or not a given
 330         field type is a @stringft.
 331 @sa bt_ctf_field_type_is_structure(): Returns whether or not a given
 332         field type is a @structft.
 333 @sa bt_ctf_field_type_is_array(): Returns whether or not a given
 334         field type is a @arrayft.
 335 @sa bt_ctf_field_type_is_sequence(): Returns whether or not a given
 336         field type is a @seqft.
 337 @sa bt_ctf_field_type_is_variant(): Returns whether or not a given
 338         field type is a @varft.
 339 */
 340 extern enum bt_ctf_type_id bt_ctf_field_type_get_type_id(
 341                 struct bt_ctf_field_type *field_type);
 342
 343 /**
 344 @brief  Returns whether or not the @ft \p field_type is a @intft.
 345
 346 @param[in] field_type   Field type to check (can be \c NULL).
 347 @returns                1 if \p field_type is an integer field type,
 348                         or 0 otherwise (including if \p field_type is
 349                         \c NULL).
 350
 351 @prenotnull{field_type}
 352 @postrefcountsame{field_type}
 353
 354 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
 355         field type.
 356 */
 357 extern int bt_ctf_field_type_is_integer(struct bt_ctf_field_type *field_type);
 358
 359 /**
 360 @brief  Returns whether or not the @ft \p field_type is a @floatft.
 361
 362 @param[in] field_type   Field type to check (can be \c NULL).
 363 @returns                1 if \p field_type is a floating point
 364                         number field type,
 365                         or 0 otherwise (including if \p field_type is
 366                         \c NULL).
 367
 368 @postrefcountsame{field_type}
 369
 370 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
 371         field type.
 372 */
 373 extern int bt_ctf_field_type_is_floating_point(struct bt_ctf_field_type *field_type);
 374
 375 /**
 376 @brief  Returns whether or not the @ft \p field_type is a @enumft.
 377
 378 @param[in] field_type   Field type to check (can be \c NULL).
 379 @returns                1 if \p field_type is an enumeration field type,
 380                         or 0 otherwise (including if \p field_type is
 381                         \c NULL).
 382
 383 @postrefcountsame{field_type}
 384
 385 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
 386         field type.
 387 */
 388 extern int bt_ctf_field_type_is_enumeration(struct bt_ctf_field_type *field_type);
 389
 390 /**
 391 @brief  Returns whether or not the @ft \p field_type is a @stringft.
 392
 393 @param[in] field_type   Field type to check (can be \c NULL).
 394 @returns                1 if \p field_type is a string field type,
 395                         or 0 otherwise (including if \p field_type is
 396                         \c NULL).
 397
 398 @postrefcountsame{field_type}
 399
 400 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
 401         field type.
 402 */
 403 extern int bt_ctf_field_type_is_string(struct bt_ctf_field_type *field_type);
 404
 405 /**
 406 @brief  Returns whether or not the @ft \p field_type is a @structft.
 407
 408 @param[in] field_type   Field type to check (can be \c NULL).
 409 @returns                1 if \p field_type is a structure field type,
 410                         or 0 otherwise (including if \p field_type is
 411                         \c NULL).
 412
 413 @postrefcountsame{field_type}
 414
 415 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
 416         field type.
 417 */
 418 extern int bt_ctf_field_type_is_structure(struct bt_ctf_field_type *field_type);
 419
 420 /**
 421 @brief  Returns whether or not the @ft \p field_type is a @arrayft.
 422
 423 @param[in] field_type   Field type to check (can be \c NULL).
 424 @returns                1 if \p field_type is an array field type,
 425                         or 0 otherwise (including if \p field_type is
 426                         \c NULL).
 427
 428 @postrefcountsame{field_type}
 429
 430 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
 431         field type.
 432 */
 433 extern int bt_ctf_field_type_is_array(struct bt_ctf_field_type *field_type);
 434
 435 /**
 436 @brief  Returns whether or not the @ft \p field_type is a @seqft.
 437
 438 @param[in] field_type   Field type to check (can be \c NULL).
 439 @returns                1 if \p field_type is a sequence field type,
 440                         or 0 otherwise (including if \p field_type is
 441                         \c NULL).
 442
 443 @postrefcountsame{field_type}
 444
 445 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
 446         field type.
 447 */
 448 extern int bt_ctf_field_type_is_sequence(struct bt_ctf_field_type *field_type);
 449
 450 /**
 451 @brief  Returns whether or not the @ft \p field_type is a @varft.
 452
 453 @param[in] field_type   Field type to check (can be \c NULL).
 454 @returns                1 if \p field_type is a variant field type,
 455                         or 0 otherwise (including if \p field_type is
 456                         \c NULL).
 457
 458 @postrefcountsame{field_type}
 459
 460 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
 461         field type.
 462 */
 463 extern int bt_ctf_field_type_is_variant(struct bt_ctf_field_type *field_type);
 464
 465 /** @} */
 466
 467 /**
 468 @name Common properties types and functions
 469 @{
 470 */
 471
 472 /**
 473 @brief  <a href="https://en.wikipedia.org/wiki/Endianness">Byte order</a>
 474         of a @ft.
 475 */
 476 enum bt_ctf_byte_order {
 477         /// Unknown, used for errors.
 478         BT_CTF_BYTE_ORDER_UNKNOWN = -1,
 479
 480         /*
 481          * Note that native, in the context of the CTF specification, is defined
 482          * as "the byte order described in the trace" and does not mean that the
 483          * host's endianness will be used.
 484          */
 485         /// Native (default) byte order.
 486         BT_CTF_BYTE_ORDER_NATIVE = 0,
 487
 488         /// Little-endian.
 489         BT_CTF_BYTE_ORDER_LITTLE_ENDIAN,
 490
 491         /// Big-endian.
 492         BT_CTF_BYTE_ORDER_BIG_ENDIAN,
 493
 494         /// Network byte order (big-endian).
 495         BT_CTF_BYTE_ORDER_NETWORK,
 496 };
 497
 498 /**
 499 @brief  String encoding of a @ft.
 500 */
 501 enum bt_ctf_string_encoding {
 502         /// Unknown, used for errors.
 503         BT_CTF_STRING_ENCODING_UNKNOWN = CTF_STRING_UNKNOWN,
 504
 505         /// No encoding.
 506         BT_CTF_STRING_ENCODING_NONE = CTF_STRING_NONE,
 507
 508         /// <a href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a>.
 509         BT_CTF_STRING_ENCODING_UTF8 = CTF_STRING_UTF8,
 510
 511         /// <a href="https://en.wikipedia.org/wiki/ASCII">ASCII</a>.
 512         BT_CTF_STRING_ENCODING_ASCII = CTF_STRING_ASCII,
 513 };
 514
 515 /**
 516 @brief  Returns the alignment of the @fields described by
 517         the @ft \p field_type.
 518
 519 @param[in] field_type   Field type which describes the
 520                         fields of which to get the alignment.
 521 @returns                Alignment of the fields described by
 522                         \p field_type, or a negative value on error.
 523
 524 @prenotnull{field_type}
 525 @postrefcountsame{field_type}
 526
 527 @sa bt_ctf_field_type_set_alignment(): Sets the alignment
 528         of the fields described by a given field type.
 529 */
 530 extern int bt_ctf_field_type_get_alignment(
 531                 struct bt_ctf_field_type *field_type);
 532
 533 /**
 534 @brief  Sets the alignment of the @fields described by the
 535         @ft \p field_type to \p alignment.
 536
 537 \p alignment \em must be greater than 0 and a power of two.
 538
 539 @param[in] field_type   Field type which describes the fields of
 540                         which to set the alignment.
 541 @param[in] alignment    Alignment of the fields described by
 542                         \p field_type.
 543 @returns                0 on success, or a negative value on error.
 544
 545 @prenotnull{field_type}
 546 @prehot{field_type}
 547 @pre \p alignment is greater than 0 and a power of two.
 548 @postrefcountsame{field_type}
 549
 550 @sa bt_ctf_field_type_get_alignment(): Returns the alignment of the
 551         fields described by a given field type.
 552 */
 553 extern int bt_ctf_field_type_set_alignment(struct bt_ctf_field_type *field_type,
 554                 unsigned int alignment);
 555
 556 /**
 557 @brief  Returns the byte order of the @fields described by
 558         the @ft \p field_type.
 559
 560 You can only call this function if \p field_type is a @intft, a
 561 @floatft, or a @enumft.
 562
 563 @param[in] field_type   Field type which describes the
 564                         fields of which to get the byte order.
 565 @returns                Byte order of the fields described by
 566                         \p field_type, or #BT_CTF_BYTE_ORDER_UNKNOWN on
 567                         error.
 568
 569 @prenotnull{field_type}
 570 @pre \p field_type is a @intft, a @floatft, or a @enumft.
 571 @postrefcountsame{field_type}
 572
 573 @sa bt_ctf_field_type_set_byte_order(): Sets the byte order
 574         of the fields described by a given field type.
 575 */
 576 extern enum bt_ctf_byte_order bt_ctf_field_type_get_byte_order(
 577                 struct bt_ctf_field_type *field_type);
 578
 579 /**
 580 @brief  Sets the byte order of the @fields described by the
 581         @ft \p field_type to \p byte_order.
 582
 583 If \p field_type is a compound field type, this function also
 584 recursively sets the byte order of its children to \p byte_order.
 585
 586 @param[in] field_type   Field type which describes the fields of
 587                         which to set the byte order.
 588 @param[in] byte_order   Alignment of the fields described by
 589                         \p field_type.
 590 @returns                0 on success, or a negative value on error.
 591
 592 @prenotnull{field_type}
 593 @prehot{field_type}
 594 @pre \p byte_order is #BT_CTF_BYTE_ORDER_NATIVE,
 595         #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN, #BT_CTF_BYTE_ORDER_BIG_ENDIAN,
 596         or #BT_CTF_BYTE_ORDER_NETWORK.
 597 @postrefcountsame{field_type}
 598
 599 @sa bt_ctf_field_type_get_byte_order(): Returns the byte order of the
 600         fields described by a given field type.
 601 */
 602 extern int bt_ctf_field_type_set_byte_order(
 603                 struct bt_ctf_field_type *field_type,
 604                 enum bt_ctf_byte_order byte_order);
 605
 606 /** @} */
 607
 608 /**
 609 @name Utility functions
 610 @{
 611 */
 612
 613 /**
 614 @brief  Returns whether or not the @ft \p field_type_a
 615         is equivalent to the field type \p field_type_b.
 616
 617 You \em must use this function to compare two field types: it is not
 618 safe to compare two pointer values directly, because, for internal
 619 reasons, some parts of the Babeltrace system can copy user field types
 620 and discard the original ones.
 621
 622 @param[in] field_type_a Field type to compare to \p field_type_b.
 623 @param[in] field_type_b Field type to compare to \p field_type_a.
 624 @returns                0 if \p field_type_a is equivalent to
 625                         \p field_type_b, 1 if they are not equivalent,
 626                         or a negative value on error.
 627
 628 @prenotnull{field_type_a}
 629 @prenotnull{field_type_b}
 630 @postrefcountsame{field_type_a}
 631 @postrefcountsame{field_type_b}
 632 */
 633 extern int bt_ctf_field_type_compare(struct bt_ctf_field_type *field_type_a,
 634                 struct bt_ctf_field_type *field_type_b);
 635
 636 /**
 637 @brief  Creates a \em deep copy of the @ft \p field_type.
 638
 639 You can copy a frozen field type: the resulting copy is
 640 <em>not frozen</em>.
 641
 642 This function resets the tag field type of a copied @varft. The
 643 automatic field resolving which some functions of the API perform
 644 can set it again when the returned field type is used (learn more
 645 in the detailed description of this module).
 646
 647 @param[in] field_type   Field type to copy.
 648 @returns                Deep copy of \p field_type on success,
 649                         or \c NULL on error.
 650
 651 @prenotnull{field_type}
 652 @postrefcountsame{field_type}
 653 @postsuccessrefcountret1
 654 @post <strong>On success</strong>, the returned field type is not frozen.
 655 */
 656 extern struct bt_ctf_field_type *bt_ctf_field_type_copy(
 657                 struct bt_ctf_field_type *field_type);
 658
 659 /** @} */
 660
 661 /** @} */
 662
 663 /**
 664 @defgroup ctfirintfieldtype CTF IR integer field type
 665 @ingroup ctfirfieldtypes
 666 @brief CTF IR integer field type.
 667
 668 @code
 669 #include <babeltrace/ctf-ir/field-types.h>
 670 @endcode
 671
 672 A CTF IR <strong><em>integer field type</em></strong> is a field type that
 673 you can use to create concrete @intfield objects.
 674
 675 You can create an integer field type
 676 with bt_ctf_field_type_integer_create().
 677
 678 An integer field type has the following properties:
 679
 680 <table>
 681   <tr>
 682     <th>Property
 683     <th>Value at creation
 684     <th>Getter
 685     <th>Setter
 686   </tr>
 687   <tr>
 688     <td>\b Alignment (bits) of the described integer fields
 689     <td>1
 690     <td>bt_ctf_field_type_get_alignment()
 691     <td>bt_ctf_field_type_set_alignment()
 692   </tr>
 693   <tr>
 694     <td><strong>Byte order</strong> of the described integer fields
 695     <td>#BT_CTF_BYTE_ORDER_NATIVE
 696     <td>bt_ctf_field_type_get_byte_order()
 697     <td>bt_ctf_field_type_set_byte_order()
 698   </tr>
 699   <tr>
 700     <td><strong>Storage size</strong> (bits) of the described
 701         integer fields
 702     <td>Specified at creation
 703     <td>bt_ctf_field_type_integer_get_size()
 704     <td>None: specified at creation (bt_ctf_field_type_integer_create())
 705   </tr>
 706   <tr>
 707     <td><strong>Signedness</strong> of the described integer fields
 708     <td>Unsigned
 709     <td>bt_ctf_field_type_integer_get_signed()
 710     <td>bt_ctf_field_type_integer_set_signed()
 711   </tr>
 712   <tr>
 713     <td><strong>Preferred display base</strong> of the described
 714         integer fields
 715     <td>#BT_CTF_INTEGER_BASE_DECIMAL
 716     <td>bt_ctf_field_type_integer_get_base()
 717     <td>bt_ctf_field_type_integer_set_base()
 718   </tr>
 719   <tr>
 720     <td>\b Encoding of the described integer fields
 721     <td>#BT_CTF_STRING_ENCODING_NONE
 722     <td>bt_ctf_field_type_integer_get_encoding()
 723     <td>bt_ctf_field_type_integer_set_encoding()
 724   </tr>
 725   <tr>
 726     <td><strong>Mapped
 727         \link ctfirclockclass CTF IR clock class\endlink</strong>
 728     <td>None
 729     <td>bt_ctf_field_type_integer_get_mapped_clock_class()
 730     <td>bt_ctf_field_type_integer_set_mapped_clock_class()
 731   </tr>
 732 </table>
 733
 734 @sa ctfirintfield
 735 @sa ctfirfieldtypes
 736 @sa \ref ctfirfieldtypesexamples_intfieldtype "Examples"
 737
 738 @addtogroup ctfirintfieldtype
 739 @{
 740 */
 741
 742 /**
 743 @brief  Preferred display base (radix) of a @intft.
 744 */
 745 enum bt_ctf_integer_base {
 746         /// Unknown, used for errors.
 747         BT_CTF_INTEGER_BASE_UNKNOWN = -1,
 748
 749         /// Binary.
 750         BT_CTF_INTEGER_BASE_BINARY = 2,
 751
 752         /// Octal.
 753         BT_CTF_INTEGER_BASE_OCTAL = 8,
 754
 755         /// Decimal.
 756         BT_CTF_INTEGER_BASE_DECIMAL = 10,
 757
 758         /// Hexadecimal.
 759         BT_CTF_INTEGER_BASE_HEXADECIMAL = 16,
 760 };
 761
 762 /**
 763 @brief  Creates a default @intft with \p size bits as the storage size
 764         of the @intfields it describes.
 765
 766 @param[in] size Storage size (bits) of the described integer fields.
 767 @returns        Created integer field type, or \c NULL on error.
 768
 769 @pre \p size is greater than 0 and lesser than or equal to 64.
 770 @postsuccessrefcountret1
 771 */
 772 extern struct bt_ctf_field_type *bt_ctf_field_type_integer_create(
 773                 unsigned int size);
 774
 775 /**
 776 @brief  Returns the storage size, in bits, of the @intfields
 777         described by the @intft \p int_field_type.
 778
 779 @param[in] int_field_type       Integer field type which describes the
 780                                 integer fields of which to get the
 781                                 storage size.
 782 @returns                        Storage size (bits) of the integer
 783                                 fields described by \p int_field_type,
 784                                 or a negative value on error.
 785
 786 @prenotnull{int_field_type}
 787 @preisintft{int_field_type}
 788 @postrefcountsame{int_field_type}
 789 */
 790 extern int bt_ctf_field_type_integer_get_size(
 791                 struct bt_ctf_field_type *int_field_type);
 792
 793 /**
 794 @brief  Returns whether or not the @intfields described by the @intft
 795         \p int_field_type are signed.
 796
 797 @param[in] int_field_type       Integer field type which describes the
 798                                 integer fields of which to get the
 799                                 signedness.
 800 @returns                        1 if the integer fields described by
 801                                 \p int_field_type are signed, 0 if they
 802                                 are unsigned, or a negative value on
 803                                 error.
 804
 805 @prenotnull{int_field_type}
 806 @preisintft{int_field_type}
 807 @postrefcountsame{int_field_type}
 808
 809 @sa bt_ctf_field_type_integer_set_signed(): Sets the signedness of the
 810         integer fields described by a given integer field type.
 811 */
 812 extern int bt_ctf_field_type_integer_get_signed(
 813                 struct bt_ctf_field_type *int_field_type);
 814
 815 /**
 816 @brief  Sets whether or not the @intfields described by
 817         the @intft \p int_field_type are signed.
 818
 819 @param[in] int_field_type       Integer field type which describes the
 820                                 integer fields of which to set the
 821                                 signedness.
 822 @param[in] is_signed            Signedness of the integer fields
 823                                 described by \p int_field_type; 0 means
 824                                 \em unsigned, 1 means \em signed.
 825 @returns                        0 on success, or a negative value on error.
 826
 827 @prenotnull{int_field_type}
 828 @preisintft{int_field_type}
 829 @prehot{int_field_type}
 830 @pre \p is_signed is 0 or 1.
 831 @postrefcountsame{event_class}
 832
 833 @sa bt_ctf_field_type_integer_get_signed(): Returns the signedness of
 834         the integer fields described by a given integer field type.
 835 */
 836 extern int bt_ctf_field_type_integer_set_signed(
 837                 struct bt_ctf_field_type *int_field_type, int is_signed);
 838
 839 /**
 840 @brief  Returns the preferred display base (radix) of the @intfields
 841         described by the @intft \p int_field_type.
 842
 843 @param[in] int_field_type       Integer field type which describes the
 844                                 integer fields of which to get the
 845                                 preferred display base.
 846 @returns                        Preferred display base of the integer
 847                                 fields described by \p int_field_type,
 848                                 or #BT_CTF_INTEGER_BASE_UNKNOWN on
 849                                 error.
 850
 851 @prenotnull{int_field_type}
 852 @preisintft{int_field_type}
 853 @postrefcountsame{int_field_type}
 854
 855 @sa bt_ctf_field_type_integer_set_base(): Sets the preferred display
 856         base of the integer fields described by a given integer field
 857         type.
 858 */
 859 extern enum bt_ctf_integer_base bt_ctf_field_type_integer_get_base(
 860                 struct bt_ctf_field_type *int_field_type);
 861
 862 /**
 863 @brief  Sets the preferred display base (radix) of the @intfields
 864         described by the @intft \p int_field_type to \p base.
 865
 866 @param[in] int_field_type       Integer field type which describes the
 867                                 integer fields of which to set the
 868                                 preferred display base.
 869 @param[in] base                 Preferred display base of the integer
 870                                 fields described by \p int_field_type.
 871 @returns                        0 on success, or a negative value on error.
 872
 873 @prenotnull{int_field_type}
 874 @preisintft{int_field_type}
 875 @prehot{int_field_type}
 876 @pre \p base is #BT_CTF_INTEGER_BASE_BINARY, #BT_CTF_INTEGER_BASE_OCTAL,
 877         #BT_CTF_INTEGER_BASE_DECIMAL, or
 878         #BT_CTF_INTEGER_BASE_HEXADECIMAL.
 879 @postrefcountsame{int_field_type}
 880
 881 @sa bt_ctf_field_type_integer_get_base(): Returns the preferred display
 882         base of the integer fields described by a given
 883         integer field type.
 884 */
 885 extern int bt_ctf_field_type_integer_set_base(
 886                 struct bt_ctf_field_type *int_field_type,
 887                 enum bt_ctf_integer_base base);
 888
 889 /**
 890 @brief  Returns the encoding of the @intfields described by
 891         the @intft \p int_field_type.
 892
 893 @param[in] int_field_type       Integer field type which describes the
 894                                 integer fields of which to get the
 895                                 encoding.
 896 @returns                        Encoding of the integer
 897                                 fields described by \p int_field_type,
 898                                 or #BT_CTF_STRING_ENCODING_UNKNOWN on
 899                                 error.
 900
 901 @prenotnull{int_field_type}
 902 @preisintft{int_field_type}
 903 @postrefcountsame{int_field_type}
 904
 905 @sa bt_ctf_field_type_integer_set_encoding(): Sets the encoding
 906         of the integer fields described by a given integer field type.
 907 */
 908 extern enum bt_ctf_string_encoding bt_ctf_field_type_integer_get_encoding(
 909                 struct bt_ctf_field_type *int_field_type);
 910
 911 /**
 912 @brief  Sets the encoding of the @intfields described by the @intft
 913         \p int_field_type to \p encoding.
 914
 915 You can use this property, in CTF IR, to create "text" @arrayfts or
 916 @seqfts. A text array field type is array field type with an unsigned,
 917 8-bit integer field type having an encoding as its element field type.
 918
 919 @param[in] int_field_type       Integer field type which describes the
 920                                 integer fields of which to set the
 921                                 encoding.
 922 @param[in] encoding             Encoding of the integer
 923                                 fields described by \p int_field_type.
 924 @returns                        0 on success, or a negative value on error.
 925
 926 @prenotnull{int_field_type}
 927 @preisintft{int_field_type}
 928 @prehot{int_field_type}
 929 @pre \p encoding is #BT_CTF_STRING_ENCODING_NONE,
 930         #BT_CTF_STRING_ENCODING_ASCII, or
 931         #BT_CTF_STRING_ENCODING_UTF8.
 932 @postrefcountsame{int_field_type}
 933
 934 @sa bt_ctf_field_type_integer_get_encoding(): Returns the encoding of
 935         the integer fields described by a given integer field type.
 936 */
 937 extern int bt_ctf_field_type_integer_set_encoding(
 938                 struct bt_ctf_field_type *int_field_type,
 939                 enum bt_ctf_string_encoding encoding);
 940
 941 /**
 942 @brief  Returns the \link ctfirclockclass CTF IR clock class\endlink
 943         mapped to the @intft \p int_field_type.
 944
 945 The mapped clock class, if any, indicates the class of the clock which
 946 an @intfield described by \p int_field_type should sample or update.
 947 This mapped clock class is only indicative.
 948
 949 @param[in] int_field_type       Integer field type of which to get the
 950                                 mapped clock class.
 951 @returns                        Mapped clock class of \p int_field_type,
 952                                 or \c NULL if there's no mapped clock
 953                                 class or on error.
 954
 955 @prenotnull{int_field_type}
 956 @preisintft{int_field_type}
 957 @postrefcountsame{int_field_type}
 958 @postsuccessrefcountretinc
 959
 960 @sa bt_ctf_field_type_integer_set_mapped_clock_class(): Sets the mapped
 961         clock class of a given integer field type.
 962 */
 963 extern struct bt_ctf_clock_class *bt_ctf_field_type_integer_get_mapped_clock_class(
 964                 struct bt_ctf_field_type *int_field_type);
 965
 966 /**
 967 @brief  Sets the \link ctfirclockclass CTF IR clock class\endlink mapped
 968         to the @intft \p int_field_type to \p clock_class.
 969
 970 The mapped clock class, if any, indicates the class of the clock which
 971 an integer field described by \p int_field_type should sample or update.
 972 This mapped clock class is only indicative.
 973
 974 @param[in] int_field_type       Integer field type of which to set the
 975                                 mapped clock class.
 976 @param[in] clock_class          Mapped clock class of \p int_field_type.
 977 @returns                        0 on success, or a negative value on error.
 978
 979 @prenotnull{int_field_type}
 980 @prenotnull{clock_class}
 981 @preisintft{int_field_type}
 982 @prehot{int_field_type}
 983 @postrefcountsame{int_field_type}
 984 @postsuccessrefcountinc{clock_class}
 985
 986 @sa bt_ctf_field_type_integer_get_mapped_clock_class(): Returns the mapped
 987         clock class of a given integer field type.
 988 */
 989 extern int bt_ctf_field_type_integer_set_mapped_clock_class(
 990                 struct bt_ctf_field_type *int_field_type,
 991                 struct bt_ctf_clock_class *clock_class);
 992
 993 /** @} */
 994
 995 /**
 996 @defgroup ctfirfloatfieldtype CTF IR floating point number field type
 997 @ingroup ctfirfieldtypes
 998 @brief CTF IR floating point number field type.
 999
1000 @code
1001 #include <babeltrace/ctf-ir/field-types.h>
1002 @endcode
1003
1004 A CTF IR <strong><em>floating point number field type</em></strong> is
1005 a field type that you can use to create concrete @floatfields.
1006
1007 You can create a floating point number field type
1008 with bt_ctf_field_type_floating_point_create().
1009
1010 A floating point number field type has the following properties:
1011
1012 <table>
1013   <tr>
1014     <th>Property
1015     <th>Value at creation
1016     <th>Getter
1017     <th>Setter
1018   </tr>
1019   <tr>
1020     <td>\b Alignment (bits) of the described floating point
1021         number fields
1022     <td>1
1023     <td>bt_ctf_field_type_get_alignment()
1024     <td>bt_ctf_field_type_set_alignment()
1025   </tr>
1026   <tr>
1027     <td><strong>Byte order</strong> of the described floating point
1028         number fields
1029     <td>#BT_CTF_BYTE_ORDER_NATIVE
1030     <td>bt_ctf_field_type_get_byte_order()
1031     <td>bt_ctf_field_type_set_byte_order()
1032   </tr>
1033   <tr>
1034     <td><strong>Exponent storage size</strong> (bits) of the described
1035         floating point number fields
1036     <td>8
1037     <td>bt_ctf_field_type_floating_point_get_exponent_digits()
1038     <td>bt_ctf_field_type_floating_point_set_exponent_digits()
1039   </tr>
1040   <tr>
1041     <td><strong>Mantissa and sign storage size</strong> (bits) of the
1042         described floating point number fields
1043     <td>24 (23-bit mantissa, 1-bit sign)
1044     <td>bt_ctf_field_type_floating_point_get_mantissa_digits()
1045     <td>bt_ctf_field_type_floating_point_set_mantissa_digits()
1046   </tr>
1047 </table>
1048
1049 @sa ctfirfloatfield
1050 @sa ctfirfieldtypes
1051 @sa \ref ctfirfieldtypesexamples_floatfieldtype "Examples"
1052
1053 @addtogroup ctfirfloatfieldtype
1054 @{
1055 */
1056
1057 /**
1058 @brief  Creates a default @floatft.
1059
1060 @returns        Created floating point number field type,
1061                 or \c NULL on error.
1062
1063 @postsuccessrefcountret1
1064 */
1065 extern struct bt_ctf_field_type *bt_ctf_field_type_floating_point_create(void);
1066
1067 /**
1068 @brief  Returns the exponent storage size of the @floatfields
1069         described by the @floatft \p float_field_type.
1070
1071 @param[in] float_field_type     Floating point number field type which
1072                                 describes the floating point number
1073                                 fields of which to get the exponent
1074                                 storage size.
1075 @returns                        Exponent storage size of the
1076                                 floating point number fields
1077                                 described by \p float_field_type,
1078                                 or a negative value on error.
1079
1080 @prenotnull{float_field_type}
1081 @preisfloatft{float_field_type}
1082 @postrefcountsame{float_field_type}
1083
1084 @sa bt_ctf_field_type_floating_point_set_exponent_digits(): Sets the
1085         exponent storage size of the floating point number fields
1086         described by a given floating point number field type.
1087 */
1088 extern int bt_ctf_field_type_floating_point_get_exponent_digits(
1089                 struct bt_ctf_field_type *float_field_type);
1090
1091 /**
1092 @brief  Sets the exponent storage size of the @floatfields described by
1093         the @floatft \p float_field_type to \p exponent_size.
1094
1095 As of Babeltrace \btversion, \p exponent_size can only be 8 or 11.
1096
1097 @param[in] float_field_type     Floating point number field type which
1098                                 describes the floating point number
1099                                 fields of which to set the exponent
1100                                 storage size.
1101 @param[in] exponent_size        Exponent storage size of the floating
1102                                 point number fields described by \p
1103                                 float_field_type.
1104 @returns                        0 on success, or a negative value on error.
1105
1106 @prenotnull{float_field_type}
1107 @preisfloatft{float_field_type}
1108 @prehot{float_field_type}
1109 @pre \p exponent_size is 8 or 11.
1110 @postrefcountsame{float_field_type}
1111
1112 @sa bt_ctf_field_type_floating_point_get_exponent_digits(): Returns the
1113         exponent storage size of the floating point number fields
1114         described by a given floating point number field type.
1115 */
1116 extern int bt_ctf_field_type_floating_point_set_exponent_digits(
1117                 struct bt_ctf_field_type *float_field_type,
1118                 unsigned int exponent_size);
1119
1120 /**
1121 @brief  Returns the mantissa and sign storage size of the @floatfields
1122         described by the @floatft \p float_field_type.
1123
1124 On success, the returned value is the sum of the mantissa \em and
1125 sign storage sizes.
1126
1127 @param[in] float_field_type     Floating point number field type which
1128                                 describes the floating point number
1129                                 fields of which to get the mantissa and
1130                                 sign storage size.
1131 @returns                        Mantissa and sign storage size of the
1132                                 floating point number fields
1133                                 described by \p float_field_type,
1134                                 or a negative value on error.
1135
1136 @prenotnull{float_field_type}
1137 @preisfloatft{float_field_type}
1138 @postrefcountsame{float_field_type}
1139
1140 @sa bt_ctf_field_type_floating_point_set_mantissa_digits(): Sets the
1141         mantissa and size storage size of the floating point number
1142         fields described by a given floating point number field type.
1143 */
1144 extern int bt_ctf_field_type_floating_point_get_mantissa_digits(
1145                 struct bt_ctf_field_type *float_field_type);
1146
1147 /**
1148 @brief  Sets the mantissa and sign storage size of the @floatfields
1149         described by the @floatft \p float_field_type to \p
1150         mantissa_sign_size.
1151
1152 As of Babeltrace \btversion, \p mantissa_sign_size can only be 24 or 53.
1153
1154 @param[in] float_field_type     Floating point number field type which
1155                                 describes the floating point number
1156                                 fields of which to set the mantissa and
1157                                 sign storage size.
1158 @param[in] mantissa_sign_size   Mantissa and sign storage size of the
1159                                 floating point number fields described
1160                                 by \p float_field_type.
1161 @returns                        0 on success, or a negative value on error.
1162
1163 @prenotnull{float_field_type}
1164 @preisfloatft{float_field_type}
1165 @prehot{float_field_type}
1166 @pre \p mantissa_sign_size is 24 or 53.
1167 @postrefcountsame{float_field_type}
1168
1169 @sa bt_ctf_field_type_floating_point_get_mantissa_digits(): Returns the
1170         mantissa and sign storage size of the floating point number
1171         fields described by a given floating point number field type.
1172 */
1173 extern int bt_ctf_field_type_floating_point_set_mantissa_digits(
1174                 struct bt_ctf_field_type *float_field_type,
1175                 unsigned int mantissa_sign_size);
1176
1177 /** @} */
1178
1179 struct bt_ctf_field_type_enumeration_mapping_iterator *
1180                 bt_ctf_field_type_enumeration_find_mappings_by_name(
1181                         struct bt_ctf_field_type *type,
1182                         const char *name);
1183
1184 struct bt_ctf_field_type_enumeration_mapping_iterator *
1185                 bt_ctf_field_type_enumeration_find_mappings_by_signed_value(
1186                         struct bt_ctf_field_type *type,
1187                         int64_t value);
1188
1189 struct bt_ctf_field_type_enumeration_mapping_iterator *
1190                 bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(
1191                         struct bt_ctf_field_type *type,
1192                         uint64_t value);
1193
1194 int bt_ctf_field_type_enumeration_mapping_iterator_get_name(
1195                 struct bt_ctf_field_type_enumeration_mapping_iterator *iter,
1196                 const char **mapping_name);
1197
1198 int bt_ctf_field_type_enumeration_mapping_iterator_get_signed(
1199                 struct bt_ctf_field_type_enumeration_mapping_iterator *iter,
1200                 const char **mapping_name, int64_t *lower, int64_t *upper);
1201
1202 int bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(
1203                 struct bt_ctf_field_type_enumeration_mapping_iterator *iter,
1204                 const char **mapping_name, uint64_t *lower, uint64_t *upper);
1205
1206 int bt_ctf_field_type_enumeration_mapping_iterator_next(
1207                 struct bt_ctf_field_type_enumeration_mapping_iterator *iter);
1208
1209 /**
1210 @defgroup ctfirenumfieldtype CTF IR enumeration field type
1211 @ingroup ctfirfieldtypes
1212 @brief CTF IR enumeration field type.
1213
1214 @code
1215 #include <babeltrace/ctf-ir/field-types.h>
1216 @endcode
1217
1218 A CTF IR <strong><em>enumeration field type</em></strong> is
1219 a field type that you can use to create concrete @enumfields.
1220
1221 You can create an enumeration field type with
1222 bt_ctf_field_type_enumeration_create(). This function needs a @intft
1223 which represents the storage field type of the created enumeration field
1224 type. In other words, an enumeration field type wraps an integer field
1225 type and adds label-value mappings to it.
1226
1227 An enumeration mapping has:
1228
1229 - A <strong>name</strong>.
1230 - A <strong>range of values</strong> given by a beginning and an ending
1231   value, both included in the range.
1232
1233 You can add a mapping to an enumeration field type with
1234 bt_ctf_field_type_enumeration_add_mapping() or
1235 bt_ctf_field_type_enumeration_add_mapping_unsigned(), depending on the
1236 signedness of the wrapped @intft.
1237
1238 Many mappings can share the same name, and the ranges of a given
1239 enumeration field type are allowed to overlap. For example,
1240 this is a valid set of mappings:
1241
1242 @verbatim
1243 APPLE  -> [  3, 19]
1244 BANANA -> [-15,  1]
1245 CHERRY -> [ 25, 34]
1246 APPLE  -> [ 55, 55]
1247 @endverbatim
1248
1249 The following set of mappings is also valid:
1250
1251 @verbatim
1252 APPLE  -> [  3, 19]
1253 BANANA -> [-15,  1]
1254 CHERRY -> [ 25, 34]
1255 APPLE  -> [ 30, 55]
1256 @endverbatim
1257
1258 Here, the range of the second \c APPLE mapping overlaps the range of
1259 the \c CHERRY mapping.
1260
1261 @sa ctfirenumfield
1262 @sa ctfirfieldtypes
1263
1264 @addtogroup ctfirenumfieldtype
1265 @{
1266 */
1267
1268 /**
1269 @brief  Creates a default @enumft wrapping the @intft \p int_field_type.
1270
1271 @param[in] int_field_type       Integer field type wrapped by the
1272                                 created enumeration field type.
1273 @returns                        Created enumeration field type,
1274                                 or \c NULL on error.
1275
1276 @prenotnull{int_field_type}
1277 @preisintft{int_field_type}
1278 @postsuccessrefcountinc{int_field_type}
1279 @postsuccessrefcountret1
1280 */
1281 extern struct bt_ctf_field_type *bt_ctf_field_type_enumeration_create(
1282                 struct bt_ctf_field_type *int_field_type);
1283
1284 /**
1285 @brief  Returns the @intft wrapped by the @enumft \p enum_field_type.
1286
1287 @param[in] enum_field_type      Enumeration field type of which to get
1288                                 the wrapped integer field type.
1289 @returns                        Integer field type wrapped by
1290                                 \p enum_field_type, or \c NULL on
1291                                 error.
1292
1293 @prenotnull{enum_field_type}
1294 @preisenumft{enum_field_type}
1295 @postrefcountsame{enum_field_type}
1296 @postsuccessrefcountretinc
1297 */
1298 extern
1299 struct bt_ctf_field_type *bt_ctf_field_type_enumeration_get_container_type(
1300                 struct bt_ctf_field_type *enum_field_type);
1301
1302 /**
1303 @brief  Returns the number of mappings contained in the
1304         @enumft \p enum_field_type.
1305
1306 @param[in] enum_field_type      Enumeration field type of which to get
1307                                 the number of contained mappings.
1308 @returns                        Number of mappings contained in
1309                                 \p enum_field_type, or a negative
1310                                 value on error.
1311
1312 @prenotnull{enum_field_type}
1313 @preisenumft{enum_field_type}
1314 @postrefcountsame{enum_field_type}
1315 */
1316 extern int bt_ctf_field_type_enumeration_get_mapping_count(
1317                 struct bt_ctf_field_type *enum_field_type);
1318
1319 extern int bt_ctf_field_type_enumeration_get_mapping_name(
1320                 struct bt_ctf_field_type *enum_field_type, int index,
1321                 const char **name);
1322
1323 /**
1324 @brief  Returns the signed mapping of the @enumft
1325         \p enum_field_type at index \p index.
1326
1327 The @intft wrapped by \p enum_field_type, as returned by
1328 bt_ctf_field_type_enumeration_get_container_type(), must be \b signed
1329 to use this function.
1330
1331 On success, \p enum_field_type remains the sole owner of \p *name.
1332
1333 @param[in] enum_field_type      Enumeration field type of which to get
1334                                 the mapping at index \p index.
1335 @param[in] index              Index of the mapping to get from
1336                                 \p enum_field_type.
1337 @param[out] name                Returned name of the mapping at index
1338                                 \p index.
1339 @param[out] range_begin         Returned beginning of the range
1340                                 (included) of the mapping at index \p
1341                                 index.
1342 @param[out] range_end           Returned end of the range (included) of
1343                                 the mapping at index \p index.
1344 @returns                        0 on success, or a negative value on error.
1345
1346 @prenotnull{enum_field_type}
1347 @prenotnull{name}
1348 @prenotnull{range_begin}
1349 @prenotnull{range_end}
1350 @preisenumft{enum_field_type}
1351 @pre The wrapped @intft of \p enum_field_type is signed.
1352 @pre \p index is lesser than the number of mappings contained in the
1353         enumeration field type \p enum_field_type (see
1354         bt_ctf_field_type_enumeration_get_mapping_count()).
1355 @postrefcountsame{enum_field_type}
1356
1357 @sa bt_ctf_field_type_enumeration_get_mapping_signed(): Returns the
1358         signed mapping contained by a given enumeration field type
1359         at a given index.
1360 */
1361 extern int bt_ctf_field_type_enumeration_get_mapping_signed(
1362                 struct bt_ctf_field_type *enum_field_type, int index,
1363                 const char **name, int64_t *range_begin, int64_t *range_end);
1364
1365 /**
1366 @brief  Returns the unsigned mapping of the @enumft
1367         \p enum_field_type at index \p index.
1368
1369 The @intft wrapped by \p enum_field_type, as returned by
1370 bt_ctf_field_type_enumeration_get_container_type(), must be
1371 \b unsigned to use this function.
1372
1373 On success, \p enum_field_type remains the sole owner of \p *name.
1374
1375 @param[in] enum_field_type      Enumeration field type of which to get
1376                                 the mapping at index \p index.
1377 @param[in] index              Index of the mapping to get from
1378                                 \p enum_field_type.
1379 @param[out] name                Returned name of the mapping at index
1380                                 \p index.
1381 @param[out] range_begin         Returned beginning of the range
1382                                 (included) of the mapping at index \p
1383                                 index.
1384 @param[out] range_end           Returned end of the range (included) of
1385                                 the mapping at index \p index.
1386 @returns                        0 on success, or a negative value on error.
1387
1388 @prenotnull{enum_field_type}
1389 @prenotnull{name}
1390 @prenotnull{range_begin}
1391 @prenotnull{range_end}
1392 @preisenumft{enum_field_type}
1393 @pre The wrapped @intft of \p enum_field_type is unsigned.
1394 @pre \p index is lesser than the number of mappings contained in the
1395         enumeration field type \p enum_field_type (see
1396         bt_ctf_field_type_enumeration_get_mapping_count()).
1397 @postrefcountsame{enum_field_type}
1398
1399 @sa bt_ctf_field_type_enumeration_get_mapping_unsigned(): Returns the
1400         unsigned mapping contained by a given enumeration field type
1401         at a given index.
1402 */
1403 extern int bt_ctf_field_type_enumeration_get_mapping_unsigned(
1404                 struct bt_ctf_field_type *enum_field_type, int index,
1405                 const char **name, uint64_t *range_begin,
1406                 uint64_t *range_end);
1407
1408 /**
1409 @brief  Adds a mapping to the @enumft \p enum_field_type which maps the
1410         name \p name to the signed range \p range_begin (included) to
1411         \p range_end (included).
1412
1413 Make \p range_begin and \p range_end the same value to add a mapping
1414 to a single value.
1415
1416 The @intft wrapped by \p enum_field_type, as returned by
1417 bt_ctf_field_type_enumeration_get_container_type(), must be
1418 \b signed to use this function.
1419
1420 A mapping in \p enum_field_type can exist with the name \p name.
1421
1422 @param[in] enum_field_type      Enumeration field type to which to add
1423                                 a mapping.
1424 @param[in] name                 Name of the mapping to add (copied
1425                                 on success).
1426 @param[in] range_begin          Beginning of the range of the mapping
1427                                 (included).
1428 @param[in] range_end            End of the range of the mapping
1429                                 (included).
1430 @returns                        0 on success, or a negative value on error.
1431
1432 @prenotnull{enum_field_type}
1433 @prenotnull{name}
1434 @preisenumft{enum_field_type}
1435 @pre The wrapped @intft of \p enum_field_type is signed.
1436 @pre \p range_end is greater than or equal to \p range_begin.
1437 @postrefcountsame{enum_field_type}
1438
1439 @sa bt_ctf_field_type_enumeration_add_mapping_unsigned(): Adds an
1440         unsigned mapping to a given enumeration field type.
1441 */
1442 extern int bt_ctf_field_type_enumeration_add_mapping(
1443                 struct bt_ctf_field_type *enum_field_type, const char *name,
1444                 int64_t range_begin, int64_t range_end);
1445
1446 /**
1447 @brief  Adds a mapping to the @enumft \p enum_field_type which maps
1448         the name \p name to the unsigned
1449         range \p range_begin (included) to \p range_end (included).
1450
1451 Make \p range_begin and \p range_end the same value to add a mapping
1452 to a single value.
1453
1454 The @intft wrapped by \p enum_field_type, as returned by
1455 bt_ctf_field_type_enumeration_get_container_type(), must be
1456 \b unsigned to use this function.
1457
1458 A mapping in \p enum_field_type can exist with the name \p name.
1459
1460 @param[in] enum_field_type      Enumeration field type to which to add
1461                                 a mapping.
1462 @param[in] name                 Name of the mapping to add (copied
1463                                 on success).
1464 @param[in] range_begin          Beginning of the range of the mapping
1465                                 (included).
1466 @param[in] range_end            End of the range of the mapping
1467                                 (included).
1468 @returns                        0 on success, or a negative value on error.
1469
1470 @prenotnull{enum_field_type}
1471 @prenotnull{name}
1472 @preisenumft{enum_field_type}
1473 @pre The wrapped @intft of \p enum_field_type is unsigned.
1474 @pre \p range_end is greater than or equal to \p range_begin.
1475 @postrefcountsame{enum_field_type}
1476
1477 @sa bt_ctf_field_type_enumeration_add_mapping(): Adds a signed
1478         mapping to a given enumeration field type.
1479 */
1480 extern int bt_ctf_field_type_enumeration_add_mapping_unsigned(
1481                 struct bt_ctf_field_type *enum_field_type, const char *name,
1482                 uint64_t range_begin, uint64_t range_end);
1483
1484 /** @} */
1485
1486 /**
1487 @defgroup ctfirstringfieldtype CTF IR string field type
1488 @ingroup ctfirfieldtypes
1489 @brief CTF IR string field type.
1490
1491 @code
1492 #include <babeltrace/ctf-ir/field-types.h>
1493 @endcode
1494
1495 A CTF IR <strong><em>string field type</em></strong> is a field type that
1496 you can use to create concrete @stringfields.
1497
1498 You can create a string field type
1499 with bt_ctf_field_type_string_create().
1500
1501 A string field type has only one property: the \b encoding of its
1502 described @stringfields. By default, the encoding of the string fields
1503 described by a string field type is #BT_CTF_STRING_ENCODING_UTF8. You
1504 can set the encoding of the string fields described by a string field
1505 type with bt_ctf_field_type_string_set_encoding().
1506
1507 @sa ctfirstringfield
1508 @sa ctfirfieldtypes
1509
1510 @addtogroup ctfirstringfieldtype
1511 @{
1512 */
1513
1514 /**
1515 @brief  Creates a default @stringft.
1516
1517 @returns        Created string field type, or \c NULL on error.
1518
1519 @postsuccessrefcountret1
1520 */
1521 extern struct bt_ctf_field_type *bt_ctf_field_type_string_create(void);
1522
1523 /**
1524 @brief  Returns the encoding of the @stringfields described by
1525         the @stringft \p string_field_type.
1526
1527 @param[in] string_field_type    String field type which describes the
1528                                 string fields of which to get the
1529                                 encoding.
1530 @returns                        Encoding of the string
1531                                 fields described by \p string_field_type,
1532                                 or #BT_CTF_STRING_ENCODING_UNKNOWN on
1533                                 error.
1534
1535 @prenotnull{string_field_type}
1536 @preisstringft{string_field_type}
1537 @postrefcountsame{string_field_type}
1538
1539 @sa bt_ctf_field_type_string_set_encoding(): Sets the encoding
1540         of the string fields described by a given string field type.
1541 */
1542 extern enum bt_ctf_string_encoding bt_ctf_field_type_string_get_encoding(
1543                 struct bt_ctf_field_type *string_field_type);
1544
1545 /**
1546 @brief  Sets the encoding of the @stringfields described by the
1547         @stringft \p string_field_type to \p encoding.
1548
1549 @param[in] string_field_type    String field type which describes the
1550                                 string fields of which to set the
1551                                 encoding.
1552 @param[in] encoding             Encoding of the string fields described
1553                                 by \p string_field_type.
1554 @returns                        0 on success, or a negative value on error.
1555
1556 @prenotnull{string_field_type}
1557 @preisstringft{string_field_type}
1558 @prehot{string_field_type}
1559 @pre \p encoding is #BT_CTF_STRING_ENCODING_ASCII or
1560         #BT_CTF_STRING_ENCODING_UTF8.
1561 @postrefcountsame{string_field_type}
1562
1563 @sa bt_ctf_field_type_string_get_encoding(): Returns the encoding of
1564         the string fields described by a given string field type.
1565 */
1566 extern int bt_ctf_field_type_string_set_encoding(
1567                 struct bt_ctf_field_type *string_field_type,
1568                 enum bt_ctf_string_encoding encoding);
1569
1570 /** @} */
1571
1572 /**
1573 @defgroup ctfirstructfieldtype CTF IR structure field type
1574 @ingroup ctfirfieldtypes
1575 @brief CTF IR structure field type.
1576
1577 @code
1578 #include <babeltrace/ctf-ir/field-types.h>
1579 @endcode
1580
1581 A CTF IR <strong><em>structure field type</em></strong> is
1582 a field type that you can use to create concrete @structfields.
1583
1584 You can create a structure field type
1585 with bt_ctf_field_type_structure_create(). This function creates
1586 an empty structure field type, with no fields.
1587
1588 You can add a field to a structure field type with
1589 bt_ctf_field_type_structure_add_field(). Two fields in a structure
1590 field type cannot have the same name.
1591
1592 You can set the \em minimum alignment of the structure fields described
1593 by a structure field type with the common
1594 bt_ctf_field_type_set_alignment() function. The \em effective alignment
1595 of the structure fields described by a structure field type, as per
1596 <a href="http://diamon.org/ctf/">CTF</a>, is the \em maximum value amongst
1597 the effective alignments of all its fields. Note that the effective
1598 alignment of @varfields is always 1.
1599
1600 You can set the byte order of <em>all the contained fields</em>,
1601 recursively, of a structure field type with the common
1602 bt_ctf_field_type_set_byte_order() function.
1603
1604 @sa ctfirstructfield
1605 @sa ctfirfieldtypes
1606
1607 @addtogroup ctfirstructfieldtype
1608 @{
1609 */
1610
1611 /**
1612 @brief  Creates a default, empty @structft.
1613
1614 @returns                        Created structure field type,
1615                                 or \c NULL on error.
1616
1617 @postsuccessrefcountret1
1618 */
1619 extern struct bt_ctf_field_type *bt_ctf_field_type_structure_create(void);
1620
1621 /**
1622 @brief  Returns the number of fields contained in the
1623         @structft \p struct_field_type.
1624
1625 @param[in] struct_field_type    Structure field type of which to get
1626                                 the number of contained fields.
1627 @returns                        Number of fields contained in
1628                                 \p struct_field_type, or a negative
1629                                 value on error.
1630
1631 @prenotnull{struct_field_type}
1632 @preisstructft{struct_field_type}
1633 @postrefcountsame{struct_field_type}
1634 */
1635 extern int bt_ctf_field_type_structure_get_field_count(
1636                 struct bt_ctf_field_type *struct_field_type);
1637
1638 /**
1639 @brief  Returns the field of the @structft \p struct_field_type
1640         at index \p index.
1641
1642 On success, the field's type is placed in \p *field_type if
1643 \p field_type is not \c NULL. The field's name is placed in
1644 \p *field_name if \p field_name is not \c NULL.
1645 \p struct_field_type remains the sole owner of \p *field_name.
1646
1647 @param[in] struct_field_type    Structure field type of which to get
1648                                 the field at index \p index.
1649 @param[out] field_name          Returned name of the field at index
1650                                 \p index (can be \c NULL).
1651 @param[out] field_type          Returned field type of the field
1652                                 at index \p index (can be \c NULL).
1653 @param[in] index              Index of the field to get from
1654                                 \p struct_field_type.
1655 @returns                        0 on success, or a negative value on error.
1656
1657 @prenotnull{struct_field_type}
1658 @preisstructft{struct_field_type}
1659 @pre \p index is lesser than the number of fields contained in the
1660         structure field type \p struct_field_type (see
1661         bt_ctf_field_type_structure_get_field_count()).
1662 @postrefcountsame{struct_field_type}
1663 @post <strong>On success</strong>, the returned field's type is placed
1664         in \p *field_type and its reference count is incremented.
1665
1666 @sa bt_ctf_field_type_structure_get_field_type_by_name(): Finds a
1667         structure field type's field by name.
1668 */
1669 extern int bt_ctf_field_type_structure_get_field(
1670                 struct bt_ctf_field_type *struct_field_type,
1671                 const char **field_name, struct bt_ctf_field_type **field_type,
1672                 int index);
1673
1674 /**
1675 @brief  Returns the type of the field named \p field_name found in
1676         the @structft \p struct_field_type.
1677
1678 @param[in] struct_field_type    Structure field type of which to get
1679                                 a field's type.
1680 @param[in] field_name           Name of the field to find.
1681 @returns                        Type of the field named \p field_name in
1682                                 \p struct_field_type, or
1683                                 \c NULL on error.
1684
1685 @prenotnull{struct_field_type}
1686 @prenotnull{field_name}
1687 @preisstructft{struct_field_type}
1688 @postrefcountsame{struct_field_type}
1689 @postsuccessrefcountretinc
1690
1691 @sa bt_ctf_field_type_structure_get_field(): Finds a
1692         structure field type's field by index.
1693 */
1694 extern
1695 struct bt_ctf_field_type *bt_ctf_field_type_structure_get_field_type_by_name(
1696                 struct bt_ctf_field_type *struct_field_type,
1697                 const char *field_name);
1698
1699 /**
1700 @brief  Adds a field named \p field_name with the @ft
1701         \p field_type to the @structft \p struct_field_type.
1702
1703 On success, \p field_type becomes the child of \p struct_field_type.
1704
1705 This function adds the new field after the current last field of
1706 \p struct_field_type (append mode).
1707
1708 You \em cannot add a field named \p field_name if there's already a
1709 field named \p field_name in \p struct_field_type.
1710
1711 @param[in] struct_field_type    Structure field type to which to add
1712                                 a new field.
1713 @param[in] field_type           Field type of the field to add to
1714                                 \p struct_field_type.
1715 @param[in] field_name           Name of the field to add to
1716                                 \p struct_field_type
1717                                 (copied on success).
1718 @returns                        0 on success, or a negative value on error.
1719
1720 @prenotnull{struct_field_type}
1721 @prenotnull{field_type}
1722 @prenotnull{field_name}
1723 @preisstructft{struct_field_type}
1724 @pre \p field_type is not and does not contain \p struct_field_type,
1725         recursively, as a field's type.
1726 @prehot{struct_field_type}
1727 @postrefcountsame{struct_field_type}
1728 @postsuccessrefcountinc{field_type}
1729 */
1730 extern int bt_ctf_field_type_structure_add_field(
1731                 struct bt_ctf_field_type *struct_field_type,
1732                 struct bt_ctf_field_type *field_type,
1733                 const char *field_name);
1734
1735 /** @} */
1736
1737 /**
1738 @defgroup ctfirarrayfieldtype CTF IR array field type
1739 @ingroup ctfirfieldtypes
1740 @brief CTF IR array field type.
1741
1742 @code
1743 #include <babeltrace/ctf-ir/field-types.h>
1744 @endcode
1745
1746 A CTF IR <strong><em>array field type</em></strong> is a field type that
1747 you can use to create concrete @arrayfields.
1748
1749 You can create an array field type
1750 with bt_ctf_field_type_array_create(). This function needs
1751 the @ft of the fields contained by the array fields described by the
1752 array field type to create.
1753
1754 @sa ctfirarrayfield
1755 @sa ctfirfieldtypes
1756
1757 @addtogroup ctfirarrayfieldtype
1758 @{
1759 */
1760
1761 /**
1762 @brief  Creates a default @arrayft with
1763         \p element_field_type as the field type of the fields contained
1764         in its described @arrayfields of length \p length.
1765
1766 @param[in] element_field_type   Field type of the fields contained in
1767                                 the array fields described by the
1768                                 created array field type.
1769 @param[in] length               Length of the array fields described by
1770                                 the created array field type.
1771 @returns                        Created array field type, or
1772                                 \c NULL on error.
1773
1774 @prenotnull{element_field_type}
1775 @postsuccessrefcountinc{element_field_type}
1776 @postsuccessrefcountret1
1777 */
1778 extern struct bt_ctf_field_type *bt_ctf_field_type_array_create(
1779                 struct bt_ctf_field_type *element_field_type,
1780                 unsigned int length);
1781
1782 /**
1783 @brief  Returns the @ft of the @fields contained in
1784         the @arrayfields described by the @arrayft \p array_field_type.
1785
1786 @param[in] array_field_type     Array field type of which to get
1787                                 the type of the fields contained in its
1788                                 described array fields.
1789 @returns                        Type of the fields contained in the
1790                                 array fields described by
1791                                 \p array_field_type, or \c NULL
1792                                 on error.
1793
1794 @prenotnull{array_field_type}
1795 @preisarrayft{array_field_type}
1796 @postrefcountsame{array_field_type}
1797 @postsuccessrefcountretinc
1798 */
1799 extern struct bt_ctf_field_type *bt_ctf_field_type_array_get_element_type(
1800                 struct bt_ctf_field_type *array_field_type);
1801
1802 /**
1803 @brief  Returns the number of @fields contained in the
1804         @arrayfields described by the @arrayft \p array_field_type.
1805
1806 @param[in] array_field_type     Array field type of which to get
1807                                 the number of fields contained in its
1808                                 described array fields.
1809 @returns                        Number of fields contained in the
1810                                 array fields described by
1811                                 \p array_field_type, or a negative value
1812                                 on error.
1813
1814 @prenotnull{array_field_type}
1815 @preisarrayft{array_field_type}
1816 @postrefcountsame{array_field_type}
1817 */
1818 extern int64_t bt_ctf_field_type_array_get_length(
1819                 struct bt_ctf_field_type *array_field_type);
1820
1821 /** @} */
1822
1823 /**
1824 @defgroup ctfirseqfieldtype CTF IR sequence field type
1825 @ingroup ctfirfieldtypes
1826 @brief CTF IR sequence field type.
1827
1828 @code
1829 #include <babeltrace/ctf-ir/field-types.h>
1830 @endcode
1831
1832 A CTF IR <strong><em>sequence field type</em></strong> is
1833 a field type that you can use to create concrete @seqfields.
1834
1835 You can create a sequence field type with
1836 bt_ctf_field_type_sequence_create(). This function needs the @ft
1837 of the fields contained by the sequence fields described by the created
1838 sequence field type. This function also needs the length name of the
1839 sequence field type to create. The length name is used to automatically
1840 resolve the length's field type. See \ref ctfirfieldtypes to learn more
1841 about the automatic resolving.
1842
1843 @sa ctfirseqfield
1844 @sa ctfirfieldtypes
1845
1846 @addtogroup ctfirseqfieldtype
1847 @{
1848 */
1849
1850 /**
1851 @brief  Creates a default @seqft with \p element_field_type as the
1852         @ft of the @fields contained in its described @seqfields
1853         with the length name \p length_name.
1854
1855 \p length_name can be an absolute or relative reference. See
1856 <a href="http://diamon.org/ctf/">CTF</a> for more details.
1857
1858 @param[in] element_field_type   Field type of the fields contained in
1859                                 the sequence fields described by the
1860                                 created sequence field type.
1861 @param[in] length_name          Length name (copied on success).
1862 @returns                        Created array field type, or
1863                                 \c NULL on error.
1864
1865 @prenotnull{element_field_type}
1866 @prenotnull{length_name}
1867 @postsuccessrefcountinc{element_field_type}
1868 @postsuccessrefcountret1
1869 */
1870 extern struct bt_ctf_field_type *bt_ctf_field_type_sequence_create(
1871                 struct bt_ctf_field_type *element_field_type,
1872                 const char *length_name);
1873
1874 /**
1875 @brief  Returns the @ft of the @fields contained in the @seqft
1876         described by the @seqft \p sequence_field_type.
1877
1878 @param[in] sequence_field_type  Sequence field type of which to get
1879                                 the type of the fields contained in its
1880                                 described sequence fields.
1881 @returns                        Type of the fields contained in the
1882                                 sequence fields described by
1883                                 \p sequence_field_type, or \c NULL
1884                                 on error.
1885
1886 @prenotnull{sequence_field_type}
1887 @preisseqft{sequence_field_type}
1888 @postrefcountsame{sequence_field_type}
1889 @postsuccessrefcountretinc
1890 */
1891 extern struct bt_ctf_field_type *bt_ctf_field_type_sequence_get_element_type(
1892                 struct bt_ctf_field_type *sequence_field_type);
1893
1894 /**
1895 @brief  Returns the length name of the @seqft \p sequence_field_type.
1896
1897 On success, \p sequence_field_type remains the sole owner of
1898 the returned string.
1899
1900 @param[in] sequence_field_type  Sequence field type of which to get the
1901                                 length name.
1902 @returns                        Length name of \p sequence_field_type,
1903                                 or \c NULL on error.
1904
1905 @prenotnull{sequence_field_type}
1906 @preisseqft{sequence_field_type}
1907
1908 @sa bt_ctf_field_type_sequence_get_length_field_path(): Returns the
1909         length's CTF IR field path of a given sequence field type.
1910 */
1911 extern const char *bt_ctf_field_type_sequence_get_length_field_name(
1912                 struct bt_ctf_field_type *sequence_field_type);
1913
1914 /**
1915 @brief  Returns the length's CTF IR field path of the @seqft
1916         \p sequence_field_type.
1917
1918 The length's field path of a sequence field type is set when automatic
1919 resolving is performed (see \ref ctfirfieldtypes).
1920
1921 @param[in] sequence_field_type  Sequence field type of which to get the
1922                                 length's field path.
1923 @returns                        Length's field path of
1924                                 \p sequence_field_type, or
1925                                 \c NULL if the length's field path is
1926                                 not set yet is not set or on error.
1927
1928 @prenotnull{sequence_field_type}
1929 @preisseqft{sequence_field_type}
1930 @postsuccessrefcountretinc
1931
1932 @sa bt_ctf_field_type_sequence_get_length_field_name(): Returns the
1933         length's name of a given sequence field type.
1934 */
1935 extern struct bt_ctf_field_path *bt_ctf_field_type_sequence_get_length_field_path(
1936                 struct bt_ctf_field_type *sequence_field_type);
1937
1938 /** @} */
1939
1940 /**
1941 @defgroup ctfirvarfieldtype CTF IR variant field type
1942 @ingroup ctfirfieldtypes
1943 @brief CTF IR variant field type.
1944
1945 @code
1946 #include <babeltrace/ctf-ir/field-types.h>
1947 @endcode
1948
1949 A CTF IR <strong><em>variant field type</em></strong> is
1950 a field type that you can use to create concrete @varfields.
1951
1952 You can create a variant field type with
1953 bt_ctf_field_type_variant_create(). This function expects you to pass
1954 both the tag's @enumft and the tag name of the variant field type to
1955 create. The tag's field type is optional, as the Babeltrace system can
1956 automatically resolve it using the tag name. You can leave the tag name
1957 to \c NULL initially, and set it later with
1958 bt_ctf_field_type_variant_set_tag_name(). The tag name must be set when
1959 the variant field type is frozen. See \ref ctfirfieldtypes to learn more
1960 about the automatic resolving and the conditions under which a field
1961 type can be frozen.
1962
1963 You can add a field to a variant field type with
1964 bt_ctf_field_type_variant_add_field(). All the field names of a
1965 variant field type \em must exist as mapping names in its tag's @enumft.
1966
1967 The effective alignment of the @varfields described by a
1968 variant field type is always 1, but the individual fields of a
1969 @varfield can have custom alignments.
1970
1971 You can set the byte order of <em>all the contained fields</em>,
1972 recursively, of a variant field type with the common
1973 bt_ctf_field_type_set_byte_order() function.
1974
1975 @sa ctfirvarfield
1976 @sa ctfirfieldtypes
1977
1978 @addtogroup ctfirvarfieldtype
1979 @{
1980 */
1981
1982 /**
1983 @brief  Creates a default, empty @varft with the tag's @enumft
1984         \p tag_field_type and the tag name \p tag_name.
1985
1986 \p tag_field_type can be \c NULL; the tag's field type can be
1987 automatically resolved from the variant field type's tag name (see
1988 \ref ctfirfieldtypes). If \p tag_name is \c NULL, it \em must be set
1989 with bt_ctf_field_type_variant_set_tag_name() \em before the variant
1990 field type is frozen.
1991
1992 \p tag_name can be an absolute or relative reference. See
1993 <a href="http://diamon.org/ctf/">CTF</a> for more details.
1994
1995 @param[in] tag_field_type       Tag's enumeration field type
1996                                 (can be \c NULL).
1997 @param[in] tag_name             Tag name (copied on success,
1998                                 can be \c NULL).
1999 @returns                        Created variant field type, or
2000                                 \c NULL on error.
2001
2002 @pre \p tag_field_type is an enumeration field type or \c NULL.
2003 @post <strong>On success, if \p tag_field_type is not \c NULL</strong>,
2004         its reference count is incremented.
2005 @postsuccessrefcountret1
2006 */
2007 extern struct bt_ctf_field_type *bt_ctf_field_type_variant_create(
2008                 struct bt_ctf_field_type *tag_field_type,
2009                 const char *tag_name);
2010
2011 /**
2012 @brief  Returns the tag's @enumft of the @varft \p variant_field_type.
2013
2014 @param[in] variant_field_type   Variant field type of which to get
2015                                 the tag's enumeration field type.
2016 @returns                        Tag's enumeration field type of
2017                                 \p variant_field_type, or \c NULL if the
2018                                 tag's field type is not set or on
2019                                 error.
2020
2021 @prenotnull{variant_field_type}
2022 @preisvarft{variant_field_type}
2023 @postrefcountsame{variant_field_type}
2024 @postsuccessrefcountretinc
2025 */
2026 extern struct bt_ctf_field_type *bt_ctf_field_type_variant_get_tag_type(
2027                 struct bt_ctf_field_type *variant_field_type);
2028
2029 /**
2030 @brief  Returns the tag name of the @varft \p variant_field_type.
2031
2032 On success, \p variant_field_type remains the sole owner of
2033 the returned string.
2034
2035 @param[in] variant_field_type   Variant field type of which to get the
2036                                 tag name.
2037 @returns                        Tag name of \p variant_field_type, or
2038                                 \c NULL if the tag name is not set or
2039                                 on error.
2040
2041 @prenotnull{variant_field_type}
2042 @preisvarft{variant_field_type}
2043
2044 @sa bt_ctf_field_type_variant_set_tag_name(): Sets the tag name of
2045         a given variant field type.
2046 @sa bt_ctf_field_type_variant_get_tag_field_path(): Returns the tag's
2047         CTF IR field path of a given variant field type.
2048 */
2049 extern const char *bt_ctf_field_type_variant_get_tag_name(
2050                 struct bt_ctf_field_type *variant_field_type);
2051
2052 /**
2053 @brief  Sets the tag name of the @varft \p variant_field_type.
2054
2055 \p tag_name can be an absolute or relative reference. See
2056 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2057
2058 @param[in] variant_field_type   Variant field type of which to set
2059                                 the tag name.
2060 @param[in] tag_name             Tag name of \p variant_field_type
2061                                 (copied on success).
2062 @returns                        0 on success, or a negative value on error.
2063
2064 @prenotnull{variant_field_type}
2065 @prenotnull{name}
2066 @prehot{variant_field_type}
2067 @postrefcountsame{variant_field_type}
2068
2069 @sa bt_ctf_field_type_variant_get_tag_name(): Returns the tag name of
2070         a given variant field type.
2071 */
2072 extern int bt_ctf_field_type_variant_set_tag_name(
2073                 struct bt_ctf_field_type *variant_field_type,
2074                 const char *tag_name);
2075
2076 /**
2077 @brief  Returns the tag's CTF IR field path of the @varft
2078         \p variant_field_type.
2079
2080 The tag's field path of a variant field type is set when automatic
2081 resolving is performed (see \ref ctfirfieldtypes).
2082
2083 @param[in] variant_field_type   Variant field type of which to get the
2084                                 tag's field path.
2085 @returns                        Tag's field path of
2086                                 \p variant_field_type, or
2087                                 \c NULL if the tag's field path is not
2088                                 set yet is not set or on error.
2089
2090 @prenotnull{variant_field_type}
2091 @preisvarft{variant_field_type}
2092 @postsuccessrefcountretinc
2093
2094 @sa bt_ctf_field_type_variant_get_tag_name(): Returns the tag's
2095         name of a given variant field type.
2096 */
2097 extern struct bt_ctf_field_path *bt_ctf_field_type_variant_get_tag_field_path(
2098                 struct bt_ctf_field_type *variant_field_type);
2099
2100 /**
2101 @brief  Returns the number of fields (choices) contained in the @varft
2102         \p variant_field_type.
2103
2104 @param[in] variant_field_type   Variant field type of which to get
2105                                 the number of contained fields.
2106 @returns                        Number of fields contained in
2107                                 \p variant_field_type, or a negative
2108                                 value on error.
2109
2110 @prenotnull{variant_field_type}
2111 @preisvarft{variant_field_type}
2112 @postrefcountsame{variant_field_type}
2113 */
2114 extern int bt_ctf_field_type_variant_get_field_count(
2115                 struct bt_ctf_field_type *variant_field_type);
2116
2117 /**
2118 @brief  Returns the field (choice) of the @varft \p variant_field_type
2119         at index \p index.
2120
2121 On success, the field's type is placed in \p *field_type if
2122 \p field_type is not \c NULL. The field's name is placed in
2123 \p *field_name if \p field_name is not \c NULL.
2124 \p variant_field_type remains the sole owner of \p *field_name.
2125
2126 @param[in] variant_field_type   Variant field type of which to get
2127                                 the field at index \p index.
2128 @param[out] field_name          Returned name of the field at index
2129                                 \p index (can be \c NULL).
2130 @param[out] field_type          Returned field type of the field
2131                                 at index \p index (can be \c NULL).
2132 @param[in] index              Index of the field to get from
2133                                 \p variant_field_type.
2134 @returns                        0 on success, or a negative value on error.
2135
2136 @prenotnull{variant_field_type}
2137 @preisvarft{variant_field_type}
2138 @pre \p index is lesser than the number of fields contained in the
2139         variant field type \p variant_field_type (see
2140         bt_ctf_field_type_variant_get_field_count()).
2141 @postrefcountsame{variant_field_type}
2142 @post <strong>On success</strong>, the returned field's type is placed
2143         in \p *field_type and its reference count is incremented.
2144
2145 @sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant
2146         field type's field by name.
2147 @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant
2148         field type's field by current tag value.
2149 */
2150 extern int bt_ctf_field_type_variant_get_field(
2151                 struct bt_ctf_field_type *variant_field_type,
2152                 const char **field_name,
2153                 struct bt_ctf_field_type **field_type, int index);
2154
2155 /**
2156 @brief  Returns the type of the field (choice) named \p field_name
2157         found in the @varft \p variant_field_type.
2158
2159 @param[in] variant_field_type   Variant field type of which to get
2160                                 a field's type.
2161 @param[in] field_name           Name of the field to find.
2162 @returns                        Type of the field named \p field_name in
2163                                 \p variant_field_type, or
2164                                 \c NULL on error.
2165
2166 @prenotnull{variant_field_type}
2167 @prenotnull{field_name}
2168 @preisvarft{variant_field_type}
2169 @postrefcountsame{variant_field_type}
2170 @postsuccessrefcountretinc
2171
2172 @sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's
2173         field by index.
2174 @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant
2175         field type's field by current tag value.
2176 */
2177 extern
2178 struct bt_ctf_field_type *bt_ctf_field_type_variant_get_field_type_by_name(
2179                 struct bt_ctf_field_type *variant_field_type,
2180                 const char *field_name);
2181
2182 /**
2183 @brief  Returns the type of the field (choice) selected by the value of
2184         the @enumfield \p tag_field in the @varft \p variant_field_type.
2185
2186 \p tag_field is the current tag value.
2187
2188 The field type of \p tag_field, as returned by bt_ctf_field_get_type(),
2189 \em must be equivalent to the field type returned by
2190 bt_ctf_field_type_variant_get_tag_type() for \p variant_field_type.
2191
2192 @param[in] variant_field_type   Variant field type of which to get
2193                                 a field's type.
2194 @param[in] tag_field            Current tag value (variant field type's
2195                                 selector).
2196 @returns                        Type of the field selected by
2197                                 \p tag_field in \p variant_field_type,
2198                                 or \c NULL on error.
2199
2200 @prenotnull{variant_field_type}
2201 @prenotnull{tag_field}
2202 @preisvarft{variant_field_type}
2203 @preisenumfield{tag_field}
2204 @postrefcountsame{variant_field_type}
2205 @postrefcountsame{tag_field}
2206 @postsuccessrefcountretinc
2207
2208 @sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's
2209         field by index.
2210 @sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant
2211         field type's field by name.
2212 */
2213 extern
2214 struct bt_ctf_field_type *bt_ctf_field_type_variant_get_field_type_from_tag(
2215                 struct bt_ctf_field_type *variant_field_type,
2216                 struct bt_ctf_field *tag_field);
2217
2218 /**
2219 @brief  Adds a field (a choice) named \p field_name with the @ft
2220         \p field_type to the @varft \p variant_field_type.
2221
2222 On success, \p field_type becomes the child of \p variant_field_type.
2223
2224 You \em cannot add a field named \p field_name if there's already a
2225 field named \p field_name in \p variant_field_type.
2226
2227 \p field_name \em must name an existing mapping in the tag's
2228 enumeration field type of \p variant_field_type.
2229
2230 @param[in] variant_field_type   Variant field type to which to add
2231                                 a new field.
2232 @param[in] field_type           Field type of the field to add to
2233                                 \p variant_field_type.
2234 @param[in] field_name           Name of the field to add to
2235                                 \p variant_field_type
2236                                 (copied on success).
2237 @returns                        0 on success, or a negative value on error.
2238
2239 @prenotnull{variant_field_type}
2240 @prenotnull{field_type}
2241 @prenotnull{field_name}
2242 @preisvarft{variant_field_type}
2243 @pre \p field_type is not and does not contain \p variant_field_type,
2244         recursively, as a field's type.
2245 @prehot{variant_field_type}
2246 @postrefcountsame{variant_field_type}
2247 @postsuccessrefcountinc{field_type}
2248 */
2249 extern int bt_ctf_field_type_variant_add_field(
2250                 struct bt_ctf_field_type *variant_field_type,
2251                 struct bt_ctf_field_type *field_type,
2252                 const char *field_name);
2253
2254 /** @} */
2255
2256 #ifdef __cplusplus
2257 }
2258 #endif
2259
2260 #endif /* BABELTRACE_CTF_IR_FIELD_TYPES_H */