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