Fields

Detailed Description

Containers of trace data.

Fields are containers of trace data: they're found in events and packets.

Fields are instances of field classes:

Borrow the class of a field with bt_field_borrow_class() and bt_field_borrow_class_const().

Fields are trace IR data objects.

There are many types of fields. They can be divided into two main categories:

Scalar

Fields which contain a simple value.

The scalar fields are:

• Boolean
• Bit array
• Integer (unsigned and signed)
• Enumeration (unsigned and signed)
• Real (single-precision and double-precision)
• String
• BLOB (static and dynamic; available since Babeltrace 2.1)

Container

Fields which contain other fields.

The container fields are:

• Array (static and dynamic)
• Structure
• Option
• Variant

Fields (green) are instances of field classes (orange).

You cannot directly create a field: there are no bt_field_*_create() functions. The Babeltrace 2 library creates fields within an event or a packet from field classes. Therefore, to fill the payload fields of an event, you must first borrow the existing payload structure field of the event with bt_event_borrow_payload_field() and then borrow each field, recursively, to set their values.

The functions to borrow a field from an event or a packet are:

• bt_packet_borrow_context_field() and bt_packet_borrow_context_field_const()
• bt_event_borrow_common_context_field() and bt_event_borrow_common_context_field_const()
• bt_event_borrow_specific_context_field() and bt_event_borrow_specific_context_field_const()
• bt_event_borrow_payload_field() and bt_event_borrow_payload_field_const()

Some fields conceptually inherit other fields, eventually making an inheritance hierarchy. For example, an enumeration field is an integer field. Therefore, an enumeration field holds an integral value, just like an integer field does.

The complete field inheritance hierarchy is:

This is the same inheritance hierarchy as the field class inheritance hierarchy.

In the illustration above:

• A field with a dark background is instantiated from a concrete field class, which you can directly create with a dedicated bt_field_class_*_create() function.

• A field with a pale background is an abstract field: it's not a concrete instance, but it can have properties, therefore there can be functions which apply to it.

  For example, bt_field_integer_signed_set_value() applies to any signed integer field.

Fields are unique objects: they belong to an event or to a packet.

Some library functions freeze fields on success. The documentation of those functions indicate this postcondition.

All the field types share the same C type, bt_field.

Get the type enumerator of the class of a field with bt_field_get_class_type(). Get whether or not a field class type conceptually is a given type with the inline bt_field_class_type_is() function.

Boolean field

A boolean field is a boolean field class instance.

A boolean field contains a boolean value (BT_TRUE or BT_FALSE).

Set the value of a boolean field with bt_field_bool_set_value().

Get the value of a boolean field with bt_field_bool_get_value().

Bit array field

A bit array field is a bit array field class instance.

A bit array field contains a fixed-length array of bits. Its length is given by its class.

The bit array field API interprets the array as an unsigned integer value: the index of the least significant bit is 0.

For example, to get whether or not bit 3 of a bit array field is set:

uint64_t value = bt_field_bit_array_get_value_as_integer(field);
 
if (value & (UINT64_C(1) << 3)) {
    // Bit 3 is set
}

Set the bits of a bit array field with bt_field_bit_array_set_value_as_integer().

Get the bits of a bit array field with bt_field_bit_array_get_value_as_integer().

Since Babeltrace 2.1, get the labels of all the active flags of the class of a bit array field for the set bits of its integral value with bt_field_bit_array_get_active_flag_labels().

Integer fields

Integer fields are integer field class instances.

Integer fields contain integral values.

An integer field is an abstract field. The concrete integer fields are:

Unsigned integer field

An unsigned integer field class instance.

An unsigned integer field contains an unsigned integral value (uint64_t).

Set the value of an unsigned integer field with bt_field_integer_unsigned_set_value().

Get the value of an unsigned integer field with bt_field_integer_unsigned_get_value().

Signed integer field

A signed integer field class instance.

A signed integer field contains a signed integral value (int64_t).

Set the value of a signed integer field with bt_field_integer_signed_set_value().

Get the value of a signed integer field with bt_field_integer_signed_get_value().

Enumeration fields

Enumeration fields are enumeration field class instances.

Enumeration fields are integer fields: they contain integral values.

An enumeration field is an abstract field. The concrete enumeration fields are:

Unsigned enumeration field

An unsigned enumeration field class instance.

An unsigned enumeration field contains an unsigned integral value (uint64_t).

Set the value of an unsigned enumeration field with bt_field_integer_unsigned_set_value().

Get the value of an unsigned enumeration field with bt_field_integer_unsigned_get_value().

Get all the enumeration field class labels mapped to the value of a given unsigned enumeration field with bt_field_enumeration_unsigned_get_mapping_labels().

Signed enumeration field

A signed enumeration field class instance.

A signed enumeration field contains a signed integral value (int64_t).

Set the value of a signed enumeration field with bt_field_integer_signed_set_value().

Get the value of a signed enumeration field with bt_field_integer_signed_get_value().

Get all the enumeration field class labels mapped to the value of a given signed enumeration field with bt_field_enumeration_signed_get_mapping_labels().

Real fields

Real fields are real field class instances.

Real fields contain real values (float or double types).

A real field is an abstract field. The concrete real fields are:

Single-precision real field

A single-precision real field class instance.

A single-precision real field contains a float value.

Set the value of a single-precision real field with bt_field_real_single_precision_set_value().

Get the value of a single-precision real field with bt_field_real_single_precision_get_value().

Double-precision real field

A double-precision real field class instance.

A double-precision real field contains a double value.

Set the value of a double-precision real field with bt_field_real_double_precision_set_value().

Get the value of a double-precision real field with bt_field_real_double_precision_get_value().

String field

A string field is a string field class instance.

A string field contains an UTF-8 string value.

Set the value of a string field with bt_field_string_set_value().

Get the value of a string field with bt_field_string_get_value().

Get the length of a string field with bt_field_string_get_length().

Append a string to the current value of a string field with bt_field_string_append() and bt_field_string_append_with_length().

Clear a string field with bt_field_string_clear().

BLOB fields (available since Babeltrace 2.1)

BLOB fields are BLOB field class instances.

BLOB fields contain zero or more bytes of binary data.

Note

BLOB fields are only available when the trace class from which you create their classes was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version 1 (available since Babeltrace 2.1).

A BLOB field is an abstract field. The concrete BLOB fields are:

Static BLOB field

A static BLOB field class instance.

A static BLOB field contains a fixed number of bytes. Its length is given by its class.

Dynamic BLOB field

A dynamic BLOB field class instance.

A dynamic BLOB field contains a variable number of bytes, that is, each instance of the same dynamic BLOB field class can contain a different number of bytes.

Set the length of a dynamic BLOB field with bt_field_blob_dynamic_set_length() before you get its data with bt_field_blob_get_data().

Get the length of a BLOB field with bt_field_blob_get_length().

Get the data of a BLOB field with bt_field_blob_get_data() or bt_field_blob_get_data_const().

Array fields

Array fields are array field class instances.

Array fields contain zero or more fields which have the same class.

An array field is an abstract field. The concrete array fields are:

Static array field

A static array field class instance.

A static array field contains a fixed number of fields. Its length is given by its class.

Dynamic array field

A dynamic array field class instance.

A dynamic array field contains a variable number of fields, that is, each instance of the same dynamic array field class can contain a different number of elements.

Set the length of a dynamic array field with bt_field_array_dynamic_set_length() before you borrow any of its fields.

Get the length of an array field with bt_field_array_get_length().

Borrow a field from an array field at a given index with bt_field_array_borrow_element_field_by_index() and bt_field_array_borrow_element_field_by_index_const().

Structure field

A structure field is a structure field class instance.

A structure field contains an ordered list of zero or more members. A structure field member contains a field: it's an instance of a structure field class member.

Borrow the field of a member from a structure field at a given index with bt_field_structure_borrow_member_field_by_index() and bt_field_structure_borrow_member_field_by_index_const().

Borrow the field of a member from a structure field by name with bt_field_structure_borrow_member_field_by_name() and bt_field_structure_borrow_member_field_by_name_const().

Option field

An option field is an option field class instance.

An option field either does or doesn't contain a field.

Set whether or not an option field has a field with bt_field_option_set_has_field().

Borrow the field from an option field with bt_field_option_borrow_field() or bt_field_option_borrow_field_const().

Variant field

A variant field is a variant field class instance.

A variant field has a single selected option amongst one or more possible options. A variant field option contains a field: it's an instance of a variant field class option.

Set the current option of a variant field with bt_field_variant_select_option_by_index().

Get the selected option index of a variant field with bt_field_variant_get_selected_option_index().

Borrow the field of the selected option of a variant field with bt_field_variant_borrow_selected_option_field() and bt_field_variant_borrow_selected_option_field_const().

Borrow the class of the selected option of a variant field with bt_field_variant_borrow_selected_option_class_const(), bt_field_variant_with_selector_field_integer_unsigned_borrow_selected_option_class_const(), and bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const().

Bit array field
enum	bt_field_bit_array_get_active_flag_labels_status {   BT_FIELD_BIT_ARRAY_GET_ACTIVE_FLAG_LABELS_STATUS_OK ,   BT_FIELD_BIT_ARRAY_GET_ACTIVE_FLAG_LABELS_STATUS_MEMORY_ERROR }
	Status codes for bt_field_bit_array_get_active_flag_labels(). More...
typedef enum bt_field_bit_array_get_active_flag_labels_status	bt_field_bit_array_get_active_flag_labels_status
	Status codes for bt_field_bit_array_get_active_flag_labels().
void	bt_field_bit_array_set_value_as_integer (bt_field *field, uint64_t bits)
	Sets the bits of the bit array field field to the bits of bits.
uint64_t	bt_field_bit_array_get_value_as_integer (const bt_field *field)
	Returns the bits of the bit array field field as an unsigned integer.
bt_field_bit_array_get_active_flag_labels_status	bt_field_bit_array_get_active_flag_labels (const bt_field *field, bt_field_class_bit_array_flag_label_array *labels, uint64_t *count)
	Returns the labels of all the active flags of the class of the bit array field field for the set bits of the integral value of field.

Enumeration field
enum	bt_field_enumeration_get_mapping_labels_status {   BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK ,   BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR }
	Status codes for bt_field_enumeration_unsigned_get_mapping_labels() and bt_field_enumeration_signed_get_mapping_labels(). More...
typedef enum bt_field_enumeration_get_mapping_labels_status	bt_field_enumeration_get_mapping_labels_status
	Status codes for bt_field_enumeration_unsigned_get_mapping_labels() and bt_field_enumeration_signed_get_mapping_labels().
bt_field_enumeration_get_mapping_labels_status	bt_field_enumeration_unsigned_get_mapping_labels (const bt_field *field, bt_field_class_enumeration_mapping_label_array *labels, uint64_t *count)
	Returns an array of all the labels of the mappings of the class of the unsigned enumeration field field of which the unsigned integer ranges contain the integral value of field.
bt_field_enumeration_get_mapping_labels_status	bt_field_enumeration_signed_get_mapping_labels (const bt_field *field, bt_field_class_enumeration_mapping_label_array *labels, uint64_t *count)
	Returns an array of all the labels of the mappings of the class of the signed enumeration field field of which the signed integer ranges contain the integral value of field.

String field
enum	bt_field_string_set_value_status {   BT_FIELD_STRING_SET_VALUE_STATUS_OK ,   BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR }
	Status codes for bt_field_string_set_value(). More...
enum	bt_field_string_append_status {   BT_FIELD_STRING_APPEND_STATUS_OK ,   BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR }
	Status codes for bt_field_string_append() and bt_field_string_append_with_length(). More...
typedef enum bt_field_string_set_value_status	bt_field_string_set_value_status
	Status codes for bt_field_string_set_value().
typedef enum bt_field_string_append_status	bt_field_string_append_status
	Status codes for bt_field_string_append() and bt_field_string_append_with_length().
bt_field_string_set_value_status	bt_field_string_set_value (bt_field *field, const char *value)
	Sets the value of the string field field to a copy of value.
uint64_t	bt_field_string_get_length (const bt_field *field)
	Returns the length of the string field field.
const char *	bt_field_string_get_value (const bt_field *field)
	Returns the value of the string field field.
bt_field_string_append_status	bt_field_string_append (bt_field *field, const char *value)
	Appends a copy of the string value to the current value of the string field field.
bt_field_string_append_status	bt_field_string_append_with_length (bt_field *field, const char *value, uint64_t length)
	Appends a copy of the first length bytes of the string value to the current value of the string field field.
void	bt_field_string_clear (bt_field *field)
	Clears the string field field, making its value an empty string.

BLOB field (available since Babeltrace 2.1)
enum	bt_field_blob_dynamic_set_length_status {   BT_FIELD_DYNAMIC_BLOB_SET_LENGTH_STATUS_OK ,   BT_FIELD_DYNAMIC_BLOB_SET_LENGTH_STATUS_MEMORY_ERROR }
	Status codes for bt_field_blob_dynamic_set_length(). More...
typedef enum bt_field_blob_dynamic_set_length_status	bt_field_blob_dynamic_set_length_status
	Status codes for bt_field_blob_dynamic_set_length().
uint64_t	bt_field_blob_get_length (const bt_field *field)
	Returns the length (number of bytes) of the BLOB field field.
uint8_t *	bt_field_blob_get_data (bt_field *field)
	Returns the writable data of the BLOB field field.
const uint8_t *	bt_field_blob_get_data_const (const bt_field *field)
	Returns the readable data of the BLOB field field.
bt_field_blob_dynamic_set_length_status	bt_field_blob_dynamic_set_length (bt_field *field, uint64_t length)
	Sets the length (number of bytes) of the dynamic BLOB field field.

Array field
enum	bt_field_array_dynamic_set_length_status {   BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_OK ,   BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR }
	Status codes for bt_field_array_dynamic_set_length(). More...
typedef enum bt_field_array_dynamic_set_length_status	bt_field_array_dynamic_set_length_status
	Status codes for bt_field_array_dynamic_set_length().
uint64_t	bt_field_array_get_length (const bt_field *field)
	Returns the length of the array field field.
bt_field *	bt_field_array_borrow_element_field_by_index (bt_field *field, uint64_t index)
	Borrows the field at index index from the array field field.
const bt_field *	bt_field_array_borrow_element_field_by_index_const (const bt_field *field, uint64_t index)
	Borrows the field at index index from the array field field (const version).
bt_field_array_dynamic_set_length_status	bt_field_array_dynamic_set_length (bt_field *field, uint64_t length)
	Sets the length of the dynamic array field field.

Variant field
enum	bt_field_variant_select_option_by_index_status { BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK }
	Status code for bt_field_variant_select_option_by_index(). More...
typedef enum bt_field_variant_select_option_by_index_status	bt_field_variant_select_option_by_index_status
	Status code for bt_field_variant_select_option_by_index().
bt_field_variant_select_option_by_index_status	bt_field_variant_select_option_by_index (bt_field *field, uint64_t index)
	Sets the selected option of the variant field field to the option at index index.
bt_field *	bt_field_variant_borrow_selected_option_field (bt_field *field)
	Borrows the field of the selected option of the variant field field.
const bt_field *	bt_field_variant_borrow_selected_option_field_const (const bt_field *field)
	Borrows the field of the selected option of the variant field field (const version).
uint64_t	bt_field_variant_get_selected_option_index (const bt_field *field)
	Returns the index of the selected option of the variant field field.
const bt_field_class_variant_option *	bt_field_variant_borrow_selected_option_class_const (const bt_field *field)
	Borrows the class of the selected option of the variant field field.
const bt_field_class_variant_with_selector_field_integer_unsigned_option *	bt_field_variant_with_selector_field_integer_unsigned_borrow_selected_option_class_const (const bt_field *field)
	Borrows the class of the selected option of the variant field (with an unsigned integer selector field) field.
const bt_field_class_variant_with_selector_field_integer_signed_option *	bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const (const bt_field *field)
	Borrows the class of the selected option of the variant field (with a signed integer selector field) field.

Type
typedef struct bt_field	bt_field
	Field.

Type query
bt_field_class_type	bt_field_get_class_type (const bt_field *field)
	Returns the type enumerator of the class of the field field.

Class access
bt_field_class *	bt_field_borrow_class (bt_field *field)
	Borrows the class of the field field.
const bt_field_class *	bt_field_borrow_class_const (const bt_field *field)
	Borrows the class of the field field (const version).

Boolean field
void	bt_field_bool_set_value (bt_field *field, bt_bool value)
	Sets the value of the boolean field field to value.
bt_bool	bt_field_bool_get_value (const bt_field *field)
	Returns the value of the boolean field field.

Integer field
void	bt_field_integer_unsigned_set_value (bt_field *field, uint64_t value)
	Sets the value of the unsigned integer field field to value.
uint64_t	bt_field_integer_unsigned_get_value (const bt_field *field)
	Returns the value of the unsigned integer field field.
void	bt_field_integer_signed_set_value (bt_field *field, int64_t value)
	Sets the value of the signed integer field field to value.
int64_t	bt_field_integer_signed_get_value (const bt_field *field)
	Returns the value of the signed integer field field.

Real field
void	bt_field_real_single_precision_set_value (bt_field *field, float value)
	Sets the value of the single-precision real field field to value.
float	bt_field_real_single_precision_get_value (const bt_field *field)
	Returns the value of the single-precision real field field.
void	bt_field_real_double_precision_set_value (bt_field *field, double value)
	Sets the value of the double-precision real field field to value.
double	bt_field_real_double_precision_get_value (const bt_field *field)
	Returns the value of the double-precision real field field.

Structure field
bt_field *	bt_field_structure_borrow_member_field_by_index (bt_field *field, uint64_t index)
	Borrows the field of the member at index index from the structure field field.
const bt_field *	bt_field_structure_borrow_member_field_by_index_const (const bt_field *field, uint64_t index)
	Borrows the field of the member at index index from the structure field field (const version).
bt_field *	bt_field_structure_borrow_member_field_by_name (bt_field *field, const char *name)
	Borrows the field of the member having the name name from the structure field field.
const bt_field *	bt_field_structure_borrow_member_field_by_name_const (const bt_field *field, const char *name)
	Borrows the field of the member having the name name from the structure field field (const version).

Option field
void	bt_field_option_set_has_field (bt_field *field, bt_bool has_field)
	Sets whether or not the option field field has a field.
bt_field *	bt_field_option_borrow_field (bt_field *field)
	Borrows the field of the option field field.
const bt_field *	bt_field_option_borrow_field_const (const bt_field *field)
	Borrows the field of the option field field (const version).

Typedef Documentation

bt_field_bit_array_get_active_flag_labels_status

typedef enum bt_field_bit_array_get_active_flag_labels_status bt_field_bit_array_get_active_flag_labels_status

Status codes for bt_field_bit_array_get_active_flag_labels().

Since

Babeltrace 2.1

bt_field_blob_dynamic_set_length_status

typedef enum bt_field_blob_dynamic_set_length_status bt_field_blob_dynamic_set_length_status

Status codes for bt_field_blob_dynamic_set_length().

Since

Babeltrace 2.1

Enumeration Type Documentation

bt_field_bit_array_get_active_flag_labels_status

enum bt_field_bit_array_get_active_flag_labels_status

Status codes for bt_field_bit_array_get_active_flag_labels().

Since

Babeltrace 2.1

Enumerator
BT_FIELD_BIT_ARRAY_GET_ACTIVE_FLAG_LABELS_STATUS_OK	Success.
BT_FIELD_BIT_ARRAY_GET_ACTIVE_FLAG_LABELS_STATUS_MEMORY_ERROR	Out of memory.

bt_field_enumeration_get_mapping_labels_status

enum bt_field_enumeration_get_mapping_labels_status

Status codes for bt_field_enumeration_unsigned_get_mapping_labels() and bt_field_enumeration_signed_get_mapping_labels().

Enumerator
BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK	Success.
BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR	Out of memory.

bt_field_string_set_value_status

enum bt_field_string_set_value_status

Status codes for bt_field_string_set_value().

Enumerator
BT_FIELD_STRING_SET_VALUE_STATUS_OK	Success.
BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR	Out of memory.

bt_field_string_append_status

enum bt_field_string_append_status

Status codes for bt_field_string_append() and bt_field_string_append_with_length().

Enumerator
BT_FIELD_STRING_APPEND_STATUS_OK	Success.
BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR	Out of memory.

bt_field_blob_dynamic_set_length_status

enum bt_field_blob_dynamic_set_length_status

Status codes for bt_field_blob_dynamic_set_length().

Since

Babeltrace 2.1

Enumerator
BT_FIELD_DYNAMIC_BLOB_SET_LENGTH_STATUS_OK	Success.
BT_FIELD_DYNAMIC_BLOB_SET_LENGTH_STATUS_MEMORY_ERROR	Out of memory.

bt_field_array_dynamic_set_length_status

enum bt_field_array_dynamic_set_length_status

Status codes for bt_field_array_dynamic_set_length().

Enumerator
BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_OK	Success.
BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR	Out of memory.

bt_field_variant_select_option_by_index_status

enum bt_field_variant_select_option_by_index_status

Status code for bt_field_variant_select_option_by_index().

Enumerator
BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK	Success.

Function Documentation

bt_field_get_class_type()

bt_field_class_type bt_field_get_class_type ( const bt_field * field )

extern

Returns the type enumerator of the class of the field field.

This function returns

bt_field_class_get_type(bt_field_borrow_class(field))

Parameters

[in]

field

Field of which to get the type enumerator of its class.

Returns

Type enumerator of the class of field.

Precondition

field is not NULL.

See also

bt_field_class_get_type() — Returns the type enumerator of a field class.

bt_field_borrow_class()

bt_field_class * bt_field_borrow_class ( bt_field * field )

extern

Borrows the class of the field field.

Parameters

[in]

field

Field of which to borrow the class.

Returns

Borrowed reference of the class of field.

Precondition

field is not NULL.

See also

bt_field_borrow_class_const() — const version of this function.

bt_field_borrow_class_const()

const bt_field_class * bt_field_borrow_class_const ( const bt_field * field )

extern

Borrows the class of the field field (const version).

See bt_field_borrow_class().

bt_field_bool_set_value()

void bt_field_bool_set_value ( bt_field * field, bt_bool value )

extern

Sets the value of the boolean field field to value.

Parameters

[in]	field	Boolean field of which to set the value to value.
[in]	value	New value of field.

Precondition

field is not NULL.

field is a boolean field.

field is not frozen.

See also

bt_field_bool_get_value() — Returns the value of a boolean field.

bt_field_bool_get_value()

bt_bool bt_field_bool_get_value ( const bt_field * field )

extern

Returns the value of the boolean field field.

Parameters

[in]

field

Boolean field of which to get the value.

Returns

Value of field.

Precondition

field is not NULL.

field is a boolean field.

See also

bt_field_bool_set_value() — Sets the value of a boolean field.

bt_field_bit_array_set_value_as_integer()

void bt_field_bit_array_set_value_as_integer ( bt_field * field, uint64_t bits )

extern

Sets the bits of the bit array field field to the bits of bits.

The index of the least significant bit is 0.

See Bit array field to learn more.

Parameters

[in]	field	Bit array field of which to set the bits to bits.
[in]	bits	New bits of field.

Precondition

field is not NULL.

field is a bit array field.

field is not frozen.

See also

bt_field_bit_array_get_value_as_integer() — Returns the bits of a bit array field as an integer.

bt_field_bit_array_get_value_as_integer()

uint64_t bt_field_bit_array_get_value_as_integer ( const bt_field * field )

extern

Returns the bits of the bit array field field as an unsigned integer.

The index of the least significant bit is 0.

See Bit array field to learn more.

Parameters

[in]

field

Bit array field of which to get the bits.

Returns

Bits of field as an unsigned integer.

Precondition

field is not NULL.

field is a bit array field.

See also

bt_field_bit_array_set_value_as_integer() — Sets the bits of a bit array field from an integer.

bt_field_bit_array_get_active_flag_labels()

bt_field_bit_array_get_active_flag_labels_status bt_field_bit_array_get_active_flag_labels ( const bt_field * field, bt_field_class_bit_array_flag_label_array * labels, uint64_t * count )

extern

Returns the labels of all the active flags of the class of the bit array field field for the set bits of the integral value of field.

This function returns

(bt_field_bit_array_get_active_flag_labels_status)
bt_field_class_bit_array_get_active_flag_labels_for_value_as_integer(
    bt_field_borrow_class_const(field),
    bt_field_bit_array_get_value_as_integer(field),
    labels, count)

Parameters

[in]	field	Bit array field having the class from which to get the labels of the active flags for the integral value of field.
[out]	labels	See bt_field_class_bit_array_get_active_flag_labels_for_value_as_integer().
[out]	count	See bt_field_class_bit_array_get_active_flag_labels_for_value_as_integer().

Return values

BT_FIELD_BIT_ARRAY_GET_ACTIVE_FLAG_LABELS_STATUS_OK	Success.
BT_FIELD_BIT_ARRAY_GET_ACTIVE_FLAG_LABELS_STATUS_MEMORY_ERROR	Out of memory.

Since

Babeltrace 2.1

Precondition

field is not NULL.

field is a bit array field.

The class of field was created from a trace class which was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version  1.

labels is not NULL.

count is not NULL.

bt_field_integer_unsigned_set_value()

void bt_field_integer_unsigned_set_value ( bt_field * field, uint64_t value )

extern

Sets the value of the unsigned integer field field to value.

Parameters

[in]	field	Unsigned integer field of which to set the value to value.
[in]	value	New value of field.

Precondition

field is not NULL.

field is an unsigned integer field.

field is not frozen.

value is within the field value range of the class of field.

See also

bt_field_integer_unsigned_get_value() — Returns the value of an unsigned integer field.

bt_field_integer_unsigned_get_value()

uint64_t bt_field_integer_unsigned_get_value ( const bt_field * field )

extern

Returns the value of the unsigned integer field field.

Parameters

[in]

field

Unsigned integer field of which to get the value.

Returns

Value of field.

Precondition

field is not NULL.

field is an unsigned integer field.

See also

bt_field_integer_unsigned_set_value() — Sets the value of an unsigned integer field.

bt_field_integer_signed_set_value()

void bt_field_integer_signed_set_value ( bt_field * field, int64_t value )

extern

Sets the value of the signed integer field field to value.

Parameters

[in]	field	Signed integer field of which to set the value to value.
[in]	value	New value of field.

Precondition

field is not NULL.

field is a signed integer field.

field is not frozen.

value is within the field value range of the class of field.

See also

bt_field_integer_signed_get_value() — Returns the value of an signed integer field.

bt_field_integer_signed_get_value()

int64_t bt_field_integer_signed_get_value ( const bt_field * field )

extern

Returns the value of the signed integer field field.

Parameters

[in]

field

Signed integer field of which to get the value.

Returns

Value of field.

Precondition

field is not NULL.

field is a signed integer field.

See also

bt_field_integer_signed_set_value() — Sets the value of an signed integer field.

bt_field_enumeration_unsigned_get_mapping_labels()

bt_field_enumeration_get_mapping_labels_status bt_field_enumeration_unsigned_get_mapping_labels ( const bt_field * field, bt_field_class_enumeration_mapping_label_array * labels, uint64_t * count )

extern

Returns an array of all the labels of the mappings of the class of the unsigned enumeration field field of which the unsigned integer ranges contain the integral value of field.

This function returns

(bt_field_enumeration_get_mapping_labels_status)
bt_field_class_enumeration_unsigned_get_mapping_labels_for_value(
    bt_field_borrow_class_const(field),
    bt_field_integer_unsigned_get_value(field),
    labels, count)

Parameters

[in]	field	Unsigned enumeration field having the class from which to get the labels of the mappings of which the ranges contain its integral value.
[out]	labels	See bt_field_class_enumeration_unsigned_get_mapping_labels_for_value().
[out]	count	See bt_field_class_enumeration_unsigned_get_mapping_labels_for_value().

Return values

BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK	Success.
BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR	Out of memory.

Precondition

field is not NULL.

field is an unsigned enumeration field.

labels is not NULL.

count is not NULL.

bt_field_enumeration_signed_get_mapping_labels()

bt_field_enumeration_get_mapping_labels_status bt_field_enumeration_signed_get_mapping_labels ( const bt_field * field, bt_field_class_enumeration_mapping_label_array * labels, uint64_t * count )

extern

Returns an array of all the labels of the mappings of the class of the signed enumeration field field of which the signed integer ranges contain the integral value of field.

This function returns

(bt_field_enumeration_get_mapping_labels_status)
bt_field_class_enumeration_signed_get_mapping_labels_for_value(
    bt_field_borrow_class_const(field),
    bt_field_integer_signed_get_value(field),
    labels, count)

Parameters

[in]	field	Signed enumeration field having the class from which to get the labels of the mappings of which the ranges contain its integral value.
[out]	labels	See bt_field_class_enumeration_signed_get_mapping_labels_for_value().
[out]	count	See bt_field_class_enumeration_signed_get_mapping_labels_for_value().

Return values

BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK	Success.
BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR	Out of memory.

Precondition

field is not NULL.

field is a signed enumeration field.

labels is not NULL.

count is not NULL.

bt_field_real_single_precision_set_value()

void bt_field_real_single_precision_set_value ( bt_field * field, float value )

extern

Sets the value of the single-precision real field field to value.

Parameters

[in]	field	Single-precision real field of which to set the value to value.
[in]	value	New value of field.

Precondition

field is not NULL.

field is a single-precision real field.

field is not frozen.

See also

bt_field_real_single_precision_get_value() — Returns the value of a single-precision real field.

bt_field_real_single_precision_get_value()

float bt_field_real_single_precision_get_value ( const bt_field * field )

extern

Returns the value of the single-precision real field field.

Parameters

[in]

field

Single-precision real field of which to get the value.

Returns

Value of field.

Precondition

field is not NULL.

field is a single-precision real field.

See also

bt_field_real_single_precision_set_value() — Sets the value of a single-precision real field.

bt_field_real_double_precision_set_value()

void bt_field_real_double_precision_set_value ( bt_field * field, double value )

extern

Sets the value of the double-precision real field field to value.

Parameters

[in]	field	Double-precision real field of which to set the value to value.
[in]	value	New value of field.

Precondition

field is not NULL.

field is a double-precision real field.

field is not frozen.

See also

bt_field_real_double_precision_get_value() — Returns the value of a double-precision real field.

bt_field_real_double_precision_get_value()

double bt_field_real_double_precision_get_value ( const bt_field * field )

extern

Returns the value of the double-precision real field field.

Parameters

[in]

field

Double-precision real field of which to get the value.

Returns

Value of field.

Precondition

field is not NULL.

field is a double-precision real field.

See also

bt_field_real_double_precision_set_value() — Sets the value of a double-precision real field.

bt_field_string_set_value()

bt_field_string_set_value_status bt_field_string_set_value ( bt_field * field, const char * value )

extern

Sets the value of the string field field to a copy of value.

Parameters

[in]	field	String field of which to set the value to value.
[in]	value	New value of field (copied).

Return values

BT_FIELD_STRING_SET_VALUE_STATUS_OK	Success.
BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR	Out of memory.

Precondition

field is not NULL.

field is a string field.

field is not frozen.

value is not NULL.

See also

bt_field_string_get_value() — Returns the value of a string field.

bt_field_string_append() — Appends a string to a string field.

bt_field_string_clear() — Clears a string field.

bt_field_string_get_length()

uint64_t bt_field_string_get_length ( const bt_field * field )

extern

Returns the length of the string field field.

Parameters

[in]

field

String field of which to get the length.

Returns

Length of field.

Precondition

field is not NULL.

field is a string field.

bt_field_string_get_value()

const char * bt_field_string_get_value ( const bt_field * field )

extern

Returns the value of the string field field.

Parameters

[in]

field

String field of which to get the value.

Returns

Value of field.

The returned pointer remains valid until field is modified.

Precondition

field is not NULL.

field is a string field.

See also

bt_field_string_set_value() — Sets the value of a string field.

bt_field_string_append()

bt_field_string_append_status bt_field_string_append ( bt_field * field, const char * value )

extern

Appends a copy of the string value to the current value of the string field field.

Attention

If you didn't set the value of field yet, then you must call bt_field_string_clear() before you call this function.

Parameters

[in]	field	String field to which to append the string value.
[in]	value	String to append to field (copied).

Return values

BT_FIELD_STRING_APPEND_STATUS_OK	Success.
BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR	Out of memory.

Precondition

field is not NULL.

field is a string field.

field is not frozen.

value is not NULL.

See also

bt_field_string_append_with_length() — Appends a string with a given length to a string field.

bt_field_string_set_value() — Sets the value of a string field.

bt_field_string_append_with_length()

bt_field_string_append_status bt_field_string_append_with_length ( bt_field * field, const char * value, uint64_t length )

extern

Appends a copy of the first length bytes of the string value to the current value of the string field field.

Attention

If you didn't set the value of field yet, then you must call bt_field_string_clear() before you call this function.

Parameters

[in]	field	String field to which to append the first length bytes of the string value.
[in]	value	String of which to append the first length bytes to field (copied).
[in]	length	Number of bytes of value to append to field.

Return values

BT_FIELD_STRING_APPEND_STATUS_OK	Success.
BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR	Out of memory.

Precondition

field is not NULL.

field is a string field.

field is not frozen.

value is not NULL.

See also

bt_field_string_append() — Appends a string to a string field.

bt_field_string_set_value() — Sets the value of a string field.

bt_field_string_clear()

void bt_field_string_clear ( bt_field * field )

extern

Clears the string field field, making its value an empty string.

Parameters

[in]

field

String field to clear.

Precondition

field is not NULL.

field is a string field.

field is not frozen.

See also

bt_field_string_set_value() — Sets the value of a string field.

bt_field_blob_get_length()

uint64_t bt_field_blob_get_length ( const bt_field * field )

extern

Returns the length (number of bytes) of the BLOB field field.

Parameters

[in]

field

BLOB field of which to get the length.

Returns

Length of field.

Since

Babeltrace 2.1

Precondition

field is not NULL.

field is a BLOB field.

The class of field was created from a trace class which was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version  1.

bt_field_blob_get_data()

uint8_t * bt_field_blob_get_data ( bt_field * field )

extern

Returns the writable data of the BLOB field field.

Attention

If field is a dynamic BLOB field, then it must have a length (call bt_field_blob_dynamic_set_length()) before you call this function.

Parameters

[in]

field

BLOB field from which to get the writable data.

Returns

Writable data of field.

The returned pointer remains valid until field is modified.

Since

Babeltrace 2.1

Precondition

field is not NULL.

field is a BLOB field.

field is not frozen.

The class of field was created from a trace class which was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version  1.

See also

bt_field_blob_get_data_const() — Returns the readable data of a BLOB field.

bt_field_blob_get_data_const()

const uint8_t * bt_field_blob_get_data_const ( const bt_field * field )

extern

Returns the readable data of the BLOB field field.

Parameters

[in]

field

BLOB field from which to get the readable data.

Returns

Readable data of field.

The returned pointer remains valid until field is modified.

Since

Babeltrace 2.1

Precondition

field is not NULL.

field is a BLOB field.

The class of field was created from a trace class which was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version  1.

See also

bt_field_blob_get_data() — Returns the writable data of a BLOB field.

bt_field_blob_dynamic_set_length()

bt_field_blob_dynamic_set_length_status bt_field_blob_dynamic_set_length ( bt_field * field, uint64_t length )

extern

Sets the length (number of bytes) of the dynamic BLOB field field.

Parameters

[in]	field	Dynamic BLOB field of which to set the length (number of bytes).
[in]	length	New length of field.

Return values

BT_FIELD_DYNAMIC_BLOB_SET_LENGTH_STATUS_OK	Success.
BT_FIELD_DYNAMIC_BLOB_SET_LENGTH_STATUS_MEMORY_ERROR	Out of memory.

Since

Babeltrace 2.1

Precondition

field is not NULL.

field is a dynamic BLOB field.

field is not frozen.

The class of field was created from a trace class which was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version  1.

bt_field_array_get_length()

uint64_t bt_field_array_get_length ( const bt_field * field )

extern

Returns the length of the array field field.

Parameters

[in]

field

Array field of which to get the length.

Returns

Length of field.

Precondition

field is not NULL.

field is an array field.

bt_field_array_borrow_element_field_by_index()

bt_field * bt_field_array_borrow_element_field_by_index ( bt_field * field, uint64_t index )

extern

Borrows the field at index index from the array field field.

Attention

If field is a dynamic array field, then it must have a length (call bt_field_array_dynamic_set_length()) before you call this function.

Parameters

[in]	field	Array field from which to borrow the field at index index.
[in]	index	Index of the field to borrow from field.

Returns

Borrowed reference of the field of field at index index.

The returned pointer remains valid as long as field exists.

Precondition

field is not NULL.

field is an array field.

index is less than the length of field (as returned by bt_field_array_get_length()).

See also

bt_field_array_borrow_element_field_by_index_const() — const version of this function.

bt_field_array_borrow_element_field_by_index_const()

const bt_field * bt_field_array_borrow_element_field_by_index_const ( const bt_field * field, uint64_t index )

extern

Borrows the field at index index from the array field field (const version).

See bt_field_array_borrow_element_field_by_index().

bt_field_array_dynamic_set_length()

bt_field_array_dynamic_set_length_status bt_field_array_dynamic_set_length ( bt_field * field, uint64_t length )

extern

Sets the length of the dynamic array field field.

Parameters

[in]	field	Dynamic array field of which to set the length.
[in]	length	New length of field.

Return values

BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_OK	Success.
BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR	Out of memory.

Precondition

field is not NULL.

field is a dynamic array field.

field is not frozen.

bt_field_structure_borrow_member_field_by_index()

bt_field * bt_field_structure_borrow_member_field_by_index ( bt_field * field, uint64_t index )

extern

Borrows the field of the member at index index from the structure field field.

Parameters

[in]	field	Structure field from which to borrow the field of the member at index index.
[in]	index	Index of the member containing the field to borrow from field.

Returns

Borrowed reference of the field of the member of field at index index.

The returned pointer remains valid as long as field exists.

Precondition

field is not NULL.

field is a structure field.

index is less than the number of members in the class of field (as returned by bt_field_class_structure_get_member_count()).

See also

bt_field_structure_borrow_member_field_by_index_const() — const version of this function.

bt_field_structure_borrow_member_field_by_index_const()

const bt_field * bt_field_structure_borrow_member_field_by_index_const ( const bt_field * field, uint64_t index )

extern

Borrows the field of the member at index index from the structure field field (const version).

See bt_field_structure_borrow_member_field_by_index().

bt_field_structure_borrow_member_field_by_name()

bt_field * bt_field_structure_borrow_member_field_by_name ( bt_field * field, const char * name )

extern

Borrows the field of the member having the name name from the structure field field.

If there's no member having the name name in the class of field, then this function returns NULL.

Parameters

[in]	field	Structure field from which to borrow the field of the member having the name name.
[in]	name	Name of the member containing the field to borrow from field.

Returns

Borrowed reference of the field of the member of field having the name name, or NULL if none.

The returned pointer remains valid as long as field exists.

Precondition

field is not NULL.

field is a structure field.

name is not NULL.

See also

bt_field_structure_borrow_member_field_by_name_const() — const version of this function.

bt_field_structure_borrow_member_field_by_name_const()

const bt_field * bt_field_structure_borrow_member_field_by_name_const ( const bt_field * field, const char * name )

extern

Borrows the field of the member having the name name from the structure field field (const version).

See bt_field_structure_borrow_member_field_by_name().

bt_field_option_set_has_field()

void bt_field_option_set_has_field ( bt_field * field, bt_bool has_field )

extern

Sets whether or not the option field field has a field.

Parameters

[in]	field	Option field of which to set whether or not it has a field.
[in]	has_field	BT_TRUE to make field have a field.

Precondition

field is not NULL.

field is an option field.

bt_field_option_borrow_field()

bt_field * bt_field_option_borrow_field ( bt_field * field )

extern

Borrows the field of the option field field.

Attention

You must call bt_field_option_set_has_field() before you call this function.

If field has no field, then this function returns NULL.

Parameters

[in]

field

Option field from which to borrow the field.

Returns

Borrowed reference of the field of field, or NULL if none.

The returned pointer remains valid as long as field exists.

Precondition

field is not NULL.

field is an option field.

See also

bt_field_option_set_has_field() — Sets whether or not an option field has a field.

bt_field_option_borrow_field_const() — const version of this function.

bt_field_option_borrow_field_const()

const bt_field * bt_field_option_borrow_field_const ( const bt_field * field )

extern

Borrows the field of the option field field (const version).

See bt_field_option_borrow_field().

bt_field_variant_select_option_by_index()

bt_field_variant_select_option_by_index_status bt_field_variant_select_option_by_index ( bt_field * field, uint64_t index )

extern

Sets the selected option of the variant field field to the option at index index.

Parameters

[in]	field	Variant field of which to set the selected option.
[in]	index	Index of the option to set as the selected option of field.

Return values

BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK

Success.

Precondition

field is not NULL.

field is a variant field.

index is less than the number of options in the class of field (as returned by bt_field_class_variant_get_option_count()).

bt_field_variant_borrow_selected_option_field()

bt_field * bt_field_variant_borrow_selected_option_field ( bt_field * field )

extern

Borrows the field of the selected option of the variant field field.

Attention

You must call bt_field_variant_select_option_by_index() before you call this function.

Parameters

[in]

field

Variant field from which to borrow the field of its selected option.

Returns

Borrowed reference of the field of the selected option of field, or NULL if none.

The returned pointer remains valid as long as field exists.

Precondition

field is not NULL.

field is a variant field.

See also

bt_field_variant_select_option_by_index() — Sets the selected option of a variant field.

bt_field_variant_get_selected_option_index() — Returns the index of the selected option of a variant field.

bt_field_variant_borrow_selected_option_field_const() — const version of this function.

bt_field_variant_borrow_selected_option_field_const()

const bt_field * bt_field_variant_borrow_selected_option_field_const ( const bt_field * field )

extern

Borrows the field of the selected option of the variant field field (const version).

See bt_field_variant_borrow_selected_option_field().

bt_field_variant_get_selected_option_index()

uint64_t bt_field_variant_get_selected_option_index ( const bt_field * field )

extern

Returns the index of the selected option of the variant field field.

Parameters

[in]

field

Variant field of which to get the index of the selected option.

Returns

Index of the selected option of field.

Precondition

field is not NULL.

field is a variant field.

See also

bt_field_variant_borrow_selected_option_field_const() — Borrows the field of the selected option of a variant field.

bt_field_variant_borrow_selected_option_class_const()

const bt_field_class_variant_option * bt_field_variant_borrow_selected_option_class_const ( const bt_field * field )

extern

Borrows the class of the selected option of the variant field field.

This function returns

bt_field_class_variant_borrow_option_by_index(
    bt_field_variant_get_selected_option_index(field))

Parameters

[in]

field

Variant field of which to borrow the class of its selected option.

Returns

Class of the selected option of field.

Precondition

field is not NULL.

field is a variant field.

bt_field_variant_with_selector_field_integer_unsigned_borrow_selected_option_class_const()

const bt_field_class_variant_with_selector_field_integer_unsigned_option * bt_field_variant_with_selector_field_integer_unsigned_borrow_selected_option_class_const ( const bt_field * field )

extern

Borrows the class of the selected option of the variant field (with an unsigned integer selector field) field.

This function returns

bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(
    bt_field_variant_get_selected_option_index(field))

Parameters

[in]

field

Variant field of which to borrow the class of its selected option.

Returns

Class of the selected option of field.

Precondition

field is not NULL.

field is a variant field (instances with a linked unsigned integer selector field).

bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const()

const bt_field_class_variant_with_selector_field_integer_signed_option * bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const ( const bt_field * field )

extern

Borrows the class of the selected option of the variant field (with a signed integer selector field) field.

This function returns

bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(
    bt_field_variant_get_selected_option_index(field))

Parameters

[in]

field

Variant field of which to borrow the class of its selected option.

Returns

Class of the selected option of field.

Precondition

field is not NULL.

field is a variant field (instances with a linked signed integer selector field).