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 #include <babeltrace/ctf/events.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 struct bt_ctf_field_path;
  45
  46 enum bt_ctf_integer_base {
  47         BT_CTF_INTEGER_BASE_UNKNOWN = -1,
  48         BT_CTF_INTEGER_BASE_BINARY = 2,
  49         BT_CTF_INTEGER_BASE_OCTAL = 8,
  50         BT_CTF_INTEGER_BASE_DECIMAL = 10,
  51         BT_CTF_INTEGER_BASE_HEXADECIMAL = 16,
  52 };
  53
  54 enum bt_ctf_byte_order {
  55         BT_CTF_BYTE_ORDER_UNKNOWN = -1,
  56         /*
  57          * Note that native, in the context of the CTF specification, is defined
  58          * as "the byte order described in the trace" and does not mean that the
  59          * host's endianness will be used.
  60          */
  61         BT_CTF_BYTE_ORDER_NATIVE = 0,
  62         BT_CTF_BYTE_ORDER_LITTLE_ENDIAN,
  63         BT_CTF_BYTE_ORDER_BIG_ENDIAN,
  64         BT_CTF_BYTE_ORDER_NETWORK,
  65 };
  66
  67 enum bt_ctf_string_encoding {
  68         BT_CTF_STRING_ENCODING_NONE = CTF_STRING_NONE,
  69         BT_CTF_STRING_ENCODING_UTF8 = CTF_STRING_UTF8,
  70         BT_CTF_STRING_ENCODING_ASCII = CTF_STRING_ASCII,
  71         BT_CTF_STRING_ENCODING_UNKNOWN = CTF_STRING_UNKNOWN,
  72 };
  73
  74 /*
  75  * bt_ctf_field_type_integer_create: create an integer field type.
  76  *
  77  * Allocate a new integer field type of the given size. The creation of a field
  78  * type sets its reference count to 1.
  79  *
  80  * @param size Integer field type size/length in bits.
  81  *
  82  * Returns an allocated field type on success, NULL on error.
  83  */
  84 extern struct bt_ctf_field_type *bt_ctf_field_type_integer_create(
  85                 unsigned int size);
  86
  87 /*
  88  * bt_ctf_field_type_integer_get_size: get an integer type's size.
  89  *
  90  * Get an integer type's size.
  91  *
  92  * @param integer Integer type.
  93  *
  94  * Returns the integer type's size, a negative value on error.
  95  */
  96 extern int bt_ctf_field_type_integer_get_size(
  97                 struct bt_ctf_field_type *integer);
  98
  99 /*
 100  * bt_ctf_field_type_integer_get_signed: get an integer type's signedness.
 101  *
 102  * Get an integer type's signedness attribute.
 103  *
 104  * @param integer Integer type.
 105  *
 106  * Returns the integer's signedness, a negative value on error.
 107  */
 108 extern int bt_ctf_field_type_integer_get_signed(
 109                 struct bt_ctf_field_type *integer);
 110
 111 /*
 112  * bt_ctf_field_type_integer_set_signed: set an integer type's signedness.
 113  *
 114  * Set an integer type's signedness attribute.
 115  *
 116  * @param integer Integer type.
 117  * @param is_signed Integer's signedness, defaults to FALSE.
 118  *
 119  * Returns 0 on success, a negative value on error.
 120  */
 121 extern int bt_ctf_field_type_integer_set_signed(
 122                 struct bt_ctf_field_type *integer, int is_signed);
 123
 124 /*
 125  * bt_ctf_field_type_integer_get_base: get an integer type's base.
 126  *
 127  * Get an integer type's base used to pretty-print the resulting trace.
 128  *
 129  * @param integer Integer type.
 130  *
 131  * Returns the integer type's base on success, BT_CTF_INTEGER_BASE_UNKNOWN on
 132  *      error.
 133  */
 134 extern enum bt_ctf_integer_base bt_ctf_field_type_integer_get_base(
 135                 struct bt_ctf_field_type *integer);
 136
 137 /*
 138  * bt_ctf_field_type_integer_set_base: set an integer type's base.
 139  *
 140  * Set an integer type's base used to pretty-print the resulting trace.
 141  *
 142  * @param integer Integer type.
 143  * @param base Integer base, defaults to BT_CTF_INTEGER_BASE_DECIMAL.
 144  *
 145  * Returns 0 on success, a negative value on error.
 146  */
 147 extern int bt_ctf_field_type_integer_set_base(struct bt_ctf_field_type *integer,
 148                 enum bt_ctf_integer_base base);
 149
 150 /*
 151  * bt_ctf_field_type_integer_get_encoding: get an integer type's encoding.
 152  *
 153  * @param integer Integer type.
 154  *
 155  * Returns the string field's encoding on success,
 156  * BT_CTF_STRING_ENCODING_UNKNOWN on error.
 157  */
 158 extern enum bt_ctf_string_encoding bt_ctf_field_type_integer_get_encoding(
 159                 struct bt_ctf_field_type *integer);
 160
 161 /*
 162  * bt_ctf_field_type_integer_set_encoding: set an integer type's encoding.
 163  *
 164  * An integer encoding may be set to signal that the integer must be printed as
 165  * a text character.
 166  *
 167  * @param integer Integer type.
 168  * @param encoding Integer output encoding, defaults to
 169  *      BT_CTF_STRING_ENCODING_NONE
 170  *
 171  * Returns 0 on success, a negative value on error.
 172  */
 173 extern int bt_ctf_field_type_integer_set_encoding(
 174                 struct bt_ctf_field_type *integer,
 175                 enum bt_ctf_string_encoding encoding);
 176
 177 /**
 178  * bt_ctf_field_type_integer_get_mapped_clock: get an integer type's mapped clock.
 179  *
 180  * @param integer Integer type.
 181  *
 182  * Returns the integer's mapped clock (if any), NULL on error.
 183  */
 184 extern struct bt_ctf_clock *bt_ctf_field_type_integer_get_mapped_clock(
 185                 struct bt_ctf_field_type *integer);
 186
 187 /**
 188  * bt_ctf_field_type_integer_set_mapped_clock: set an integer type's mapped clock.
 189  *
 190  * @param integer Integer type.
 191  * @param clock Clock to map.
 192  *
 193  * Returns 0 on success, a negative value on error.
 194  */
 195 extern int bt_ctf_field_type_integer_set_mapped_clock(
 196                 struct bt_ctf_field_type *integer,
 197                 struct bt_ctf_clock *clock);
 198
 199 /*
 200  * bt_ctf_field_type_enumeration_create: create an enumeration field type.
 201  *
 202  * Allocate a new enumeration field type with the given underlying type. The
 203  * creation of a field type sets its reference count to 1.
 204  * The resulting enumeration will share the integer_container_type's ownership
 205  * by increasing its reference count.
 206  *
 207  * @param integer_container_type Underlying integer type of the enumeration
 208  *      type.
 209  *
 210  * Returns an allocated field type on success, NULL on error.
 211  */
 212 extern struct bt_ctf_field_type *bt_ctf_field_type_enumeration_create(
 213                 struct bt_ctf_field_type *integer_container_type);
 214
 215 /*
 216  * bt_ctf_field_type_enumeration_get_container_type: get underlying container.
 217  *
 218  * Get the enumeration type's underlying integer container type.
 219  *
 220  * @param enumeration Enumeration type.
 221  *
 222  * Returns an allocated field type on success, NULL on error.
 223  */
 224 extern
 225 struct bt_ctf_field_type *bt_ctf_field_type_enumeration_get_container_type(
 226                 struct bt_ctf_field_type *enumeration);
 227
 228 /*
 229  * bt_ctf_field_type_enumeration_add_mapping: add an enumeration mapping.
 230  *
 231  * Add a mapping to the enumeration. The range's values are inclusive.
 232  *
 233  * @param enumeration Enumeration type.
 234  * @param name Enumeration mapping name (will be copied).
 235  * @param range_start Enumeration mapping range start.
 236  * @param range_end Enumeration mapping range end.
 237  *
 238  * Returns 0 on success, a negative value on error.
 239  */
 240 extern int bt_ctf_field_type_enumeration_add_mapping(
 241                 struct bt_ctf_field_type *enumeration, const char *name,
 242                 int64_t range_start, int64_t range_end);
 243
 244 /*
 245  * bt_ctf_field_type_enumeration_add_mapping_unsigned: add an enumeration
 246  *      mapping.
 247  *
 248  * Add a mapping to the enumeration. The range's values are inclusive.
 249  *
 250  * @param enumeration Enumeration type.
 251  * @param name Enumeration mapping name (will be copied).
 252  * @param range_start Enumeration mapping range start.
 253  * @param range_end Enumeration mapping range end.
 254  *
 255  * Returns 0 on success, a negative value on error.
 256  */
 257 extern int bt_ctf_field_type_enumeration_add_mapping_unsigned(
 258                 struct bt_ctf_field_type *enumeration, const char *name,
 259                 uint64_t range_start, uint64_t range_end);
 260
 261 /*
 262  * bt_ctf_field_type_enumeration_get_mapping_count: Get the number of mappings
 263  *      defined in the enumeration.
 264  *
 265  * @param enumeration Enumeration type.
 266  *
 267  * Returns the mapping count on success, a negative value on error.
 268  */
 269 extern int bt_ctf_field_type_enumeration_get_mapping_count(
 270                 struct bt_ctf_field_type *enumeration);
 271
 272 /*
 273  * bt_ctf_field_type_enumeration_get_mapping: get an enumeration mapping.
 274  *
 275  * @param enumeration Enumeration type.
 276  * @param index Index of mapping.
 277  * @param name Pointer where the mapping's name will be returned (valid for
 278  *      the lifetime of the enumeration).
 279  * @param range_start Pointer where the enumeration mapping's range start will
 280  *      be returned.
 281  * @param range_end Pointer where the enumeration mapping's range end will
 282  *      be returned.
 283  *
 284  * Returns 0 on success, a negative value on error.
 285  */
 286 extern int bt_ctf_field_type_enumeration_get_mapping(
 287                 struct bt_ctf_field_type *enumeration, int index,
 288                 const char **name, int64_t *range_start, int64_t *range_end);
 289
 290 /*
 291  * bt_ctf_field_type_enumeration_get_mapping_unsigned: get a mapping.
 292  *
 293  * @param enumeration Enumeration type.
 294  * @param index Index of mapping.
 295  * @param name Pointer where the mapping's name will be returned (valid for
 296  *      the lifetime of the enumeration).
 297  * @param range_start Pointer where the enumeration mapping's range start will
 298  *      be returned.
 299  * @param range_end Pointer where the enumeration mapping's range end will
 300  *      be returned.
 301  *
 302  * Returns 0 on success, a negative value on error.
 303  */
 304 extern int bt_ctf_field_type_enumeration_get_mapping_unsigned(
 305                 struct bt_ctf_field_type *enumeration, int index,
 306                 const char **name, uint64_t *range_start,
 307                 uint64_t *range_end);
 308
 309 /*
 310  * bt_ctf_field_type_enumeration_get_mapping_index_by_name: get an enumerations'
 311  *      mapping index by name.
 312  *
 313  * @param enumeration Enumeration type.
 314  * @param name Mapping name.
 315  *
 316  * Returns mapping index on success, a negative value on error.
 317  */
 318 extern int bt_ctf_field_type_enumeration_get_mapping_index_by_name(
 319                 struct bt_ctf_field_type *enumeration, const char *name);
 320
 321 /*
 322  * bt_ctf_field_type_enumeration_get_mapping_index_by_value: get an
 323  *      enumerations' mapping index by value.
 324  *
 325  * @param enumeration Enumeration type.
 326  * @param value Value.
 327  *
 328  * Returns mapping index on success, a negative value on error.
 329  */
 330 extern int bt_ctf_field_type_enumeration_get_mapping_index_by_value(
 331                 struct bt_ctf_field_type *enumeration, int64_t value);
 332
 333 /*
 334  * bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value: get an
 335  *      enumerations' mapping index by value.
 336  *
 337  * @param enumeration Enumeration type.
 338  * @param value Value.
 339  *
 340  * Returns 0 on success, a negative value on error.
 341  */
 342 extern int bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value(
 343                 struct bt_ctf_field_type *enumeration, uint64_t value);
 344
 345 /*
 346  * bt_ctf_field_type_floating_point_create: create a floating point field type.
 347  *
 348  * Allocate a new floating point field type. The creation of a field type sets
 349  * its reference count to 1.
 350  *
 351  * Returns an allocated field type on success, NULL on error.
 352  */
 353 extern struct bt_ctf_field_type *bt_ctf_field_type_floating_point_create(void);
 354
 355 /*
 356  * bt_ctf_field_type_floating_point_get_exponent_digits: get exponent digit
 357  *      count.
 358  *
 359  * @param floating_point Floating point type.
 360  *
 361  * Returns the exponent digit count on success, a negative value on error.
 362  */
 363 extern int bt_ctf_field_type_floating_point_get_exponent_digits(
 364                 struct bt_ctf_field_type *floating_point);
 365
 366 /*
 367  * bt_ctf_field_type_floating_point_set_exponent_digits: set exponent digit
 368  *      count.
 369  *
 370  * Set the number of exponent digits to use to store the floating point field.
 371  * The only values currently supported are FLT_EXP_DIG and DBL_EXP_DIG.
 372  *
 373  * @param floating_point Floating point type.
 374  * @param exponent_digits Number of digits to allocate to the exponent (defaults
 375  *      to FLT_EXP_DIG).
 376  *
 377  * Returns 0 on success, a negative value on error.
 378  */
 379 extern int bt_ctf_field_type_floating_point_set_exponent_digits(
 380                 struct bt_ctf_field_type *floating_point,
 381                 unsigned int exponent_digits);
 382
 383 /*
 384  * bt_ctf_field_type_floating_point_get_mantissa_digits: get mantissa digit
 385  * count.
 386  *
 387  * @param floating_point Floating point type.
 388  *
 389  * Returns the mantissa digit count on success, a negative value on error.
 390  */
 391 extern int bt_ctf_field_type_floating_point_get_mantissa_digits(
 392                 struct bt_ctf_field_type *floating_point);
 393
 394 /*
 395  * bt_ctf_field_type_floating_point_set_mantissa_digits: set mantissa digit
 396  *      count.
 397  *
 398  * Set the number of mantissa digits to use to store the floating point field.
 399  * The only values currently supported are FLT_MANT_DIG and DBL_MANT_DIG.
 400  *
 401  * @param floating_point Floating point type.
 402  * @param mantissa_digits Number of digits to allocate to the mantissa (defaults
 403  *      to FLT_MANT_DIG).
 404  *
 405  * Returns 0 on success, a negative value on error.
 406  */
 407 extern int bt_ctf_field_type_floating_point_set_mantissa_digits(
 408                 struct bt_ctf_field_type *floating_point,
 409                 unsigned int mantissa_digits);
 410
 411 /*
 412  * bt_ctf_field_type_structure_create: create a structure field type.
 413  *
 414  * Allocate a new structure field type. The creation of a field type sets
 415  * its reference count to 1.
 416  *
 417  * Returns an allocated field type on success, NULL on error.
 418  */
 419 extern struct bt_ctf_field_type *bt_ctf_field_type_structure_create(void);
 420
 421 /*
 422  * bt_ctf_field_type_structure_add_field: add a field to a structure.
 423  *
 424  * Add a field of type "field_type" to the structure. The structure will share
 425  * field_type's ownership by increasing its reference count.
 426  *
 427  * @param structure Structure type.
 428  * @param field_type Type of the field to add to the structure type.
 429  * @param field_name Name of the structure's new field (will be copied).
 430  *
 431  * Returns 0 on success, a negative value on error.
 432  */
 433 extern int bt_ctf_field_type_structure_add_field(
 434                 struct bt_ctf_field_type *structure,
 435                 struct bt_ctf_field_type *field_type,
 436                 const char *field_name);
 437
 438 /*
 439  * bt_ctf_field_type_structure_get_field_count: Get the number of fields defined
 440  *      in the structure.
 441  *
 442  * @param structure Structure type.
 443  *
 444  * Returns the field count on success, a negative value on error.
 445  */
 446 extern int bt_ctf_field_type_structure_get_field_count(
 447                 struct bt_ctf_field_type *structure);
 448
 449 /*
 450  * bt_ctf_field_type_structure_get_field: get a structure's field type and name.
 451  *
 452  * @param structure Structure type.
 453  * @param field_type Pointer to a const char* where the field's name will
 454  *      be returned.
 455  * @param field_type Pointer to a bt_ctf_field_type* where the field's type will
 456  *      be returned.
 457  * @param index Index of field.
 458  *
 459  * Returns 0 on success, a negative value on error.
 460  */
 461 extern int bt_ctf_field_type_structure_get_field(
 462                 struct bt_ctf_field_type *structure,
 463                 const char **field_name, struct bt_ctf_field_type **field_type,
 464                 int index);
 465
 466 /*
 467  * bt_ctf_field_type_structure_get_field_type_by_name: get a structure field's
 468  *      type by name.
 469  *
 470  * @param structure Structure type.
 471  * @param field_name Name of the structure's field.
 472  *
 473  * Returns a field type instance on success, NULL on error.
 474  */
 475 extern
 476 struct bt_ctf_field_type *bt_ctf_field_type_structure_get_field_type_by_name(
 477                 struct bt_ctf_field_type *structure, const char *field_name);
 478
 479 /*
 480  * bt_ctf_field_type_variant_create: create a variant field type.
 481  *
 482  * Allocate a new variant field type. The creation of a field type sets
 483  * its reference count to 1. tag_name must be the name of an enumeration
 484  * field declared in the same scope as this variant.
 485  *
 486  * @param enum_tag Type of the variant's tag/selector (must be an enumeration).
 487  * @param tag_name Name of the variant's tag/selector field (will be copied).
 488  *
 489  * Returns an allocated field type on success, NULL on error.
 490  */
 491 extern struct bt_ctf_field_type *bt_ctf_field_type_variant_create(
 492                 struct bt_ctf_field_type *enum_tag, const char *tag_name);
 493
 494 /*
 495  * bt_ctf_field_type_variant_get_tag_type: get a variant's tag type.
 496  *
 497  * @param variant Variant type.
 498  *
 499  * Returns a field type instance on success, NULL if unset.
 500  */
 501 extern struct bt_ctf_field_type *bt_ctf_field_type_variant_get_tag_type(
 502                 struct bt_ctf_field_type *variant);
 503
 504 /*
 505  * bt_ctf_field_type_variant_get_tag_name: get a variant's tag name.
 506  *
 507  * @param variant Variant type.
 508  *
 509  * Returns the tag field's name, NULL if unset.
 510  */
 511 extern const char *bt_ctf_field_type_variant_get_tag_name(
 512                 struct bt_ctf_field_type *variant);
 513
 514 /*
 515  * bt_ctf_field_type_variant_set_tag_name: set a variant's tag name.
 516  *
 517  * @param variant Variant type.
 518  * @param name Tag field name.
 519  *
 520  * Returns 0 on success, a negative value on error.
 521  */
 522 extern int bt_ctf_field_type_variant_set_tag_name(
 523                 struct bt_ctf_field_type *variant, const char *name);
 524
 525 /*
 526  * bt_ctf_field_type_variant_add_field: add a field to a variant.
 527  *
 528  * Add a field of type "field_type" to the variant. The variant will share
 529  * field_type's ownership by increasing its reference count. The "field_name"
 530  * will be copied. field_name must match a mapping in the tag/selector
 531  * enumeration.
 532  *
 533  * @param variant Variant type.
 534  * @param field_type Type of the variant type's new field.
 535  * @param field_name Name of the variant type's new field (will be copied).
 536  *
 537  * Returns 0 on success, a negative value on error.
 538  */
 539 extern int bt_ctf_field_type_variant_add_field(
 540                 struct bt_ctf_field_type *variant,
 541                 struct bt_ctf_field_type *field_type,
 542                 const char *field_name);
 543
 544 /*
 545  * bt_ctf_field_type_variant_get_field_type_by_name: get variant field's type.
 546  *
 547  * @param structure Variant type.
 548  * @param field_name Name of the variant's field.
 549  *
 550  * Returns a field type instance on success, NULL on error.
 551  */
 552 extern
 553 struct bt_ctf_field_type *bt_ctf_field_type_variant_get_field_type_by_name(
 554                 struct bt_ctf_field_type *variant, const char *field_name);
 555
 556 /*
 557  * bt_ctf_field_type_variant_get_field_type_from_tag: get variant field's type.
 558  *
 559  * @param variant Variant type.
 560  * @param tag Type tag (enum).
 561  *
 562  * Returns a field type instance on success, NULL on error.
 563  */
 564 extern
 565 struct bt_ctf_field_type *bt_ctf_field_type_variant_get_field_type_from_tag(
 566                 struct bt_ctf_field_type *variant, struct bt_ctf_field *tag);
 567
 568 /*
 569  * bt_ctf_field_type_variant_get_field_count: Get the number of fields defined
 570  *      in the variant.
 571  *
 572  * @param variant Variant type.
 573  *
 574  * Returns the field count on success, a negative value on error.
 575  */
 576 extern int bt_ctf_field_type_variant_get_field_count(
 577                 struct bt_ctf_field_type *variant);
 578
 579 /*
 580  * bt_ctf_field_type_variant_get_field: get a variant's field name and type.
 581  *
 582  * @param variant Variant type.
 583  * @param field_type Pointer to a const char* where the field's name will
 584  *      be returned.
 585  * @param field_type Pointer to a bt_ctf_field_type* where the field's type will
 586  *      be returned.
 587  * @param index Index of field.
 588  *
 589  * Returns 0 on success, a negative value on error.
 590  */
 591 extern int bt_ctf_field_type_variant_get_field(
 592                 struct bt_ctf_field_type *variant, const char **field_name,
 593                 struct bt_ctf_field_type **field_type, int index);
 594
 595 /*
 596  * bt_ctf_field_type_array_create: create an array field type.
 597  *
 598  * Allocate a new array field type. The creation of a field type sets
 599  * its reference count to 1.
 600  *
 601  * @param element_type Array's element type.
 602  * @oaram length Array type's length.
 603  *
 604  * Returns an allocated field type on success, NULL on error.
 605  */
 606 extern struct bt_ctf_field_type *bt_ctf_field_type_array_create(
 607                 struct bt_ctf_field_type *element_type, unsigned int length);
 608
 609 /*
 610  * bt_ctf_field_type_array_get_element_type: get an array's element type.
 611  *
 612  * @param array Array type.
 613  *
 614  * Returns a field type instance on success, NULL on error.
 615  */
 616 extern struct bt_ctf_field_type *bt_ctf_field_type_array_get_element_type(
 617                 struct bt_ctf_field_type *array);
 618
 619 /*
 620  * bt_ctf_field_type_array_get_length: get an array's length.
 621  *
 622  * @param array Array type.
 623  *
 624  * Returns the array's length on success, a negative value on error.
 625  */
 626 extern int64_t bt_ctf_field_type_array_get_length(
 627                 struct bt_ctf_field_type *array);
 628
 629 /*
 630  * bt_ctf_field_type_sequence_create: create a sequence field type.
 631  *
 632  * Allocate a new sequence field type. The creation of a field type sets
 633  * its reference count to 1. "length_field_name" must match an integer field
 634  * declared in the same scope.
 635  *
 636  * @param element_type Sequence's element type.
 637  * @param length_field_name Name of the sequence's length field (will be
 638  *      copied).
 639  *
 640  * Returns an allocated field type on success, NULL on error.
 641  */
 642 extern struct bt_ctf_field_type *bt_ctf_field_type_sequence_create(
 643                 struct bt_ctf_field_type *element_type,
 644                 const char *length_field_name);
 645
 646 /*
 647  * bt_ctf_field_type_sequence_get_element_type: get a sequence's element type.
 648  *
 649  * @param sequence Sequence type.
 650  *
 651  * Returns a field type instance on success, NULL on error.
 652  */
 653 extern struct bt_ctf_field_type *bt_ctf_field_type_sequence_get_element_type(
 654                 struct bt_ctf_field_type *sequence);
 655
 656 /*
 657  * bt_ctf_field_type_sequence_get_length_field_name: get length field name.
 658  *
 659  * @param sequence Sequence type.
 660  *
 661  * Returns the sequence's length field on success, NULL on error.
 662  */
 663 extern const char *bt_ctf_field_type_sequence_get_length_field_name(
 664                 struct bt_ctf_field_type *sequence);
 665
 666 /*
 667  * bt_ctf_field_type_string_create: create a string field type.
 668  *
 669  * Allocate a new string field type. The creation of a field type sets
 670  * its reference count to 1.
 671  *
 672  * Returns an allocated field type on success, NULL on error.
 673  */
 674 extern struct bt_ctf_field_type *bt_ctf_field_type_string_create(void);
 675
 676 /*
 677  * bt_ctf_field_type_string_get_encoding: get a string type's encoding.
 678  *
 679  * Get the string type's encoding.
 680  *
 681  * @param string_type String type.
 682  *
 683  * Returns the string's encoding on success, a BT_CTF_STRING_ENCODING_UNKNOWN
 684  * on error.
 685  */
 686 extern enum bt_ctf_string_encoding bt_ctf_field_type_string_get_encoding(
 687                 struct bt_ctf_field_type *string_type);
 688
 689 /*
 690  * bt_ctf_field_type_string_set_encoding: set a string type's encoding.
 691  *
 692  * Set the string type's encoding.
 693  *
 694  * @param string_type String type.
 695  * @param encoding String field encoding, default BT_CTF_STRING_ENCODING_ASCII.
 696  *      Valid values are BT_CTF_STRING_ENCODING_ASCII and
 697  *      BT_CTF_STRING_ENCODING_UTF8.
 698  *
 699  * Returns 0 on success, a negative value on error.
 700  */
 701 extern int bt_ctf_field_type_string_set_encoding(
 702                 struct bt_ctf_field_type *string_type,
 703                 enum bt_ctf_string_encoding encoding);
 704
 705 /*
 706  * bt_ctf_field_type_get_alignment: get a field type's alignment.
 707  *
 708  * Get the field type's alignment.
 709  *
 710  * @param type Field type.
 711  *
 712  * Returns the field type's alignment on success, a negative value on error and
 713  * 0 if the alignment is undefined (as in the case of a variant).
 714  */
 715 extern int bt_ctf_field_type_get_alignment(struct bt_ctf_field_type *type);
 716
 717 /*
 718  * bt_ctf_field_type_set_alignment: set a field type's alignment.
 719  *
 720  * Set the field type's alignment.
 721  *
 722  * @param type Field type.
 723  * @param alignment Type's alignment. Defaults to 1 (bit-aligned). However,
 724  *      some types, such as structures and string, may impose other alignment
 725  *      constraints.
 726  *
 727  * Returns 0 on success, a negative value on error.
 728  */
 729 extern int bt_ctf_field_type_set_alignment(struct bt_ctf_field_type *type,
 730                 unsigned int alignment);
 731
 732 /*
 733  * bt_ctf_field_type_get_byte_order: get a field type's byte order.
 734  *
 735  * @param type Field type.
 736  *
 737  * Returns the field type's byte order on success, a negative value on error.
 738  */
 739 extern enum bt_ctf_byte_order bt_ctf_field_type_get_byte_order(
 740                 struct bt_ctf_field_type *type);
 741
 742 /*
 743  * bt_ctf_field_type_set_byte_order: set a field type's byte order.
 744  *
 745  * Set the field type's byte order.
 746  *
 747  * @param type Field type.
 748  * @param byte_order Field type's byte order. Defaults to
 749  * BT_CTF_BYTE_ORDER_NATIVE; the trace's endianness.
 750  *
 751  * Returns 0 on success, a negative value on error.
 752  */
 753 extern int bt_ctf_field_type_set_byte_order(struct bt_ctf_field_type *type,
 754                 enum bt_ctf_byte_order byte_order);
 755
 756 /*
 757  * bt_ctf_field_type_variant_get_tag_field_path: get a variant's tag's field
 758  *      path.
 759  *
 760  * Get the variant's tag's field path.
 761  *
 762  * @param type Field type.
 763  *
 764  * Returns the field path on success, NULL on error or if no field path is set.
 765  */
 766 extern struct bt_ctf_field_path *bt_ctf_field_type_variant_get_tag_field_path(
 767                 struct bt_ctf_field_type *type);
 768
 769 /*
 770  * bt_ctf_field_type_sequence_get_length_field_path: get a sequence's length's
 771  *      field path.
 772  *
 773  * Get the sequence's length's field path.
 774  *
 775  * @param type Field type.
 776  *
 777  * Returns the field path on success, NULL on error or if no field path is set.
 778  */
 779 extern struct bt_ctf_field_path *bt_ctf_field_type_sequence_get_length_field_path(
 780                 struct bt_ctf_field_type *type);
 781
 782 /*
 783  * bt_ctf_field_type_compare: compare two field types recursively
 784  *
 785  * Compare two field types recursively.
 786  *
 787  * The registered tag field type of a variant field type is ignored:
 788  * only the tag strings are compared.
 789  *
 790  * @param type_a Field type A.
 791  * @param type_b Field type B.
 792  *
 793  * Returns 0 if both field types are semantically equivalent, a positive
 794  * value if they are not equivalent, or a negative value on error.
 795  */
 796 extern int bt_ctf_field_type_compare(struct bt_ctf_field_type *type_a,
 797                 struct bt_ctf_field_type *type_b);
 798
 799 /*
 800  * bt_ctf_field_type_get_type_id: get a field type's bt_ctf_type_id.
 801  *
 802  * @param type Field type.
 803  *
 804  * Returns the field type's bt_ctf_type_id, CTF_TYPE_UNKNOWN on error.
 805  */
 806 extern enum bt_ctf_type_id bt_ctf_field_type_get_type_id(
 807                 struct bt_ctf_field_type *type);
 808
 809 /*
 810  * bt_ctf_field_type_is_integer: returns whether or not a given field
 811  *      type is an integer type.
 812  *
 813  * @param type Field type.
 814  *
 815  * Returns 1 if the field type is an integer type, 0 otherwise.
 816  */
 817 extern int bt_ctf_field_type_is_integer(struct bt_ctf_field_type *type);
 818
 819 /*
 820  * bt_ctf_field_type_is_floating_point: returns whether or not a given field
 821  *      type is a floating point number type.
 822  *
 823  * @param type Field type.
 824  *
 825  * Returns 1 if the field type is a floating point number type, 0 otherwise.
 826  */
 827 extern int bt_ctf_field_type_is_floating_point(struct bt_ctf_field_type *type);
 828
 829 /*
 830  * bt_ctf_field_type_is_enumeration: returns whether or not a given field
 831  *      type is an enumeration type.
 832  *
 833  * @param type Field type.
 834  *
 835  * Returns 1 if the field type is an enumeration type, 0 otherwise.
 836  */
 837 extern int bt_ctf_field_type_is_enumeration(struct bt_ctf_field_type *type);
 838
 839 /*
 840  * bt_ctf_field_type_is_string: returns whether or not a given field
 841  *      type is a string type.
 842  *
 843  * @param type Field type.
 844  *
 845  * Returns 1 if the field type is a string type, 0 otherwise.
 846  */
 847 extern int bt_ctf_field_type_is_string(struct bt_ctf_field_type *type);
 848
 849 /*
 850  * bt_ctf_field_type_is_structure: returns whether or not a given field
 851  *      type is a structure type.
 852  *
 853  * @param type Field type.
 854  *
 855  * Returns 1 if the field type is a structure type, 0 otherwise.
 856  */
 857 extern int bt_ctf_field_type_is_structure(struct bt_ctf_field_type *type);
 858
 859 /*
 860  * bt_ctf_field_type_is_array: returns whether or not a given field
 861  *      type is an array type.
 862  *
 863  * @param type Field type.
 864  *
 865  * Returns 1 if the field type is an array type, 0 otherwise.
 866  */
 867 extern int bt_ctf_field_type_is_array(struct bt_ctf_field_type *type);
 868
 869 /*
 870  * bt_ctf_field_type_is_sequence: returns whether or not a given field
 871  *      type is a sequence type.
 872  *
 873  * @param type Field type.
 874  *
 875  * Returns 1 if the field type is a sequence type, 0 otherwise.
 876  */
 877 extern int bt_ctf_field_type_is_sequence(struct bt_ctf_field_type *type);
 878
 879 /*
 880  * bt_ctf_field_type_is_variant: returns whether or not a given field
 881  *      type is a variant type.
 882  *
 883  * @param type Field type.
 884  *
 885  * Returns 1 if the field type is a variant type, 0 otherwise.
 886  */
 887 extern int bt_ctf_field_type_is_variant(struct bt_ctf_field_type *type);
 888
 889 #ifdef __cplusplus
 890 }
 891 #endif
 892
 893 #endif /* BABELTRACE_CTF_IR_FIELD_TYPES_H */