Babeltrace 2 C API  2.0.0
Open-source trace manipulation framework

Detailed Description

Trace (set of streams).

A trace is a set of streams with properties:

In the illustration above, notice that a trace is an instance of a trace class and that it contains streams.

Borrow the class of a trace with bt_trace_borrow_class() and bt_trace_borrow_class_const().

A trace is a trace IR data object.

A trace is a shared object: get a new reference with bt_trace_get_ref() and put an existing reference with bt_trace_put_ref().

Some library functions freeze traces on success. The documentation of those functions indicate this postcondition. With a frozen trace, you can still:

The type of a trace is bt_trace.

A trace contains streams. All the streams of a given trace have unique numeric IDs. Get the number of streams in a trace with bt_trace_get_stream_count(). Borrow a specific stream from a trace with bt_trace_borrow_stream_by_index(), bt_trace_borrow_stream_by_index_const(), bt_trace_borrow_stream_by_id(), or bt_trace_borrow_stream_by_id_const().

Create a default trace from a trace class with bt_trace_create().

Add to and remove a destruction listener from a trace with bt_trace_add_destruction_listener() and bt_trace_remove_destruction_listener().

Properties

A trace has the following properties:

Optional: Name

Name of the trace.

Use bt_trace_set_name() and bt_trace_get_name().

Optional: UUID

UUID of the trace.

The trace's UUID uniquely identifies the trace.

Use bt_trace_set_uuid() and bt_trace_get_uuid().

Optional: Environment

Generic key-value store which describes the environment of the trace (for example, the system's hostname, its network address, the tracer's name and version, and the rest).

Trace environment keys are strings while values are signed integers or strings.

Set a trace environment entry's value with bt_trace_set_environment_entry_integer() and bt_trace_set_environment_entry_string().

Get the number of environment entries in a trace with bt_trace_get_environment_entry_count().

Borrow an environment entry from a trace with bt_trace_borrow_environment_entry_value_by_name_const().

Optional: User attributes

User attributes of the trace.

User attributes are custom attributes attached to a trace.

Use bt_trace_set_user_attributes(), bt_trace_borrow_user_attributes(), and bt_trace_borrow_user_attributes_const().

Type

typedef struct bt_trace bt_trace
 Trace.
 

Creation

bt_tracebt_trace_create (bt_trace_class *trace_class)
 Creates a default trace from the trace class trace_class. More...
 

Class access

bt_trace_classbt_trace_borrow_class (bt_trace *trace)
 Borrows the class of the trace trace. More...
 
const bt_trace_classbt_trace_borrow_class_const (const bt_trace *trace)
 Borrows the class of the trace trace (const version). More...
 

Stream access

uint64_t bt_trace_get_stream_count (const bt_trace *trace)
 Returns the number of streams contained in the trace trace. More...
 
bt_streambt_trace_borrow_stream_by_index (bt_trace *trace, uint64_t index)
 Borrows the stream at index index from the trace trace. More...
 
const bt_streambt_trace_borrow_stream_by_index_const (const bt_trace *trace, uint64_t index)
 Borrows the stream at index index from the trace trace (const version). More...
 
bt_streambt_trace_borrow_stream_by_id (bt_trace *trace, uint64_t id)
 Borrows the stream having the numeric ID id from the trace trace. More...
 
const bt_streambt_trace_borrow_stream_by_id_const (const bt_trace *trace, uint64_t id)
 Borrows the stream having the numeric ID id from the trace trace (const version). More...
 

Properties

enum  bt_trace_set_name_status {
  BT_TRACE_SET_NAME_STATUS_OK,
  BT_TRACE_SET_NAME_STATUS_MEMORY_ERROR
}
 Status codes for bt_trace_set_name(). More...
 
enum  bt_trace_set_environment_entry_status {
  BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK,
  BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR
}
 Status codes for bt_trace_set_name(). More...
 
typedef enum bt_trace_set_name_status bt_trace_set_name_status
 Status codes for bt_trace_set_name().
 
typedef enum bt_trace_set_environment_entry_status bt_trace_set_environment_entry_status
 Status codes for bt_trace_set_name().
 
bt_trace_set_name_status bt_trace_set_name (bt_trace *trace, const char *name)
 Sets the name of the trace trace to a copy of name. More...
 
const char * bt_trace_get_name (const bt_trace *trace)
 Returns the name of the trace trace. More...
 
void bt_trace_set_uuid (bt_trace *trace, bt_uuid uuid)
 Sets the UUID of the trace trace to a copy of uuid. More...
 
bt_uuid bt_trace_get_uuid (const bt_trace *trace)
 Returns the UUID of the trace trace. More...
 
bt_trace_set_environment_entry_status bt_trace_set_environment_entry_integer (bt_trace *trace, const char *name, int64_t value)
 Sets the value of the environment entry of the trace trace named name to the signed integer value. More...
 
bt_trace_set_environment_entry_status bt_trace_set_environment_entry_string (bt_trace *trace, const char *name, const char *value)
 Sets the value of the environment entry of the trace trace named name to the string value. More...
 
uint64_t bt_trace_get_environment_entry_count (const bt_trace *trace)
 Returns the number of environment entries contained in the trace trace. More...
 
void bt_trace_borrow_environment_entry_by_index_const (const bt_trace *trace, uint64_t index, const char **name, const bt_value **value)
 Borrows the environment entry at index index from the trace trace, setting *name to its name and *value to its value. More...
 
const bt_valuebt_trace_borrow_environment_entry_value_by_name_const (const bt_trace *trace, const char *name)
 Borrows the value of the environment entry named name in the trace trace. More...
 
void bt_trace_set_user_attributes (bt_trace *trace, const bt_value *user_attributes)
 Sets the user attributes of the trace trace to user_attributes. More...
 
bt_valuebt_trace_borrow_user_attributes (bt_trace *trace)
 Borrows the user attributes of the trace trace. More...
 
const bt_valuebt_trace_borrow_user_attributes_const (const bt_trace *trace)
 Borrows the user attributes of the trace trace (const version). More...
 

Listeners

enum  bt_trace_add_listener_status {
  BT_TRACE_ADD_LISTENER_STATUS_OK,
  BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR
}
 Status codes for bt_trace_add_destruction_listener(). More...
 
enum  bt_trace_remove_listener_status {
  BT_TRACE_REMOVE_LISTENER_STATUS_OK,
  BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR
}
 Status codes for bt_trace_remove_destruction_listener(). More...
 
typedef void(* bt_trace_destruction_listener_func) (const bt_trace *trace, void *user_data)
 User function for bt_trace_add_destruction_listener(). More...
 
typedef enum bt_trace_add_listener_status bt_trace_add_listener_status
 Status codes for bt_trace_add_destruction_listener().
 
typedef enum bt_trace_remove_listener_status bt_trace_remove_listener_status
 Status codes for bt_trace_remove_destruction_listener().
 
bt_trace_add_listener_status bt_trace_add_destruction_listener (const bt_trace *trace, bt_trace_destruction_listener_func user_func, void *user_data, bt_listener_id *listener_id)
 Adds a destruction listener having the function user_func to the trace trace. More...
 
bt_trace_remove_listener_status bt_trace_remove_destruction_listener (const bt_trace *trace, bt_listener_id listener_id)
 Removes the destruction listener having the ID listener_id from the trace trace. More...
 

Reference count

void bt_trace_get_ref (const bt_trace *trace)
 Increments the reference count of the trace trace. More...
 
void bt_trace_put_ref (const bt_trace *trace)
 Decrements the reference count of the trace trace. More...
 
#define BT_TRACE_PUT_REF_AND_RESET(_trace)
 Decrements the reference count of the trace _trace, and then sets _trace to NULL. More...
 
#define BT_TRACE_MOVE_REF(_dst, _src)
 Decrements the reference count of the trace _dst, sets _dst to _src, and then sets _src to NULL. More...
 

Typedef Documentation

◆ bt_trace_destruction_listener_func

typedef void(* bt_trace_destruction_listener_func) (const bt_trace *trace, void *user_data)

User function for bt_trace_add_destruction_listener().

This is the user function type for a trace destruction listener.

Parameters
[in]traceTrace being destroyed (frozen).
[in]user_dataUser data, as passed as the user_data parameter of bt_trace_add_destruction_listener().
Precondition
trace is not NULL.
Postcondition
The reference count of trace is not changed.
The current thread has no error.
See also
bt_trace_add_destruction_listener() — Adds a destruction listener to a trace.

Enumeration Type Documentation

◆ bt_trace_set_name_status

Status codes for bt_trace_set_name().

Enumerator
BT_TRACE_SET_NAME_STATUS_OK 

Success.

BT_TRACE_SET_NAME_STATUS_MEMORY_ERROR 

Out of memory.

◆ bt_trace_set_environment_entry_status

Status codes for bt_trace_set_name().

Enumerator
BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK 

Success.

BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR 

Out of memory.

◆ bt_trace_add_listener_status

Status codes for bt_trace_add_destruction_listener().

Enumerator
BT_TRACE_ADD_LISTENER_STATUS_OK 

Success.

BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR 

Out of memory.

◆ bt_trace_remove_listener_status

Status codes for bt_trace_remove_destruction_listener().

Enumerator
BT_TRACE_REMOVE_LISTENER_STATUS_OK 

Success.

BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR 

Out of memory.

Macro Definition Documentation

◆ BT_TRACE_PUT_REF_AND_RESET

#define BT_TRACE_PUT_REF_AND_RESET (   _trace)

Decrements the reference count of the trace _trace, and then sets _trace to NULL.

Parameters
_trace

Trace of which to decrement the reference count.

Can contain NULL.

Precondition
_trace is an assignable expression.

◆ BT_TRACE_MOVE_REF

#define BT_TRACE_MOVE_REF (   _dst,
  _src 
)

Decrements the reference count of the trace _dst, sets _dst to _src, and then sets _src to NULL.

This macro effectively moves a trace reference from the expression _src to the expression _dst, putting the existing _dst reference.

Parameters
_dst

Destination expression.

Can contain NULL.

_src

Source expression.

Can contain NULL.

Precondition
_dst is an assignable expression.
_src is an assignable expression.

Function Documentation

◆ bt_trace_create()

bt_trace* bt_trace_create ( bt_trace_class trace_class)

Creates a default trace from the trace class trace_class.

This function instantiates trace_class.

On success, the returned trace has the following property values:

Property Value
Name None
UUID None
Environment Empty
User attributes Empty map value
Parameters
[in]trace_classTrace class from which to create the default trace.
Returns
New trace reference, or NULL on memory error.

◆ bt_trace_borrow_class()

bt_trace_class* bt_trace_borrow_class ( bt_trace trace)

Borrows the class of the trace trace.

Parameters
[in]traceTrace of which to borrow the class.
Returns
Borrowed reference of the class of trace.
Precondition
trace is not NULL.
See also
bt_trace_borrow_class_const()const version of this function.

◆ bt_trace_borrow_class_const()

const bt_trace_class* bt_trace_borrow_class_const ( const bt_trace trace)

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

See bt_trace_borrow_class().

◆ bt_trace_get_stream_count()

uint64_t bt_trace_get_stream_count ( const bt_trace trace)

Returns the number of streams contained in the trace trace.

Parameters
[in]traceTrace of which to get the number of contained streams.
Returns
Number of contained streams in trace.
Precondition
trace is not NULL.

◆ bt_trace_borrow_stream_by_index()

bt_stream* bt_trace_borrow_stream_by_index ( bt_trace trace,
uint64_t  index 
)

Borrows the stream at index index from the trace trace.

Parameters
[in]traceTrace from which to borrow the stream at index index.
[in]indexIndex of the stream to borrow from trace.
Returns

Borrowed reference of the stream of trace at index index.

The returned pointer remains valid as long as trace exists.

Precondition
trace is not NULL.
index is less than the number of streams in trace (as returned by bt_trace_get_stream_count()).
See also
bt_trace_get_stream_count() — Returns the number of streams contained in a trace.
bt_trace_borrow_stream_by_index_const()const version of this function.

◆ bt_trace_borrow_stream_by_index_const()

const bt_stream* bt_trace_borrow_stream_by_index_const ( const bt_trace trace,
uint64_t  index 
)

Borrows the stream at index index from the trace trace (const version).

See bt_trace_borrow_stream_by_index().

◆ bt_trace_borrow_stream_by_id()

bt_stream* bt_trace_borrow_stream_by_id ( bt_trace trace,
uint64_t  id 
)

Borrows the stream having the numeric ID id from the trace trace.

If there's no stream having the numeric ID id in trace, this function returns NULL.

Parameters
[in]traceTrace from which to borrow the stream having the numeric ID id.
[in]idID of the stream to borrow from trace.
Returns

Borrowed reference of the stream of trace having the numeric ID id, or NULL if none.

The returned pointer remains valid as long as trace exists.

Precondition
trace is not NULL.
See also
bt_trace_borrow_stream_by_id_const()const version of this function.

◆ bt_trace_borrow_stream_by_id_const()

const bt_stream* bt_trace_borrow_stream_by_id_const ( const bt_trace trace,
uint64_t  id 
)

Borrows the stream having the numeric ID id from the trace trace (const version).

See bt_trace_borrow_stream_by_id().

◆ bt_trace_set_name()

bt_trace_set_name_status bt_trace_set_name ( bt_trace trace,
const char *  name 
)

Sets the name of the trace trace to a copy of name.

See the name property.

Parameters
[in]traceTrace of which to set the name to name.
[in]nameNew name of trace (copied).
Return values
BT_TRACE_SET_NAME_STATUS_OKSuccess.
BT_TRACE_SET_NAME_STATUS_MEMORY_ERROROut of memory.
Precondition
trace is not NULL.
trace is not frozen.
name is not NULL.
See also
bt_trace_get_name() — Returns the name of a trace.

◆ bt_trace_get_name()

const char* bt_trace_get_name ( const bt_trace trace)

Returns the name of the trace trace.

See the name property.

If trace has no name, this function returns NULL.

Parameters
[in]traceTrace of which to get the name.
Returns

Name of trace, or NULL if none.

The returned pointer remains valid as long as trace is not modified.

Precondition
trace is not NULL.
See also
bt_trace_set_name() — Sets the name of a trace.

◆ bt_trace_set_uuid()

void bt_trace_set_uuid ( bt_trace trace,
bt_uuid  uuid 
)

Sets the UUID of the trace trace to a copy of uuid.

See the UUID property.

Parameters
[in]traceTrace of which to set the UUID to uuid.
[in]uuidNew UUID of trace (copied).
Precondition
trace is not NULL.
trace is not frozen.
uuid is not NULL.
See also
bt_trace_get_uuid() — Returns the UUID of a trace.

◆ bt_trace_get_uuid()

bt_uuid bt_trace_get_uuid ( const bt_trace trace)

Returns the UUID of the trace trace.

See the UUID property.

If trace has no UUID, this function returns NULL.

Parameters
[in]traceTrace of which to get the UUID.
Returns

UUID of trace, or NULL if none.

The returned pointer remains valid as long as trace is not modified.

Precondition
trace is not NULL.
See also
bt_trace_set_uuid() — Sets the UUID of a trace.

◆ bt_trace_set_environment_entry_integer()

bt_trace_set_environment_entry_status bt_trace_set_environment_entry_integer ( bt_trace trace,
const char *  name,
int64_t  value 
)

Sets the value of the environment entry of the trace trace named name to the signed integer value.

See the environment property.

On success, if trace already contains an environment entry named name, this function replaces the existing entry's value with value.

Parameters
[in]traceTrace in which to insert or replace an environment entry named name with the value value.
[in]nameName of the entry to insert or replace in trace (copied).
[in]valueValue of the environment entry to insert or replace in trace.
Return values
BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OKSuccess.
BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROROut of memory.
Precondition
trace is not NULL.
trace is not frozen.
name is not NULL.
See also
bt_trace_set_environment_entry_string() — Sets a trace environment entry's value to a string.

◆ bt_trace_set_environment_entry_string()

bt_trace_set_environment_entry_status bt_trace_set_environment_entry_string ( bt_trace trace,
const char *  name,
const char *  value 
)

Sets the value of the environment entry of the trace trace named name to the string value.

See the environment property.

On success, if trace already contains an environment entry named name, this function replaces the existing entry's value with value.

Parameters
[in]traceTrace in which to insert or replace an environment entry named name with the value value.
[in]nameName of the entry to insert or replace in trace (copied).
[in]valueValue of the environment entry to insert or replace in trace.
Return values
BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OKSuccess.
BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROROut of memory.
Precondition
trace is not NULL.
trace is not frozen.
name is not NULL.
value is not NULL.
See also
bt_trace_set_environment_entry_integer() — Sets a trace environment entry's value to a signed integer.

◆ bt_trace_get_environment_entry_count()

uint64_t bt_trace_get_environment_entry_count ( const bt_trace trace)

Returns the number of environment entries contained in the trace trace.

See the environment property.

Parameters
[in]traceTrace of which to get the number of environment entries.
Returns
Number of environment entries in trace.
Precondition
trace is not NULL.

◆ bt_trace_borrow_environment_entry_by_index_const()

void bt_trace_borrow_environment_entry_by_index_const ( const bt_trace trace,
uint64_t  index,
const char **  name,
const bt_value **  value 
)

Borrows the environment entry at index index from the trace trace, setting *name to its name and *value to its value.

See the environment property.

Parameters
[in]traceTrace from which to borrow the environment entry at index index.
[in]indexIndex of the environment entry to borrow from trace.
[in]name

On success, *name is the name of the environment entry at index index in trace.

The returned pointer remains valid as long as trace is not modified.

[in]value

On success, *value is a borrowed reference of the environment entry at index index in trace.

*value is either a signed integer value (BT_VALUE_TYPE_SIGNED_INTEGER) or a string value (BT_VALUE_TYPE_STRING).

The returned pointer remains valid as long as trace is not modified.

Precondition
trace is not NULL.
index is less than the number of environment entries in trace (as returned by bt_trace_get_environment_entry_count()).
name is not NULL.
value is not NULL.
See also
bt_trace_get_environment_entry_count() — Returns the number of environment entries contained in a trace.

◆ bt_trace_borrow_environment_entry_value_by_name_const()

const bt_value* bt_trace_borrow_environment_entry_value_by_name_const ( const bt_trace trace,
const char *  name 
)

Borrows the value of the environment entry named name in the trace trace.

See the environment property.

If there's no environment entry named name in trace, this function returns NULL.

Parameters
[in]traceTrace from which to borrow the value of the environment entry named name.
[in]nameName of the environment entry to borrow from trace.
Returns

Borrowed reference of the value of the environment entry named name in trace.

The returned value is either a signed integer value (BT_VALUE_TYPE_SIGNED_INTEGER) or a string value (BT_VALUE_TYPE_STRING).

The returned pointer remains valid as long as trace is not modified.

Precondition
trace is not NULL.
name is not NULL.

◆ bt_trace_set_user_attributes()

void bt_trace_set_user_attributes ( bt_trace trace,
const bt_value user_attributes 
)

Sets the user attributes of the trace trace to user_attributes.

See the user attributes property.

Note
When you create a default trace with bt_trace_create(), the trace's initial user attributes is an empty map value. Therefore you can borrow it with bt_trace_borrow_user_attributes() and fill it directly instead of setting a new one with this function.
Parameters
[in]traceTrace of which to set the user attributes to user_attributes.
[in]user_attributesNew user attributes of trace.
Precondition
trace is not NULL.
trace is not frozen.
user_attributes is not NULL.
user_attributes is a map value (bt_value_is_map() returns BT_TRUE).
See also
bt_trace_borrow_user_attributes() — Borrows the user attributes of a trace.

◆ bt_trace_borrow_user_attributes()

bt_value* bt_trace_borrow_user_attributes ( bt_trace trace)

Borrows the user attributes of the trace trace.

See the user attributes property.

Note
When you create a default trace with bt_trace_create(), the trace's initial user attributes is an empty map value.
Parameters
[in]traceTrace from which to borrow the user attributes.
Returns
User attributes of trace (a map value).
Precondition
trace is not NULL.
See also
bt_trace_set_user_attributes() — Sets the user attributes of a trace.
bt_trace_borrow_user_attributes_const()const version of this function.

◆ bt_trace_borrow_user_attributes_const()

const bt_value* bt_trace_borrow_user_attributes_const ( const bt_trace trace)

Borrows the user attributes of the trace trace (const version).

See bt_trace_borrow_user_attributes().

◆ bt_trace_add_destruction_listener()

bt_trace_add_listener_status bt_trace_add_destruction_listener ( const bt_trace trace,
bt_trace_destruction_listener_func  user_func,
void *  user_data,
bt_listener_id listener_id 
)

Adds a destruction listener having the function user_func to the trace trace.

All the destruction listener user functions of a trace are called when it's being destroyed.

If listener_id is not NULL, then this function, on success, sets *listener_id to the ID of the added destruction listener within trace. You can then use this ID to remove the added destruction listener with bt_trace_remove_destruction_listener().

Parameters
[in]traceTrace to add the destruction listener to.
[in]user_funcUser function of the destruction listener to add to trace.
[in]user_dataUser data to pass as the user_data parameter of user_func.
[out]listener_idOn success and if not NULL, *listener_id is the ID of the added destruction listener within trace.
Return values
BT_TRACE_ADD_LISTENER_STATUS_OKSuccess.
BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROROut of memory.
Precondition
trace is not NULL.
user_func is not NULL.
See also
bt_trace_remove_destruction_listener() — Removes a destruction listener from a trace.

◆ bt_trace_remove_destruction_listener()

bt_trace_remove_listener_status bt_trace_remove_destruction_listener ( const bt_trace trace,
bt_listener_id  listener_id 
)

Removes the destruction listener having the ID listener_id from the trace trace.

The destruction listener to remove from trace was previously added with bt_trace_add_destruction_listener().

You can call this function when trace is frozen.

Parameters
[in]traceTrace from which to remove the destruction listener having the ID listener_id.
[in]listener_idID of the destruction listener to remove from trace­.
Return values
BT_TRACE_REMOVE_LISTENER_STATUS_OKSuccess.
BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROROut of memory.
Precondition
trace is not NULL.
listener_id is the ID of an existing destruction listener in trace.
See also
bt_trace_add_destruction_listener() — Adds a destruction listener to a trace.

◆ bt_trace_get_ref()

void bt_trace_get_ref ( const bt_trace trace)

Increments the reference count of the trace trace.

Parameters
[in]trace

Trace of which to increment the reference count.

Can be NULL.

See also
bt_trace_put_ref() — Decrements the reference count of a trace.

◆ bt_trace_put_ref()

void bt_trace_put_ref ( const bt_trace trace)

Decrements the reference count of the trace trace.

Parameters
[in]trace

Trace of which to decrement the reference count.

Can be NULL.

See also
bt_trace_get_ref() — Increments the reference count of a trace.