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