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

   1 #ifndef BABELTRACE_CTF_IR_EVENT_TYPES_H
   2 #define BABELTRACE_CTF_IR_EVENT_TYPES_H
   3
   4 /*
   5  * BabelTrace - CTF IR: Event 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 <babeltrace/ctf/events.h>
  34 #include <stdint.h>
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 struct bt_ctf_event_class;
  41 struct bt_ctf_event;
  42 struct bt_ctf_field_type;
  43 struct bt_ctf_field;
  44
  45 enum bt_ctf_integer_base {
  46         BT_CTF_INTEGER_BASE_UNKNOWN = -1,
  47         BT_CTF_INTEGER_BASE_BINARY = 2,
  48         BT_CTF_INTEGER_BASE_OCTAL = 8,
  49         BT_CTF_INTEGER_BASE_DECIMAL = 10,
  50         BT_CTF_INTEGER_BASE_HEXADECIMAL = 16,
  51 };
  52
  53 enum bt_ctf_byte_order {
  54         BT_CTF_BYTE_ORDER_UNKNOWN = -1,
  55         /*
  56          * Note that native, in the context of the CTF specification, is defined as
  57          * "the byte order described in the trace" and does not mean that the host's
  58          * endianness will be used.
  59          */
  60         BT_CTF_BYTE_ORDER_NATIVE = 0,
  61         BT_CTF_BYTE_ORDER_LITTLE_ENDIAN,
  62         BT_CTF_BYTE_ORDER_BIG_ENDIAN,
  63         BT_CTF_BYTE_ORDER_NETWORK,
  64 };
  65
  66 /*
  67  * bt_ctf_field_type_integer_create: create an integer field type.
  68  *
  69  * Allocate a new integer field type of the given size. The creation of a field
  70  * type sets its reference count to 1.
  71  *
  72  * @param size Integer field type size/length in bits.
  73  *
  74  * Returns an allocated field type on success, NULL on error.
  75  */
  76 extern struct bt_ctf_field_type *bt_ctf_field_type_integer_create(
  77                 unsigned int size);
  78
  79 /*
  80  * bt_ctf_field_type_integer_get_size: get an integer type's size.
  81  *
  82  * Get an integer type's size.
  83  *
  84  * @param integer Integer type.
  85  *
  86  * Returns the integer type's size, a negative value on error.
  87  */
  88 extern int bt_ctf_field_type_integer_get_size(
  89                 struct bt_ctf_field_type *integer);
  90
  91 /*
  92  * bt_ctf_field_type_integer_get_signed: get an integer type's signedness.
  93  *
  94  * Get an integer type's signedness attribute.
  95  *
  96  * @param integer Integer type.
  97  *
  98  * Returns the integer's signedness, a negative value on error.
  99  */
 100 extern int bt_ctf_field_type_integer_get_signed(
 101                 struct bt_ctf_field_type *integer);
 102
 103 /*
 104  * bt_ctf_field_type_integer_set_signed: set an integer type's signedness.
 105  *
 106  * Set an integer type's signedness attribute.
 107  *
 108  * @param integer Integer type.
 109  * @param is_signed Integer's signedness, defaults to FALSE.
 110  *
 111  * Returns 0 on success, a negative value on error.
 112  */
 113 extern int bt_ctf_field_type_integer_set_signed(
 114                 struct bt_ctf_field_type *integer, int is_signed);
 115
 116 /*
 117  * bt_ctf_field_type_integer_get_base: get an integer type's base.
 118  *
 119  * Get an integer type's base used to pretty-print the resulting trace.
 120  *
 121  * @param integer Integer type.
 122  *
 123  * Returns the integer type's base on success, BT_CTF_INTEGER_BASE_UNKNOWN on
 124  *      error.
 125  */
 126 extern enum bt_ctf_integer_base bt_ctf_field_type_integer_get_base(
 127                 struct bt_ctf_field_type *integer);
 128
 129 /*
 130  * bt_ctf_field_type_integer_set_base: set an integer type's base.
 131  *
 132  * Set an integer type's base used to pretty-print the resulting trace.
 133  *
 134  * @param integer Integer type.
 135  * @param base Integer base, defaults to BT_CTF_INTEGER_BASE_DECIMAL.
 136  *
 137  * Returns 0 on success, a negative value on error.
 138  */
 139 extern int bt_ctf_field_type_integer_set_base(struct bt_ctf_field_type *integer,
 140                 enum bt_ctf_integer_base base);
 141
 142 /*
 143  * bt_ctf_field_type_integer_get_encoding: get an integer type's encoding.
 144  *
 145  * @param integer Integer type.
 146  *
 147  * Returns the string field's encoding on success, CTF_STRING_UNKNOWN on error.
 148  */
 149 extern enum ctf_string_encoding bt_ctf_field_type_integer_get_encoding(
 150                 struct bt_ctf_field_type *integer);
 151
 152 /*
 153  * bt_ctf_field_type_integer_set_encoding: set an integer type's encoding.
 154  *
 155  * An integer encoding may be set to signal that the integer must be printed as
 156  * a text character.
 157  *
 158  * @param integer Integer type.
 159  * @param encoding Integer output encoding, defaults to CTF_STRING_ENCODING_NONE
 160  *
 161  * Returns 0 on success, a negative value on error.
 162  */
 163 extern int bt_ctf_field_type_integer_set_encoding(
 164                 struct bt_ctf_field_type *integer,
 165                 enum ctf_string_encoding encoding);
 166
 167 /*
 168  * bt_ctf_field_type_enumeration_create: create an enumeration field type.
 169  *
 170  * Allocate a new enumeration field type with the given underlying type. The
 171  * creation of a field type sets its reference count to 1.
 172  * The resulting enumeration will share the integer_container_type's ownership
 173  * by increasing its reference count.
 174  *
 175  * @param integer_container_type Underlying integer type of the enumeration
 176  *      type.
 177  *
 178  * Returns an allocated field type on success, NULL on error.
 179  */
 180 extern struct bt_ctf_field_type *bt_ctf_field_type_enumeration_create(
 181                 struct bt_ctf_field_type *integer_container_type);
 182
 183 /*
 184  * bt_ctf_field_type_enumeration_get_container_type: get underlying container.
 185  *
 186  * Get the enumeration type's underlying integer container type.
 187  *
 188  * @param enumeration Enumeration type.
 189  *
 190  * Returns an allocated field type on success, NULL on error.
 191  */
 192 extern
 193 struct bt_ctf_field_type *bt_ctf_field_type_enumeration_get_container_type(
 194                 struct bt_ctf_field_type *enumeration);
 195
 196 /*
 197  * bt_ctf_field_type_enumeration_add_mapping: add an enumeration mapping.
 198  *
 199  * Add a mapping to the enumeration. The range's values are inclusive.
 200  *
 201  * @param enumeration Enumeration type.
 202  * @param name Enumeration mapping name (will be copied).
 203  * @param range_start Enumeration mapping range start.
 204  * @param range_end Enumeration mapping range end.
 205  *
 206  * Returns 0 on success, a negative value on error.
 207  */
 208 extern int bt_ctf_field_type_enumeration_add_mapping(
 209                 struct bt_ctf_field_type *enumeration, const char *name,
 210                 int64_t range_start, int64_t range_end);
 211
 212 /*
 213  * bt_ctf_field_type_enumeration_add_mapping_unsigned: add an enumeration
 214  *      mapping.
 215  *
 216  * Add a mapping to the enumeration. The range's values are inclusive.
 217  *
 218  * @param enumeration Enumeration type.
 219  * @param name Enumeration mapping name (will be copied).
 220  * @param range_start Enumeration mapping range start.
 221  * @param range_end Enumeration mapping range end.
 222  *
 223  * Returns 0 on success, a negative value on error.
 224  */
 225 extern int bt_ctf_field_type_enumeration_add_mapping_unsigned(
 226                 struct bt_ctf_field_type *enumeration, const char *name,
 227                 uint64_t range_start, uint64_t range_end);
 228
 229 /*
 230  * bt_ctf_field_type_enumeration_get_mapping_count: Get the number of mappings
 231  *      defined in the enumeration.
 232  *
 233  * @param enumeration Enumeration type.
 234  *
 235  * Returns the mapping count on success, a negative value on error.
 236  */
 237 extern int bt_ctf_field_type_enumeration_get_mapping_count(
 238                 struct bt_ctf_field_type *enumeration);
 239
 240 /*
 241  * bt_ctf_field_type_enumeration_get_mapping: get an enumeration mapping.
 242  *
 243  * @param enumeration Enumeration type.
 244  * @param index Index of mapping.
 245  * @param name Pointer where the mapping's name will be returned (valid for
 246  *      the lifetime of the enumeration).
 247  * @param range_start Pointer where the enumeration mapping's range start will
 248  *      be returned.
 249  * @param range_end Pointer where the enumeration mapping's range end will
 250  *      be returned.
 251  *
 252  * Returns 0 on success, a negative value on error.
 253  */
 254 extern int bt_ctf_field_type_enumeration_get_mapping(
 255                 struct bt_ctf_field_type *enumeration, int index,
 256                 const char **name, int64_t *range_start, int64_t *range_end);
 257
 258 /*
 259  * bt_ctf_field_type_enumeration_get_mapping_unsigned: get a mapping.
 260  *
 261  * @param enumeration Enumeration type.
 262  * @param index Index of mapping.
 263  * @param name Pointer where the mapping's name will be returned (valid for
 264  *      the lifetime of the enumeration).
 265  * @param range_start Pointer where the enumeration mapping's range start will
 266  *      be returned.
 267  * @param range_end Pointer where the enumeration mapping's range end will
 268  *      be returned.
 269  *
 270  * Returns 0 on success, a negative value on error.
 271  */
 272 extern int bt_ctf_field_type_enumeration_get_mapping_unsigned(
 273                 struct bt_ctf_field_type *enumeration, int index,
 274                 const char **name, uint64_t *range_start,
 275                 uint64_t *range_end);
 276
 277 /*
 278  * bt_ctf_field_type_enumeration_get_mapping_index_by_name: get an enumerations'
 279  *      mapping index by name.
 280  *
 281  * @param enumeration Enumeration type.
 282  * @param name Mapping name.
 283  *
 284  * Returns mapping index on success, a negative value on error.
 285  */
 286 extern int bt_ctf_field_type_enumeration_get_mapping_index_by_name(
 287                 struct bt_ctf_field_type *enumeration, const char *name);
 288
 289 /*
 290  * bt_ctf_field_type_enumeration_get_mapping_index_by_value: get an
 291  *      enumerations' mapping index by value.
 292  *
 293  * @param enumeration Enumeration type.
 294  * @param value Value.
 295  *
 296  * Returns mapping index on success, a negative value on error.
 297  */
 298 extern int bt_ctf_field_type_enumeration_get_mapping_index_by_value(
 299                 struct bt_ctf_field_type *enumeration, int64_t value);
 300
 301 /*
 302  * bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value: get an
 303  *      enumerations' mapping index by value.
 304  *
 305  * @param enumeration Enumeration type.
 306  * @param value Value.
 307  *
 308  * Returns 0 on success, a negative value on error.
 309  */
 310 extern int bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value(
 311                 struct bt_ctf_field_type *enumeration, uint64_t value);
 312
 313 /*
 314  * bt_ctf_field_type_floating_point_create: create a floating point field type.
 315  *
 316  * Allocate a new floating point field type. The creation of a field type sets
 317  * its reference count to 1.
 318  *
 319  * Returns an allocated field type on success, NULL on error.
 320  */
 321 extern struct bt_ctf_field_type *bt_ctf_field_type_floating_point_create(void);
 322
 323 /*
 324  * bt_ctf_field_type_floating_point_get_exponent_digits: get exponent digit
 325  *      count.
 326  *
 327  * @param floating_point Floating point type.
 328  *
 329  * Returns the exponent digit count on success, a negative value on error.
 330  */
 331 extern int bt_ctf_field_type_floating_point_get_exponent_digits(
 332                 struct bt_ctf_field_type *floating_point);
 333
 334 /*
 335  * bt_ctf_field_type_floating_point_set_exponent_digits: set exponent digit
 336  *      count.
 337  *
 338  * Set the number of exponent digits to use to store the floating point field.
 339  * The only values currently supported are FLT_EXP_DIG and DBL_EXP_DIG.
 340  *
 341  * @param floating_point Floating point type.
 342  * @param exponent_digits Number of digits to allocate to the exponent (defaults
 343  *      to FLT_EXP_DIG).
 344  *
 345  * Returns 0 on success, a negative value on error.
 346  */
 347 extern int bt_ctf_field_type_floating_point_set_exponent_digits(
 348                 struct bt_ctf_field_type *floating_point,
 349                 unsigned int exponent_digits);
 350
 351 /*
 352  * bt_ctf_field_type_floating_point_get_mantissa_digits: get mantissa digit
 353  * count.
 354  *
 355  * @param floating_point Floating point type.
 356  *
 357  * Returns the mantissa digit count on success, a negative value on error.
 358  */
 359 extern int bt_ctf_field_type_floating_point_get_mantissa_digits(
 360                 struct bt_ctf_field_type *floating_point);
 361
 362 /*
 363  * bt_ctf_field_type_floating_point_set_mantissa_digits: set mantissa digit
 364  *      count.
 365  *
 366  * Set the number of mantissa digits to use to store the floating point field.
 367  * The only values currently supported are FLT_MANT_DIG and DBL_MANT_DIG.
 368  *
 369  * @param floating_point Floating point type.
 370  * @param mantissa_digits Number of digits to allocate to the mantissa (defaults
 371  *      to FLT_MANT_DIG).
 372  *
 373  * Returns 0 on success, a negative value on error.
 374  */
 375 extern int bt_ctf_field_type_floating_point_set_mantissa_digits(
 376                 struct bt_ctf_field_type *floating_point,
 377                 unsigned int mantissa_digits);
 378
 379 /*
 380  * bt_ctf_field_type_structure_create: create a structure field type.
 381  *
 382  * Allocate a new structure field type. The creation of a field type sets
 383  * its reference count to 1.
 384  *
 385  * Returns an allocated field type on success, NULL on error.
 386  */
 387 extern struct bt_ctf_field_type *bt_ctf_field_type_structure_create(void);
 388
 389 /*
 390  * bt_ctf_field_type_structure_add_field: add a field to a structure.
 391  *
 392  * Add a field of type "field_type" to the structure. The structure will share
 393  * field_type's ownership by increasing its reference count.
 394  *
 395  * @param structure Structure type.
 396  * @param field_type Type of the field to add to the structure type.
 397  * @param field_name Name of the structure's new field (will be copied).
 398  *
 399  * Returns 0 on success, a negative value on error.
 400  */
 401 extern int bt_ctf_field_type_structure_add_field(
 402                 struct bt_ctf_field_type *structure,
 403                 struct bt_ctf_field_type *field_type,
 404                 const char *field_name);
 405
 406 /*
 407  * bt_ctf_field_type_structure_get_field_count: Get the number of fields defined
 408  *      in the structure.
 409  *
 410  * @param structure Structure type.
 411  *
 412  * Returns the field count on success, a negative value on error.
 413  */
 414 extern int bt_ctf_field_type_structure_get_field_count(
 415                 struct bt_ctf_field_type *structure);
 416
 417 /*
 418  * bt_ctf_field_type_structure_get_field: get a structure's field type and name.
 419  *
 420  * @param structure Structure type.
 421  * @param field_type Pointer to a const char* where the field's name will
 422  *      be returned.
 423  * @param field_type Pointer to a bt_ctf_field_type* where the field's type will
 424  *      be returned.
 425  * @param index Index of field.
 426  *
 427  * Returns 0 on success, a negative value on error.
 428  */
 429 extern int bt_ctf_field_type_structure_get_field(
 430                 struct bt_ctf_field_type *structure,
 431                 const char **field_name, struct bt_ctf_field_type **field_type,
 432                 int index);
 433
 434 /*
 435  * bt_ctf_field_type_structure_get_field_type_by_name: get a structure field's
 436  *      type by name.
 437  *
 438  * @param structure Structure type.
 439  * @param field_name Name of the structure's field.
 440  *
 441  * Returns a field type instance on success, NULL on error.
 442  */
 443 extern
 444 struct bt_ctf_field_type *bt_ctf_field_type_structure_get_field_type_by_name(
 445                 struct bt_ctf_field_type *structure, const char *field_name);
 446
 447 /*
 448  * bt_ctf_field_type_variant_create: create a variant field type.
 449  *
 450  * Allocate a new variant field type. The creation of a field type sets
 451  * its reference count to 1. tag_name must be the name of an enumeration
 452  * field declared in the same scope as this variant.
 453  *
 454  * @param enum_tag Type of the variant's tag/selector (must be an enumeration).
 455  * @param tag_name Name of the variant's tag/selector field (will be copied).
 456  *
 457  * Returns an allocated field type on success, NULL on error.
 458  */
 459 extern struct bt_ctf_field_type *bt_ctf_field_type_variant_create(
 460                 struct bt_ctf_field_type *enum_tag, const char *tag_name);
 461
 462 /*
 463  * bt_ctf_field_type_variant_get_tag_type: get a variant's tag type.
 464  *
 465  * @param variant Variant type.
 466  *
 467  * Returns a field type instance on success, NULL on error.
 468  */
 469 extern struct bt_ctf_field_type *bt_ctf_field_type_variant_get_tag_type(
 470                 struct bt_ctf_field_type *variant);
 471
 472 /*
 473  * bt_ctf_field_type_variant_get_tag_name: get a variant's tag name.
 474  *
 475  * @param variant Variant type.
 476  *
 477  * Returns the tag field's name, NULL on error.
 478  */
 479 extern const char *bt_ctf_field_type_variant_get_tag_name(
 480                 struct bt_ctf_field_type *variant);
 481
 482 /*
 483  * bt_ctf_field_type_variant_add_field: add a field to a variant.
 484  *
 485  * Add a field of type "field_type" to the variant. The variant will share
 486  * field_type's ownership by increasing its reference count. The "field_name"
 487  * will be copied. field_name must match a mapping in the tag/selector
 488  * enumeration.
 489  *
 490  * @param variant Variant type.
 491  * @param field_type Type of the variant type's new field.
 492  * @param field_name Name of the variant type's new field (will be copied).
 493  *
 494  * Returns 0 on success, a negative value on error.
 495  */
 496 extern int bt_ctf_field_type_variant_add_field(
 497                 struct bt_ctf_field_type *variant,
 498                 struct bt_ctf_field_type *field_type,
 499                 const char *field_name);
 500
 501 /*
 502  * bt_ctf_field_type_variant_get_field_type_by_name: get variant field's type.
 503  *
 504  * @param structure Variant type.
 505  * @param field_name Name of the variant's field.
 506  *
 507  * Returns a field type instance on success, NULL on error.
 508  */
 509 extern
 510 struct bt_ctf_field_type *bt_ctf_field_type_variant_get_field_type_by_name(
 511                 struct bt_ctf_field_type *variant, const char *field_name);
 512
 513 /*
 514  * bt_ctf_field_type_variant_get_field_type_from_tag: get variant field's type.
 515  *
 516  * @param variant Variant type.
 517  * @param tag Type tag (enum).
 518  *
 519  * Returns a field type instance on success, NULL on error.
 520  */
 521 extern
 522 struct bt_ctf_field_type *bt_ctf_field_type_variant_get_field_type_from_tag(
 523                 struct bt_ctf_field_type *variant, struct bt_ctf_field *tag);
 524
 525 /*
 526  * bt_ctf_field_type_variant_get_field_count: Get the number of fields defined
 527  *      in the variant.
 528  *
 529  * @param variant Variant type.
 530  *
 531  * Returns the field count on success, a negative value on error.
 532  */
 533 extern int bt_ctf_field_type_variant_get_field_count(
 534                 struct bt_ctf_field_type *variant);
 535
 536 /*
 537  * bt_ctf_field_type_variant_get_field: get a variant's field name and type.
 538  *
 539  * @param variant Variant type.
 540  * @param field_type Pointer to a const char* where the field's name will
 541  *      be returned.
 542  * @param field_type Pointer to a bt_ctf_field_type* where the field's type will
 543  *      be returned.
 544  * @param index Index of field.
 545  *
 546  * Returns 0 on success, a negative value on error.
 547  */
 548 extern int bt_ctf_field_type_variant_get_field(
 549                 struct bt_ctf_field_type *variant, const char **field_name,
 550                 struct bt_ctf_field_type **field_type, int index);
 551
 552 /*
 553  * bt_ctf_field_type_array_create: create an array field type.
 554  *
 555  * Allocate a new array field type. The creation of a field type sets
 556  * its reference count to 1.
 557  *
 558  * @param element_type Array's element type.
 559  * @oaram length Array type's length.
 560  *
 561  * Returns an allocated field type on success, NULL on error.
 562  */
 563 extern struct bt_ctf_field_type *bt_ctf_field_type_array_create(
 564                 struct bt_ctf_field_type *element_type, unsigned int length);
 565
 566 /*
 567  * bt_ctf_field_type_array_get_element_type: get an array's element type.
 568  *
 569  * @param array Array type.
 570  *
 571  * Returns a field type instance on success, NULL on error.
 572  */
 573 extern struct bt_ctf_field_type *bt_ctf_field_type_array_get_element_type(
 574                 struct bt_ctf_field_type *array);
 575
 576 /*
 577  * bt_ctf_field_type_array_get_length: get an array's length.
 578  *
 579  * @param array Array type.
 580  *
 581  * Returns the array's length on success, a negative value on error.
 582  */
 583 extern int64_t bt_ctf_field_type_array_get_length(
 584                 struct bt_ctf_field_type *array);
 585
 586 /*
 587  * bt_ctf_field_type_sequence_create: create a sequence field type.
 588  *
 589  * Allocate a new sequence field type. The creation of a field type sets
 590  * its reference count to 1. "length_field_name" must match an integer field
 591  * declared in the same scope.
 592  *
 593  * @param element_type Sequence's element type.
 594  * @param length_field_name Name of the sequence's length field (will be
 595  *      copied).
 596  *
 597  * Returns an allocated field type on success, NULL on error.
 598  */
 599 extern struct bt_ctf_field_type *bt_ctf_field_type_sequence_create(
 600                 struct bt_ctf_field_type *element_type,
 601                 const char *length_field_name);
 602
 603 /*
 604  * bt_ctf_field_type_sequence_get_element_type: get a sequence's element type.
 605  *
 606  * @param sequence Sequence type.
 607  *
 608  * Returns a field type instance on success, NULL on error.
 609  */
 610 extern struct bt_ctf_field_type *bt_ctf_field_type_sequence_get_element_type(
 611                 struct bt_ctf_field_type *sequence);
 612
 613 /*
 614  * bt_ctf_field_type_sequence_get_length_field_name: get length field name.
 615  *
 616  * @param sequence Sequence type.
 617  *
 618  * Returns the sequence's length field on success, NULL on error.
 619  */
 620 extern const char *bt_ctf_field_type_sequence_get_length_field_name(
 621                 struct bt_ctf_field_type *sequence);
 622
 623 /*
 624  * bt_ctf_field_type_string_create: create a string field type.
 625  *
 626  * Allocate a new string field type. The creation of a field type sets
 627  * its reference count to 1.
 628  *
 629  * Returns an allocated field type on success, NULL on error.
 630  */
 631 extern struct bt_ctf_field_type *bt_ctf_field_type_string_create(void);
 632
 633 /*
 634  * bt_ctf_field_type_string_get_encoding: get a string type's encoding.
 635  *
 636  * Get the string type's encoding.
 637  *
 638  * @param string_type String type.
 639  *
 640  * Returns the string's encoding on success, a CTF_STRING_UNKNOWN on error.
 641  */
 642 extern enum ctf_string_encoding bt_ctf_field_type_string_get_encoding(
 643                 struct bt_ctf_field_type *string_type);
 644
 645 /*
 646  * bt_ctf_field_type_string_set_encoding: set a string type's encoding.
 647  *
 648  * Set the string type's encoding.
 649  *
 650  * @param string_type String type.
 651  * @param encoding String field encoding, default CTF_STRING_ENCODING_ASCII.
 652  *      Valid values are CTF_STRING_ENCODING_ASCII and CTF_STRING_ENCODING_UTF8.
 653  *
 654  * Returns 0 on success, a negative value on error.
 655  */
 656 extern int bt_ctf_field_type_string_set_encoding(
 657                 struct bt_ctf_field_type *string_type,
 658                 enum ctf_string_encoding encoding);
 659
 660 /*
 661  * bt_ctf_field_type_get_alignment: get a field type's alignment.
 662  *
 663  * Get the field type's alignment.
 664  *
 665  * @param type Field type.
 666  *
 667  * Returns the field type's alignment on success, a negative value on error.
 668  */
 669 extern int bt_ctf_field_type_get_alignment(struct bt_ctf_field_type *type);
 670
 671 /*
 672  * bt_ctf_field_type_set_alignment: set a field type's alignment.
 673  *
 674  * Set the field type's alignment.
 675  *
 676  * @param type Field type.
 677  * @param alignment Type's alignment. Defaults to 1 (bit-aligned). However,
 678  *      some types, such as structures and string, may impose other alignment
 679  *      constraints.
 680  *
 681  * Returns 0 on success, a negative value on error.
 682  */
 683 extern int bt_ctf_field_type_set_alignment(struct bt_ctf_field_type *type,
 684                 unsigned int alignment);
 685
 686 /*
 687  * bt_ctf_field_type_get_byte_order: get a field type's byte order.
 688  *
 689  * @param type Field type.
 690  *
 691  * Returns the field type's byte order on success, a negative value on error.
 692  */
 693 extern enum bt_ctf_byte_order bt_ctf_field_type_get_byte_order(
 694                 struct bt_ctf_field_type *type);
 695
 696 /*
 697  * bt_ctf_field_type_set_byte_order: set a field type's byte order.
 698  *
 699  * Set the field type's byte order.
 700  *
 701  * @param type Field type.
 702  * @param byte_order Field type's byte order. Defaults to
 703  * BT_CTF_BYTE_ORDER_NATIVE; the trace's endianness.
 704  *
 705  * Returns 0 on success, a negative value on error.
 706  */
 707 extern int bt_ctf_field_type_set_byte_order(struct bt_ctf_field_type *type,
 708                 enum bt_ctf_byte_order byte_order);
 709
 710 /*
 711  * bt_ctf_field_type_get_type_id: get a field type's ctf_type_id.
 712  *
 713  * @param type Field type.
 714  *
 715  * Returns the field type's ctf_type_id, CTF_TYPE_UNKNOWN on error.
 716  */
 717 extern enum ctf_type_id bt_ctf_field_type_get_type_id(
 718                 struct bt_ctf_field_type *type);
 719
 720 /*
 721  * bt_ctf_field_type_get_alias_nameL get a field type's alias name
 722  *
 723  * A type's alias name is set if it was resolved from a typedef or
 724  * typealias. Note that types that are resolved from a ypealias or
 725  * typedef are distinct from the underlying type and can't be compared
 726  * pointer-wise.
 727  *
 728  * @param type Field type.
 729  *
 730  * Returns a field type's alias name, NULL on error.
 731  */
 732 extern const char *bt_ctf_field_type_get_alias_name(
 733                 struct bt_ctf_field_type *type);
 734
 735 /*
 736  * bt_ctf_field_type_get and bt_ctf_field_type_put: increment and decrement
 737  * the field type's reference count.
 738  *
 739  * These functions ensure that the field type won't be destroyed while it
 740  * is in use. The same number of get and put (plus one extra put to
 741  * release the initial reference done at creation) have to be done to
 742  * destroy a field type.
 743  *
 744  * When the field type's reference count is decremented to 0 by a
 745  * bt_ctf_field_type_put, the field type is freed.
 746  *
 747  * @param type Field type.
 748  */
 749 extern void bt_ctf_field_type_get(struct bt_ctf_field_type *type);
 750 extern void bt_ctf_field_type_put(struct bt_ctf_field_type *type);
 751
 752 #ifdef __cplusplus
 753 }
 754 #endif
 755
 756 #endif /* BABELTRACE_CTF_IR_EVENT_TYPES_H */