callsites: fix memory leak

[babeltrace.git] / doc / API.txt

Babeltrace API documentation

Babeltrace provides trace read and write libraries, as well as a trace
converter. A plugin can be created for any trace format to allow its
conversion to/from another trace format.

The main format expected to be converted to/from is the Common Trace
Format (CTF). The latest version of the CTF specification can be found at:
	git tree:   git://git.efficios.com/ctf.git
	gitweb:     http://git.efficios.com/?p=ctf.git

This document describes the main concepts to use the libbabeltrace,
which exposes the Babeltrace trace reading capability.


TERMINOLOGY
¯¯¯¯¯¯¯¯¯¯¯

* A "callback" is a reference to a piece of executable code (such as a
  function) that is passed as an argument to another piece of code
  (like another function).

* A "context" is a structure that represents an object in which a trace
  collection is opened.

* An "iterator" is a structure that enables the user to traverse a trace.

* A "trace handle" is a unique identifier representing a trace file.
  It allows the user to manipulate a trace directly.

* The "declaration" of a field or an event, is the structure which contains
  the representaion of an object as declared in the metadata. All the
  declarations of all events and fields can be accessed as soon as the trace is
  open, but of course they contain no trace data, just the layout.

* The "definition" of a field or an event is the structure in which the actual
  trace data is contained. When we read an event in the trace, we access its
  definition and we can access all the field definitions contained in all the
  scopes of this event to the get the actual data.

* "Scopes" allow specifying the level at which the information about the
  current event must be fetched: event header, event payload, event context,
  stream context. Compound-type (arrays, structures, sequences and variants)
  fields are relative scopes which contain fields.


USAGE
¯¯¯¯¯¯

Context:

In order to use libbabeltrace to read a trace, the first step is to create a
context structure and to add a trace to it. This is done using the
bt_context_create() and bt_context_add_trace() functions. As long as this
context structure is allocated and the trace is valid, the trace can be
manipulated by the library.

The context can be destroyed by calling one more bt_context_put() than
bt_context_get(), functions which respectively decrement and increment the
refcount of the context. These functions ensures that the context won't be
destroyed when it is in use.

Once a trace is added to the context, it can be read and seeked using iterators
and callbacks.


Iterator:

An iterator can be created using the bt_iter_create() function. As of now, only
ctf iterator are supported. These are used to traverse a ctf-formatted trace.
Such iterators can be created with bt_ctf_iter_create().

While creating an iterator, a begin and an end position may be specified. To do
so, one or two struct bt_iter_pos must be passed. Such struct have two
attributes: type and u. "type" is the seek type, can be either:
	BT_SEEK_TIME
	BT_SEEK_RESTORE
	BT_SEEK_CUR
	BT_SEEK_BEGIN
	BT_SEEK_END
and "u" is a union of the seek time (if using BT_SEEK_TIME) and the restore
position (if using BT_SEEK_RESTORE).

Once the iterator is created, various functions become available. We have
bt_ctf_iter_read_event() which returns the ctf event of the trace where the
iterator is set. There is also bt_ctf_iter_destroy() which frees the iterator.
Note that only one iterator can be created in a context at the same time. If
more than one iterator is being created for the same context, the second
creation will return NULL. The previous iterator must be destroyed before
creation of the new iterator. In the future, creation of multiples iterators
will be allowed.

The bt_ctf_iter_read_event_flags() function has the same behaviour as
bt_ctf_iter_read_event() but takes an additionnal flag pointer. This flag is
used to inform the user if a special condition occured while reading the event.
As of now, only the BT_ITER_LOST_EVENTS is handled, it informs the user that
some events were discarded by the tracer. To get the number of events lost
immediately prior to the last event read, the user can call the
bt_ctf_get_lost_events_count() function.

Finally, we have the bt_ctf_get_iter() function which returns a struct bt_iter
with which the iterator can be moved using one of these functions:
	bt_iter_next(),		moves the iterator to the next event
	bt_iter_set_pos(),	moves the iterator to the specified position

To get the current position (struct bt_iter_pos) of the iterator, the function
bt_iter_get_pos() must be used. To create an arbitrary position based on a
specific time, bt_iter_create_time_pos() is the function to use. The
bt_iter_pos structure returned by these two functions must be freed with
bt_iter_free_pos() after use.


CTF Event:

A CTF event is obtained from an iterator via the bt_ctf_iter_read_event()
function or via the call_data parameter of a callback. To read the data of a
CTF event :
	* bt_ctf_event_name() 		returns the name of the event;
	* bt_ctf_get_timestamp() 	returns the timestamp of the event
					offsetted with the system clock
					source (in ns);
	* bt_ctf_get_cycles() 		returns the timestamp of the event as
					written in the packet (in cycles).

The payload of an event is divided in various scopes depending on the type of
information. There are six top-level scopes (defined in the bt_ctf_scope enum)
which can be accessed by the bt_ctf_get_top_level_scope() function :
	BT_TRACE_PACKET_HEADER		= 0,
	BT_STREAM_PACKET_CONTEXT        = 1,
	BT_STREAM_EVENT_HEADER          = 2,
	BT_STREAM_EVENT_CONTEXT         = 3,
	BT_EVENT_CONTEXT                = 4,
	BT_EVENT_FIELDS                 = 5.

In order to access a field or a field list, the user needs to pass a scope as
argument, this scope can be a top-level scope or a scope relative to an
arbitrary field in the case of compound types (array, sequence, structure or
variant)

For more information on each scope, see the CTF specifications.

The bt_ctf_get_field_list() function gives access to the list of fields in the
current event. The bt_ctf_get_field() function gives acces to of a specific
field of an event.

The bt_ctf_get_event_decl_list() and bt_ctf_get_decl_fields() functions give
respectively access to the list of the events declared in a trace and the list
of the fields declared in an event.

Once the field is obtained, we can obtain its name and type using the
bt_ctf_field_name() and bt_ctf_field_type() functions respectively. The
possible types are defined in the ctf_type_id enum:
	CTF_TYPE_UNKNOWN = 0,
	CTF_TYPE_INTEGER,
	CTF_TYPE_FLOAT,
	CTF_TYPE_ENUM,
	CTF_TYPE_STRING,
	CTF_TYPE_STRUCT,
	CTF_TYPE_UNTAGGED_VARIANT,
	CTF_TYPE_VARIANT,
	CTF_TYPE_ARRAY,
	CTF_TYPE_SEQUENCE,
	NR_CTF_TYPES.

Depending on the field type, we can get informations about the field with the
following functions:
	* bt_ctf_get_index()		return the element at the index
					position of an array of a sequence;

	* bt_ctf_get_array_len()	return the length of an array;

	* bt_ctf_get_int_signedness() 	return the signedness of an integer;

	* bt_ctf_get_int_base()		return the base of an integer;

	* bt_ctf_get_int_byte_order() 	return the byte order of an integer;

	* bt_ctf_get_int_len()		return the size in bits of an integer;

	* bt_ctf_get_encoding()		return the encoding of an int or a
					string defined in the
					ctf_string_encoding enum:
						CTF_STRING_NONE = 0,
						CTF_STRING_UTF8,
						CTF_STRING_ASCII,
						CTF_STRING_UNKNOWN.

All of these functions require a field declaration as parameter, depending on
the source type of data (struct definition* or struct bt_ctf_field_decl*), the
user might have to call bt_ctf_get_decl_from_def() or
bt_ctf_get_decl_from_field_decl().

The following functions give access to the value associated with a field
defintion:
	* bt_ctf_get_uint64();
	* bt_ctf_get_int64();
	* bt_ctf_get_char_array();
	* bt_ctf_get_string();
	* bt_ctf_get_enum_int();
	* bt_ctf_get_enum_str().

If the field does not exist or is not of the type requested, the value returned
with these four functions is undefined. To check if an error occured, use the
bt_ctf_field_get_error() function after accessing a field. If no error
occured, the function will return 0.

It is also possible to access the declaration fields, the same way as the
definition ones. bt_ctf_get_event_decl_list() sets a list to an array of
bt_ctf_event_decl pointers and bt_ctf_get_event_decl_fields() sets a list to an
array of bt_ctf_field_decl pointers.  From the first type, the name of the
event can be obtained with bt_ctf_get_decl_event_name().  For the second type,
the field decl name is obtained with bt_ctf_get_decl_field_name().

The declaration functions allow the user to list the events, fields and
contexts fields enabled in the trace once it is opened, whereas the definition
functions apply on the current event being read.


Callback:

The iterator allow the user to read the trace, in order to access the events
and fields, the user can either call the functions listed previously on each
event, or register callbacks functions that are called when specific (or all)
events are read.

This is done with the bt_ctf_iter_add_callback() function. It requires a valid
ctf iterator as the first argument. Here are all arguments:
	iter: trace collection iterator (input)
	event: event to target. 0 for all events.
	private_data: private data pointer to pass to the callback
	flags: specific flags controlling the behavior of this callback
		(or'd).
	callback: function pointer to call
	depends: struct bt_dependency detailing the required computation
		results.  Ends with 0.
	weak_depends: struct bt_dependency detailing the optional computation
		results that can be optionally consumed by this
		callback.
	provides: struct bt_dependency detailing the computation results
		provided by this callback.
		Ends with 0.

"depends", "weak_depends" and "provides" memory is handled by the babeltrace
library after this call succeeds or fails. These objects can still be used by
the caller until the babeltrace iterator is destroyed, but they belong to the
babeltrace library.

As of now the flags and dependencies are not used, the callbacks are
processed in FIFO order.

Note: once implemented, the dependency graph will be calculated when
bt_ctf_iter_read_event() is executed after a bt_ctf_iter_add_callback(). It is
valid to create/add callbacks/read/add more callbacks/read some more.

The callback function passed to bt_ctf_iter_add_callback() must return a
bt_cb_ret value:
	BT_CB_OK		= 0,
	BT_CB_OK_STOP		= 1,
	BT_CB_ERROR_STOP	= 2,
	BT_CB_ERROR_CONTINUE	= 3.


Trace handle:

When a trace is added to a context, bt_context_add_trace() returns a trace
handle id.  This id is associated with its corresponding trace handle.  With
that id, it is possible to manipulate directly the trace.

	* bt_trace_handle_get_path()
		-> returns the path of the trace handle	(path to the trace).

	* bt_trace_handle_get_timestamp_begin()
	* bt_trace_handle_get_timestamp_end()
		-> return the creation/destruction timestamps (in ns or cycles
			depending on the type specified) of the buffers of a
			trace.

	* bt_ctf_event_get_handle_id()
		-> returns the handle id associated with an event.


For more information on CTF, see the CTF documentation.