Fix: Use list rather than ptr array for trace streams
[babeltrace.git] / doc / API.txt
CommitLineData
827b30c1
DS
1Babeltrace API documentation
2
3Babeltrace provides trace read and write libraries, as well as a trace
4converter. A plugin can be created for any trace format to allow its
5conversion to/from another trace format.
6
7The main format expected to be converted to/from is the Common Trace
8Format (CTF). The latest version of the CTF specification can be found at:
9 git tree: git://git.efficios.com/ctf.git
10 gitweb: http://git.efficios.com/?p=ctf.git
11
12This document describes the main concepts to use the libbabeltrace,
13which exposes the Babeltrace trace reading capability.
14
15
16TERMINOLOGY
17¯¯¯¯¯¯¯¯¯¯¯
18
19* A "callback" is a reference to a piece of executable code (such as a
20 function) that is passed as an argument to another piece of code
21 (like another function).
22
23* A "context" is a structure that represents an object in which a trace
24 collection is opened.
25
26* An "iterator" is a structure that enables the user to traverse a trace.
27
28* A "trace handle" is a unique identifier representing a trace file.
29 It allows the user to manipulate a trace directly.
30
f5464725
JD
31* The "declaration" of a field or an event, is the structure which contains
32 the representaion of an object as declared in the metadata. All the
33 declarations of all events and fields can be accessed as soon as the trace is
34 open, but of course they contain no trace data, just the layout.
35
36* The "definition" of a field or an event is the structure in which the actual
37 trace data is contained. When we read an event in the trace, we access its
38 definition and we can access all the field definitions contained in all the
39 scopes of this event to the get the actual data.
40
41* "Scopes" allow specifying the level at which the information about the
42 current event must be fetched: event header, event payload, event context,
43 stream context. Compound-type (arrays, structures, sequences and variants)
44 fields are relative scopes which contain fields.
827b30c1
DS
45
46
47USAGE
48¯¯¯¯¯¯
49
50Context:
51
52In order to use libbabeltrace to read a trace, the first step is to create a
53context structure and to add a trace to it. This is done using the
54bt_context_create() and bt_context_add_trace() functions. As long as this
55context structure is allocated and the trace is valid, the trace can be
56manipulated by the library.
57
58The context can be destroyed by calling one more bt_context_put() than
59bt_context_get(), functions which respectively decrement and increment the
60refcount of the context. These functions ensures that the context won't be
61destroyed when it is in use.
62
63Once a trace is added to the context, it can be read and seeked using iterators
64and callbacks.
65
66
67Iterator:
68
69An iterator can be created using the bt_iter_create() function. As of now, only
70ctf iterator are supported. These are used to traverse a ctf-formatted trace.
71Such iterators can be created with bt_ctf_iter_create().
72
73While creating an iterator, a begin and an end position may be specified. To do
74so, one or two struct bt_iter_pos must be passed. Such struct have two
75attributes: type and u. "type" is the seek type, can be either:
76 BT_SEEK_TIME
77 BT_SEEK_RESTORE
78 BT_SEEK_CUR
79 BT_SEEK_BEGIN
80 BT_SEEK_END
81and "u" is a union of the seek time (if using BT_SEEK_TIME) and the restore
82position (if using BT_SEEK_RESTORE).
83
84Once the iterator is created, various functions become available. We have
85bt_ctf_iter_read_event() which returns the ctf event of the trace where the
86iterator is set. There is also bt_ctf_iter_destroy() which frees the iterator.
87Note that only one iterator can be created in a context at the same time. If
88more than one iterator is being created for the same context, the second
89creation will return NULL. The previous iterator must be destroyed before
90creation of the new iterator. In the future, creation of multiples iterators
91will be allowed.
92
f60efc0e
JD
93The bt_ctf_iter_read_event_flags() function has the same behaviour as
94bt_ctf_iter_read_event() but takes an additionnal flag pointer. This flag is
95used to inform the user if a special condition occured while reading the event.
96As of now, only the BT_ITER_LOST_EVENTS is handled, it informs the user that
97some events were discarded by the tracer. To get the number of events lost
98immediately prior to the last event read, the user can call the
99bt_ctf_get_lost_events_count() function.
100
827b30c1
DS
101Finally, we have the bt_ctf_get_iter() function which returns a struct bt_iter
102with which the iterator can be moved using one of these functions:
103 bt_iter_next(), moves the iterator to the next event
104 bt_iter_set_pos(), moves the iterator to the specified position
105
106To get the current position (struct bt_iter_pos) of the iterator, the function
107bt_iter_get_pos() must be used. To create an arbitrary position based on a
108specific time, bt_iter_create_time_pos() is the function to use. The
109bt_iter_pos structure returned by these two functions must be freed with
110bt_iter_free_pos() after use.
111
112
113CTF Event:
114
115A CTF event is obtained from an iterator via the bt_ctf_iter_read_event()
116function or via the call_data parameter of a callback. To read the data of a
117CTF event :
118 * bt_ctf_event_name() returns the name of the event;
119 * bt_ctf_get_timestamp() returns the timestamp of the event
120 offsetted with the system clock
121 source (in ns);
122 * bt_ctf_get_cycles() returns the timestamp of the event as
123 written in the packet (in cycles).
124
125The payload of an event is divided in various scopes depending on the type of
126information. There are six top-level scopes (defined in the bt_ctf_scope enum)
127which can be accessed by the bt_ctf_get_top_level_scope() function :
128 BT_TRACE_PACKET_HEADER = 0,
129 BT_STREAM_PACKET_CONTEXT = 1,
130 BT_STREAM_EVENT_HEADER = 2,
131 BT_STREAM_EVENT_CONTEXT = 3,
132 BT_EVENT_CONTEXT = 4,
133 BT_EVENT_FIELDS = 5.
134
135In order to access a field or a field list, the user needs to pass a scope as
136argument, this scope can be a top-level scope or a scope relative to an
137arbitrary field in the case of compound types (array, sequence, structure or
138variant)
139
140For more information on each scope, see the CTF specifications.
141
f5464725
JD
142The bt_ctf_get_field_list() function gives access to the list of fields in the
143current event. The bt_ctf_get_field() function gives acces to of a specific
144field of an event.
145
146The bt_ctf_get_event_decl_list() and bt_ctf_get_decl_fields() functions give
147respectively access to the list of the events declared in a trace and the list
148of the fields declared in an event.
827b30c1
DS
149
150Once the field is obtained, we can obtain its name and type using the
151bt_ctf_field_name() and bt_ctf_field_type() functions respectively. The
152possible types are defined in the ctf_type_id enum:
153 CTF_TYPE_UNKNOWN = 0,
154 CTF_TYPE_INTEGER,
155 CTF_TYPE_FLOAT,
156 CTF_TYPE_ENUM,
157 CTF_TYPE_STRING,
158 CTF_TYPE_STRUCT,
159 CTF_TYPE_UNTAGGED_VARIANT,
160 CTF_TYPE_VARIANT,
161 CTF_TYPE_ARRAY,
162 CTF_TYPE_SEQUENCE,
163 NR_CTF_TYPES.
164
f5464725
JD
165Depending on the field type, we can get informations about the field with the
166following functions:
827b30c1
DS
167 * bt_ctf_get_index() return the element at the index
168 position of an array of a sequence;
169
170 * bt_ctf_get_array_len() return the length of an array;
171
172 * bt_ctf_get_int_signedness() return the signedness of an integer;
173
174 * bt_ctf_get_int_base() return the base of an integer;
175
176 * bt_ctf_get_int_byte_order() return the byte order of an integer;
177
178 * bt_ctf_get_int_len() return the size in bits of an integer;
179
180 * bt_ctf_get_encoding() return the encoding of an int or a
181 string defined in the
182 ctf_string_encoding enum:
183 CTF_STRING_NONE = 0,
184 CTF_STRING_UTF8,
185 CTF_STRING_ASCII,
186 CTF_STRING_UNKNOWN.
187
f5464725
JD
188All of these functions require a field declaration as parameter, depending on
189the source type of data (struct definition* or struct bt_ctf_field_decl*), the
190user might have to call bt_ctf_get_decl_from_def() or
191bt_ctf_get_decl_from_field_decl().
192
193The following functions give access to the value associated with a field
194defintion:
827b30c1
DS
195 * bt_ctf_get_uint64();
196 * bt_ctf_get_int64();
197 * bt_ctf_get_char_array();
6ab22097
JD
198 * bt_ctf_get_string();
199 * bt_ctf_get_enum_int();
200 * bt_ctf_get_enum_str().
827b30c1
DS
201
202If the field does not exist or is not of the type requested, the value returned
203with these four functions is undefined. To check if an error occured, use the
204bt_ctf_field_get_error() function after accessing a field. If no error
205occured, the function will return 0.
206
207It is also possible to access the declaration fields, the same way as the
208definition ones. bt_ctf_get_event_decl_list() sets a list to an array of
209bt_ctf_event_decl pointers and bt_ctf_get_event_decl_fields() sets a list to an
210array of bt_ctf_field_decl pointers. From the first type, the name of the
211event can be obtained with bt_ctf_get_decl_event_name(). For the second type,
212the field decl name is obtained with bt_ctf_get_decl_field_name().
213
214The declaration functions allow the user to list the events, fields and
215contexts fields enabled in the trace once it is opened, whereas the definition
216functions apply on the current event being read.
217
218
219Callback:
220
221The iterator allow the user to read the trace, in order to access the events
222and fields, the user can either call the functions listed previously on each
223event, or register callbacks functions that are called when specific (or all)
224events are read.
225
226This is done with the bt_ctf_iter_add_callback() function. It requires a valid
227ctf iterator as the first argument. Here are all arguments:
228 iter: trace collection iterator (input)
229 event: event to target. 0 for all events.
230 private_data: private data pointer to pass to the callback
231 flags: specific flags controlling the behavior of this callback
232 (or'd).
233 callback: function pointer to call
234 depends: struct bt_dependency detailing the required computation
235 results. Ends with 0.
236 weak_depends: struct bt_dependency detailing the optional computation
237 results that can be optionally consumed by this
238 callback.
239 provides: struct bt_dependency detailing the computation results
240 provided by this callback.
241 Ends with 0.
242
243"depends", "weak_depends" and "provides" memory is handled by the babeltrace
244library after this call succeeds or fails. These objects can still be used by
245the caller until the babeltrace iterator is destroyed, but they belong to the
246babeltrace library.
247
248As of now the flags and dependencies are not used, the callbacks are
249processed in FIFO order.
250
251Note: once implemented, the dependency graph will be calculated when
252bt_ctf_iter_read_event() is executed after a bt_ctf_iter_add_callback(). It is
253valid to create/add callbacks/read/add more callbacks/read some more.
254
255The callback function passed to bt_ctf_iter_add_callback() must return a
256bt_cb_ret value:
257 BT_CB_OK = 0,
258 BT_CB_OK_STOP = 1,
259 BT_CB_ERROR_STOP = 2,
260 BT_CB_ERROR_CONTINUE = 3.
261
262
263Trace handle:
264
265When a trace is added to a context, bt_context_add_trace() returns a trace
266handle id. This id is associated with its corresponding trace handle. With
267that id, it is possible to manipulate directly the trace.
268
269 * bt_trace_handle_get_path()
270 -> returns the path of the trace handle (path to the trace).
271
272 * bt_trace_handle_get_timestamp_begin()
273 * bt_trace_handle_get_timestamp_end()
274 -> return the creation/destruction timestamps (in ns or cycles
275 depending on the type specified) of the buffers of a
276 trace.
277
278 * bt_ctf_event_get_handle_id()
279 -> returns the handle id associated with an event.
280
281
282For more information on CTF, see the CTF documentation.
This page took 0.053804 seconds and 4 git commands to generate.