Fields

Detailed Description

Containers of trace data.

Fields are containers of trace data: they are 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

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 event's existing payload structure field 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 a field's class 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 least significant bit's index 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) << UINT64_C(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().

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 a string field's current value with bt_field_string_append() and bt_field_string_append_with_length().

Clear a string field with bt_field_string_clear().

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 class

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 a dynamic array field's length with bt_field_array_dynamic_set_length() before you borrow any of its fields.

Get an array field's length 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 a member's field 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 a member's field 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 a variant field's selected option's index with bt_field_variant_get_selected_option_index().

Borrow a variant field's selected option's field with bt_field_variant_borrow_selected_option_field() and bt_field_variant_borrow_selected_option_field_const().

Borrow the class of a variant field's selected option 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().

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. More...

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

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

Bit array field
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. More...
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. More...

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. More...
uint64_t	bt_field_integer_unsigned_get_value (const bt_field *field)
	Returns the value of the unsigned integer field field. More...
void	bt_field_integer_signed_set_value (bt_field *field, int64_t value)
	Sets the value of the signed integer field field to value. More...
int64_t	bt_field_integer_signed_get_value (const bt_field *field)
	Returns the value of the signed integer field field. More...

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. More...
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. More...

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. More...
float	bt_field_real_single_precision_get_value (const bt_field *field)
	Returns the value of the single-precision real field field. More...
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. More...
double	bt_field_real_double_precision_get_value (const bt_field *field)
	Returns the value of the double-precision real field field. More...

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. More...
uint64_t	bt_field_string_get_length (const bt_field *field)
	Returns the length of the string field field. More...
const char *	bt_field_string_get_value (const bt_field *field)
	Returns the value of the string field field. More...
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. More...
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. More...
void	bt_field_string_clear (bt_field *field)
	Clears the string field field, making its value an empty string. More...

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. More...
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. More...
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). More...
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. More...

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. More...
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). More...
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. More...
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). More...

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. More...
bt_field *	bt_field_option_borrow_field (bt_field *field)
	Borrows the field of the option field field. More...
const bt_field *	bt_field_option_borrow_field_const (const bt_field *field)
	Borrows the field of the option field field (const version). More...

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. More...
bt_field *	bt_field_variant_borrow_selected_option_field (bt_field *field)
	Borrows the field of the selected option of the variant field field. More...
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). More...
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. More...
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. More...
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. More...
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. More...

Enumeration Type Documentation

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_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

)

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 class's type enumerator

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

)

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

)

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
	)

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

)

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
	)

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

The least significant bit's index 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

)

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

The least significant bit's index 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_integer_unsigned_set_value()

void bt_field_integer_unsigned_set_value	(	bt_field *	field,
		uint64_t	value
	)

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

)

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
	)

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

)

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
	)

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
	)

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
	)

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

)

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
	)

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

)

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
	)

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

)

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

)

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
	)

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, 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
	)

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, 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

)

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_array_get_length()

uint64_t bt_field_array_get_length

(

const bt_field *

field

)

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
	)

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

Attention

If field is a dynamic array field, 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
	)

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
	)

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
	)

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
	)

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
	)

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, 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
	)

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
	)

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

)

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, 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

)

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
	)

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

)

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 selected option's field.

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 a variant field's selected option.

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

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

)

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

)

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 a variant field's selected option.

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

)

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 get the selected option's class.

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

)

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 get the selected option's class.

Returns

Class of the selected option of field.

Precondition

field is not NULL.

field is a variant field (with an 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

)

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 get the selected option's class.

Returns

Class of the selected option of field.

Precondition

field is not NULL.

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