| 1 | /*! |
| 2 | @page api-fund API fundamentals |
| 3 | |
| 4 | This page explains the basic principles of the \bt_api. |
| 5 | |
| 6 | You \em must understand what the API expects before you create a |
| 7 | \bt_name \bt_plugin or an application which uses the API. |
| 8 | |
| 9 | @section api-fund-header Header file |
| 10 | |
| 11 | To use the \bt_api, include <code>%babeltrace2/babeltrace.h</code>: |
| 12 | |
| 13 | @code |
| 14 | #include <babeltrace2/babeltrace.h> |
| 15 | @endcode |
| 16 | |
| 17 | Do \em not include any other header file found in the \c babeltrace2 |
| 18 | directory: the compiler prints an error when you try to. |
| 19 | |
| 20 | @section api-fund-ns Namespace |
| 21 | |
| 22 | - All libbabeltrace2 functions and types start with \c bt_. |
| 23 | |
| 24 | - All libbabeltrace2 definitions, macros, and enumerators start |
| 25 | with \c BT_. |
| 26 | |
| 27 | @section api-fund-pre-post Function contract checking |
| 28 | |
| 29 | All the functions of libbabeltrace2 check that the caller meets their |
| 30 | <a href="https://en.wikipedia.org/wiki/Precondition">preconditions</a>. |
| 31 | |
| 32 | All the functions of libbabeltrace2 which call a user function check |
| 33 | that it meets its |
| 34 | <a href="https://en.wikipedia.org/wiki/Postcondition">postconditions</a> |
| 35 | when it returns. |
| 36 | |
| 37 | The function descriptions in the |
| 38 | <a class="el" href="modules.html">API reference modules</a> |
| 39 | list all their preconditions and postconditions, if any. |
| 40 | |
| 41 | The libbabeltrace2 public functions offer a |
| 42 | <strong>narrow contract</strong>: when you break it, the library |
| 43 | prints how the precondition or postcondition was not satisfied, with |
| 44 | details, and then calls <code>abort()</code>. |
| 45 | |
| 46 | Here's an example of what the library prints to the standard error |
| 47 | before aborting when you break a precondition (call |
| 48 | bt_value_bool_set() with a \c NULL value); |
| 49 | \ref api-fund-logging "logging" prefixes are removed for clarity: |
| 50 | |
| 51 | @code{.unparsed} |
| 52 | Babeltrace 2 library precondition not satisfied. |
| 53 | ------------------------------------------------------------------------ |
| 54 | Condition ID: `pre:value-bool-set:not-null:value-object`. |
| 55 | Function: bt_value_bool_set(). |
| 56 | ------------------------------------------------------------------------ |
| 57 | Error is: |
| 58 | Value object is NULL. |
| 59 | Aborting... |
| 60 | @endcode |
| 61 | |
| 62 | In the output above: |
| 63 | |
| 64 | - <code>pre:value-bool-set:not-null:value-object</code> is the unique, |
| 65 | permanent ID of this precondition. |
| 66 | |
| 67 | We use this ID for internal libbabeltrace2 testing. |
| 68 | |
| 69 | - The <code>Function:</code> line shows which function's contract was |
| 70 | broken. |
| 71 | |
| 72 | Because precondition and postcondition checks detect programming errors, |
| 73 | libbabeltrace2's approach is to abort as soon as possible so that you |
| 74 | fix the error. Therefore, the libbabeltrace2 functions never return a |
| 75 | programming error status (like what \c EINVAL means on Unix systems, for |
| 76 | example). |
| 77 | |
| 78 | @attention |
| 79 | Some precondition and postcondition checks which occur on the fast |
| 80 | path and which would therefore significantly impact performance |
| 81 | during a typical trace processing \bt_graph run are only enabled in |
| 82 | \ref guide-build-bt2-dev "developer mode". |
| 83 | |
| 84 | Common function preconditions are: |
| 85 | |
| 86 | - A pointer parameter is not \c NULL. |
| 87 | |
| 88 | - An index parameter is not ouf of bounds. |
| 89 | |
| 90 | - A string or container parameter is not empty. |
| 91 | |
| 92 | - An object parameter has a given conceptual type. For example, you |
| 93 | cannot call bt_value_array_get_length() with a |
| 94 | \bt_bool_val. |
| 95 | |
| 96 | - An object parameter is not \ref api-fund-freezing "frozen". |
| 97 | |
| 98 | - An object parameter has some specific state. |
| 99 | |
| 100 | @section api-fund-object Object model |
| 101 | |
| 102 | The \bt_api is |
| 103 | <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented</a>. |
| 104 | |
| 105 | With a few exceptions, API functions are actually |
| 106 | <a href="https://en.wikipedia.org/wiki/Method_(computer_programming)"><em>methods</em></a> |
| 107 | which operate on objects: their first parameter points to said object. |
| 108 | For example: |
| 109 | |
| 110 | @code |
| 111 | uint64_t bt_value_array_get_length(const bt_value *value); |
| 112 | @endcode |
| 113 | |
| 114 | You can create some types of objects with functions that contain the |
| 115 | word \c create, while for some other types, only the library can create |
| 116 | them behind the scenes. For example, you can create a |
| 117 | \bt_bool_val object with bt_value_bool_create(), but you cannot directly |
| 118 | create a \bt_ev object: you need to borrow one from a \bt_ev_msg which |
| 119 | contains it. |
| 120 | |
| 121 | Each type of object has its own C type. Learn more about typing in |
| 122 | \ref api-fund-c-typing below. |
| 123 | |
| 124 | Some types of objects conceptually inherit other types of objects. If an |
| 125 | object type A inherits an object type B, then you can use both the A and |
| 126 | B API functions with an object of type A. For example, because an |
| 127 | \bt_enum_fc \em is conceptually an \bt_int_fc, you can use any integer |
| 128 | field class function with an enumeration field class. |
| 129 | The <a class="el" href="modules.html">API reference modules</a> always |
| 130 | indicate the inheritance relations. |
| 131 | |
| 132 | @subsection api-fund-object-shared-unique Shared vs. unique objects |
| 133 | |
| 134 | Some \bt_name objects are \em shared while some others are \em unique: |
| 135 | |
| 136 | <dl> |
| 137 | <dt>\anchor api-fund-shared-object Shared object</dt> |
| 138 | <dd> |
| 139 | A \em shared object has a <a |
| 140 | href="https://en.wikipedia.org/wiki/Reference_counting">reference |
| 141 | count</a>. |
| 142 | |
| 143 | A shared object's creation function returns a \em new reference. |
| 144 | |
| 145 | The API of a given shared object type contains: |
| 146 | |
| 147 | - A function to get a new reference, increasing the reference count, |
| 148 | which ends with \c _get_ref. |
| 149 | |
| 150 | - A function to put an existing reference, decreasing the reference |
| 151 | count, which ends with \c _put_ref. |
| 152 | |
| 153 | - A macro to put an existing reference and then set the passed |
| 154 | expression to \c NULL. This macro ends with \c _PUT_REF_AND_RESET. |
| 155 | |
| 156 | - A macro to move an existing reference from a source expression to |
| 157 | a destination expression, putting the destination expression's |
| 158 | existing reference, and setting the source expression to \c NULL. |
| 159 | This macro ends with \c _MOVE_REF. |
| 160 | |
| 161 | For example, bt_value_get_ref() and bt_value_put_ref() get and put |
| 162 | \bt_val object references, BT_VALUE_PUT_REF_AND_RESET() puts a |
| 163 | value reference and sets the expression to \c NULL, and |
| 164 | BT_VALUE_MOVE_REF() moves a value reference. |
| 165 | |
| 166 | All <code>*_get_ref()</code> and <code>*_put_ref()</code> functions, |
| 167 | and all <code>*_PUT_REF_AND_RESET()</code> macros accept a \c NULL |
| 168 | parameter. |
| 169 | |
| 170 | When the reference count of a given object reaches zero, it \em can |
| 171 | be destroyed. Some shared objects, however, have a lifetime that is |
| 172 | managed by another shared object. For example, an \bt_ev_cls is not |
| 173 | destroyed until its parent \bt_stream_cls is also destroyed, even if |
| 174 | its reference count technically reaches zero. |
| 175 | |
| 176 | A function which accepts a shared object never "takes" or steals the |
| 177 | caller's reference unless its name contains the word \c move: you |
| 178 | still have your own reference when the function returns. For |
| 179 | example: |
| 180 | |
| 181 | @code |
| 182 | bt_event_class *event_class = bt_event_class_create(stream_class); |
| 183 | |
| 184 | /* |
| 185 | * At this point, we still have a reference of `stream_class`. |
| 186 | * We need to put it with bt_stream_class_put_ref() at some point. |
| 187 | */ |
| 188 | @endcode |
| 189 | |
| 190 | A function which contains the word \c borrow returns a |
| 191 | <em>borrowed reference</em>: if you need your own reference, get |
| 192 | one with the appropriate <code>*_get_ref()</code> function. |
| 193 | </dd> |
| 194 | |
| 195 | <dt>\anchor api-fund-unique-object Unique object</dt> |
| 196 | <dd> |
| 197 | A \em unique object does not have a reference count: another object |
| 198 | is always its sole owner. |
| 199 | |
| 200 | Because you cannot get a new unique object reference, you \em must |
| 201 | ensure that you own the unique object's owner to keep it alive. The |
| 202 | <a class="el" href="modules.html">API reference modules</a> make it |
| 203 | clear, depending on the context, which |
| 204 | shared object is the ultimate owner of a given unique object. |
| 205 | |
| 206 | In general, you cannot create a unique object: the library creates |
| 207 | it, and then you \em borrow it from another object (shared or unique |
| 208 | itself). |
| 209 | |
| 210 | Unique objects exist for performance reasons: some optimizations are |
| 211 | challenging to implement without this concept. |
| 212 | </dd> |
| 213 | </dl> |
| 214 | |
| 215 | In the <a class="el" href="modules.html">API reference</a>, each module |
| 216 | indicates whether the documented objects are shared or unique. |
| 217 | |
| 218 | @subsection api-fund-freezing Object freezing |
| 219 | |
| 220 | The library can \em freeze some types of \bt_name objects when specific |
| 221 | functions succeed. |
| 222 | |
| 223 | A frozen object is immutable: trying to set an object's property once |
| 224 | it's frozen represents a \ref api-fund-pre-post "precondition" break. |
| 225 | |
| 226 | For example, the library freezes the source \bt_comp initialization |
| 227 | parameters when you call bt_graph_add_source_component(): this |
| 228 | guarantees to the component's |
| 229 | \ref api-comp-cls-dev-meth-init "initialization method" that the |
| 230 | parameters will never change for the rest of their lifetime. |
| 231 | |
| 232 | When an object becomes frozen, its contained objects, if any, also |
| 233 | become frozen, recursively. |
| 234 | |
| 235 | There's no function to check whether or not a given object is frozen. |
| 236 | Because the <a class="el" href="modules.html">API reference modules</a> |
| 237 | document which functions freeze which objects, |
| 238 | the "frozen" property is only useful for libbabeltrace2 to catch |
| 239 | programming errors (\ref api-fund-pre-post "precondition checks"). |
| 240 | |
| 241 | @attention |
| 242 | Some "frozen" property checks which occur on the fast path and which |
| 243 | would therefore significantly impact performance during a typical trace |
| 244 | processing \bt_graph run are only enabled in |
| 245 | \ref guide-build-bt2-dev "developer mode". |
| 246 | |
| 247 | @section api-fund-c-typing C typing |
| 248 | |
| 249 | The \bt_api typing system is very strict to catch many programming |
| 250 | errors at compile time. |
| 251 | |
| 252 | Each type of object has its own C type. Consequently, functions accept |
| 253 | and return specific C types. For example, all the \bt_ev functions |
| 254 | accept a #bt_event pointer. |
| 255 | |
| 256 | The API uses |
| 257 | <a href="https://en.wikipedia.org/wiki/Opaque_pointer">opaque pointers</a>, |
| 258 | so that you don't having access to the object type's actual C structure. |
| 259 | This helps with the development of features and fixes in future releases |
| 260 | of \bt_name. |
| 261 | |
| 262 | Some objects share the same C type when different conceptual types can |
| 263 | be contained in some collection. For example, all \bt_val objects have |
| 264 | the type #bt_value because an \bt_array_val can contain different |
| 265 | types of values. You must be careful to only call the functions which |
| 266 | apply to a specific type of such objects. |
| 267 | The <a class="el" href="modules.html">API reference modules</a> make |
| 268 | this clear in the precondition section. Such objects always have a |
| 269 | <code>*_get_type()</code> function to get the object's exact type |
| 270 | enumerator. For example, bt_value_get_type() returns the type enumerator |
| 271 | of a given \bt_val object. |
| 272 | |
| 273 | When an object type A conceptually inherits an object type B, and when A |
| 274 | and B have different C types, the API offers a dedicated, inline |
| 275 | upcasting function named <code>bt_A_as_B()</code> to have access to the B |
| 276 | API at no cost. For example, an \bt_uenum_fc mapping \em is conceptually |
| 277 | an \bt_enum_fc mapping, but they have different C types: |
| 278 | #bt_field_class_enumeration_unsigned_mapping and |
| 279 | #bt_field_class_enumeration_mapping. Get the latter from the former with |
| 280 | bt_field_class_enumeration_unsigned_mapping_as_mapping_const(). |
| 281 | The <code>bt_A_as_B()</code> functions do not change the object's |
| 282 | reference count and they accept \c NULL. |
| 283 | |
| 284 | @attention |
| 285 | \b Never directly cast a \bt_name object pointer from some C type to |
| 286 | another C type: the API is designed so that you never need to do |
| 287 | that. |
| 288 | |
| 289 | @subsection api-fund-const const correctness |
| 290 | |
| 291 | The \bt_api is <code>const</code>-correct: when a function has a |
| 292 | \c const object pointer parameter, it never modifies that object from |
| 293 | the user's viewpoint. |
| 294 | |
| 295 | As such, when a function returns a \c const object pointer, directly or |
| 296 | through an output parameter, you can't modify the object. |
| 297 | |
| 298 | @attention |
| 299 | \b Never remove a \bt_name object pointer's \c const qualifier. The |
| 300 | API is designed so that you never need to do that. |
| 301 | |
| 302 | Functions which accept or return a \c const object pointer end with |
| 303 | \c _const when they have (or could have in the future) a non \c const |
| 304 | equivalent. For example, bt_value_map_borrow_entry_value_const() is the |
| 305 | \c const version of bt_value_map_borrow_entry_value(). |
| 306 | |
| 307 | Simple property getter functions do not end with \c _const. |
| 308 | |
| 309 | \ref api-fund-shared-object "Reference count" changing functions, ending |
| 310 | with \c _get_ref and \c _put_ref(), accept a \c const object pointer |
| 311 | parameter: the library does not consider that an object's nature is |
| 312 | altered when its reference count changes. |
| 313 | |
| 314 | @subsection api-fund-int-types C integer types |
| 315 | |
| 316 | The API only uses \c uint64_t and \c int64_t as C integer types for |
| 317 | clarity and consistency. |
| 318 | |
| 319 | @subsection api-fund-common-types Common C types and definitions |
| 320 | |
| 321 | There are a few C types and definitions which are common to many parts |
| 322 | of the \bt_api. |
| 323 | |
| 324 | See \ref api-common-types. |
| 325 | |
| 326 | @section api-fund-func-status Function return |
| 327 | |
| 328 | libbabeltrace2 functions which cannot fail return a property or an |
| 329 | object pointer directly. For example, bt_value_array_get_length() |
| 330 | returns the length of an \bt_array_val, and |
| 331 | bt_value_array_borrow_element_by_index_const() returns a \bt_val |
| 332 | contained in an \bt_array_val. Both functions cannot fail: any |
| 333 | programming error \ref api-fund-pre-post "makes the program abort". |
| 334 | |
| 335 | When a function returns an optional property or object: |
| 336 | |
| 337 | <dl> |
| 338 | <dt>If it's a pointer</dt> |
| 339 | <dd> |
| 340 | The function returns \c NULL if the property/object is missing. |
| 341 | </dd> |
| 342 | |
| 343 | <dt>If it's not a pointer</dt> |
| 344 | <dd> |
| 345 | <dl> |
| 346 | <dt>If the property is available</dt> |
| 347 | <dd> |
| 348 | The function returns the property by output parameter and returns |
| 349 | #BT_PROPERTY_AVAILABILITY_AVAILABLE. |
| 350 | </dd> |
| 351 | |
| 352 | <dt>If the property is not available</dt> |
| 353 | <dd> |
| 354 | The function returns #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE. |
| 355 | </dd> |
| 356 | </dl> |
| 357 | </dd> |
| 358 | </dl> |
| 359 | |
| 360 | Many libbabeltrace2 functions return a status code, that is, a C |
| 361 | enumerator containing the word \c STATUS. For example, |
| 362 | bt_value_copy() returns either #BT_VALUE_COPY_STATUS_OK or |
| 363 | #BT_VALUE_COPY_STATUS_MEMORY_ERROR. |
| 364 | |
| 365 | Although the API guarantees that any status enumerator which has the |
| 366 | \c _OK status has the value 0, we recommend that you compare the |
| 367 | returned value to exact status enumerators for clarity, for example: |
| 368 | |
| 369 | @code |
| 370 | bt_value_copy_status status = bt_value_copy(obj, &val_copy); |
| 371 | |
| 372 | if (status != BT_VALUE_COPY_STATUS_OK) { |
| 373 | /* handle error */ |
| 374 | } |
| 375 | @endcode |
| 376 | |
| 377 | The <a class="el" href="modules.html">API reference modules</a> |
| 378 | document, for each function, what each return status enumerator means. |
| 379 | |
| 380 | Some functions return properties or objects by output parameter. When |
| 381 | such a function which accepts a property or object pointer \c ptr fails, |
| 382 | the library does \em not guarantee that <code>*ptr</code> remains |
| 383 | unchanged. Therefore, such a pattern is \em not safe: |
| 384 | |
| 385 | @code |
| 386 | bt_some_object *some_object = NULL; |
| 387 | |
| 388 | status = bt_get_some_object(obj, &some_object); |
| 389 | |
| 390 | if (some_object) { |
| 391 | /* ... */ |
| 392 | } |
| 393 | @endcode |
| 394 | |
| 395 | Always rely on the returned status code: |
| 396 | |
| 397 | @code |
| 398 | bt_some_object *some_object; |
| 399 | |
| 400 | status = bt_get_some_object(obj, &some_object); |
| 401 | |
| 402 | if (status == BT_GET_SOME_OBJECT_STATUS_OK) { |
| 403 | /* ... */ |
| 404 | } |
| 405 | @endcode |
| 406 | |
| 407 | @section api-fund-user-classes User classes |
| 408 | |
| 409 | The whole \bt_name project is about extensibility: you can implement |
| 410 | \bt_p_comp_cls, and then package and distribute them as |
| 411 | \bt_p_plugin. |
| 412 | |
| 413 | When you implement a \bt_name \bt_comp_cls, you override protected |
| 414 | methods, just like you would do in any |
| 415 | <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented programming</a> |
| 416 | (OOP) language. |
| 417 | |
| 418 | Here's the mapping of typical OOP language features to the |
| 419 | \bt_name library domain: |
| 420 | |
| 421 | <table> |
| 422 | <tr> |
| 423 | <th>OOP concept |
| 424 | <th>\bt_name equivalent |
| 425 | <tr> |
| 426 | <td>User class. |
| 427 | <td> |
| 428 | Class object with implemented user functions. |
| 429 | |
| 430 | For example: #bt_component_class_source. |
| 431 | <tr> |
| 432 | <td>User class instance. |
| 433 | <td> |
| 434 | Instance object, created from a class object. |
| 435 | |
| 436 | For example: #bt_component_source. |
| 437 | <tr> |
| 438 | <td> |
| 439 | Instance pointer (\c this keyword in C++/Java and \c self variable |
| 440 | in Python, for example). |
| 441 | <td> |
| 442 | "Self" (private) object. |
| 443 | |
| 444 | A "self" object has a specific, dedicated C type which starts |
| 445 | with <code>bt_self_</code>. |
| 446 | |
| 447 | For example: #bt_self_component_source. |
| 448 | <tr> |
| 449 | <td>Protected, final method. |
| 450 | <td> |
| 451 | Library function accepting an instance pointer ("self" object) as |
| 452 | its first parameter. |
| 453 | |
| 454 | Those functions always start with <code>bt_self_</code>. |
| 455 | |
| 456 | For example: bt_self_component_source_add_output_port(). |
| 457 | <tr> |
| 458 | <td>Protected, overridable method. |
| 459 | <td> |
| 460 | User function with a specific signature, accepting an instance |
| 461 | pointer ("self" object) as its first parameter. |
| 462 | |
| 463 | For example: #bt_component_class_source_initialize_method. |
| 464 | <tr> |
| 465 | <td>Private user method. |
| 466 | <td> |
| 467 | Custom \c static user function having access to the instance |
| 468 | pointer ("self" object) somehow. |
| 469 | <tr> |
| 470 | <td>Private user property or attribute. |
| 471 | <td> |
| 472 | Custom \bt_voidp data which you set and get using |
| 473 | dedicated protected methods (for example, |
| 474 | bt_self_component_set_data() and bt_self_component_get_data()). |
| 475 | </table> |
| 476 | |
| 477 | @section api-fund-error Error reporting |
| 478 | |
| 479 | libbabeltrace2 features a rich \ref api-error "error reporting" |
| 480 | mechanism to augment an error with custom causes without having to |
| 481 | explicitly pass an error object to the library functions. |
| 482 | |
| 483 | When a library function or \ref api-fund-user-classes "user method" |
| 484 | returns an error status code (any status enumerator which contains |
| 485 | the word \c ERROR), it \em can add one or more error causes to the |
| 486 | current thread's error object. |
| 487 | |
| 488 | This makes it possible for the end user to understand the contexts which |
| 489 | lead to the error, possibly across many \bt_p_plugin written by |
| 490 | different developers. |
| 491 | |
| 492 | An error cause contains information about the source location where the |
| 493 | error occurred, the actor involved in the error, and a message. |
| 494 | |
| 495 | When you "catch" an error, that is, react to a function returning an |
| 496 | error status code without returning an error status code yourself, |
| 497 | you can: |
| 498 | |
| 499 | - Take the current thread's error with bt_current_thread_take_error() to |
| 500 | get its causes, possibly presenting them to the end user. |
| 501 | |
| 502 | You then need to release the error with bt_error_release(). |
| 503 | |
| 504 | - Clear the current thread's error with bt_current_thread_clear_error(). |
| 505 | |
| 506 | @attention |
| 507 | You \em cannot call any libbabeltrace2 function when the current |
| 508 | thread has an error, except the |
| 509 | \ref api-fund-shared-object "reference counting" functions (ending |
| 510 | with <code>_get_ref()</code> or <code>_put_ref()</code>). |
| 511 | |
| 512 | The |
| 513 | <a href="https://babeltrace.org/docs/v\bt_version_min_maj/man1/babeltrace2.1"><code>babeltrace2</code></a> |
| 514 | CLI uses this feature to pretty-print an error's causes to the end user, |
| 515 | for example: |
| 516 | |
| 517 | @code{.unparsed} |
| 518 | ERROR: [Babeltrace CLI] (babeltrace2.c:2521) |
| 519 | Cannot create components. |
| 520 | CAUSED BY [Babeltrace CLI] (babeltrace2.c:2336) |
| 521 | Cannot create component: plugin-name="ctf", comp-cls-name="fs", comp-cls-type=0, |
| 522 | comp-name="auto-disc-source-ctf-fs" |
| 523 | CAUSED BY [libbabeltrace2] (graph.c:1343) |
| 524 | Component initialization method failed: status=ERROR, comp-addr=0x562fbd275f40, |
| 525 | comp-name="auto-disc-source-ctf-fs", comp-log-level=WARNING, comp-class-type=SOURCE, |
| 526 | comp-class-name="fs", comp-class-partial-descr="Read CTF traces from the file sy", |
| 527 | comp-class-is-frozen=1, comp-class-so-handle-addr=0x562fbd285810, |
| 528 | comp-class-so-handle-path="/usr/lib/babeltrace2/plugins/babeltrace-plugin-ctf.so", |
| 529 | comp-input-port-count=0, comp-output-port-count=0 |
| 530 | CAUSED BY [auto-disc-source-ctf-fs: 'source.ctf.fs'] (fs.c:1148) |
| 531 | Cannot create trace for `/path/to/trace`. |
| 532 | CAUSED BY [auto-disc-source-ctf-fs: 'source.ctf.fs'] (fs.c:928) |
| 533 | Cannot add stream file `/path/to/trace/channel0_1` to stream file group |
| 534 | CAUSED BY [auto-disc-source-ctf-fs: 'source.ctf.fs'] (fs.c:734) |
| 535 | Cannot get stream file's first packet's header and context fields (`/path/to/trace/channel0_1`). |
| 536 | @endcode |
| 537 | |
| 538 | @section api-fund-logging Logging |
| 539 | |
| 540 | libbabeltrace2 contains many hundreds of logging statements to help you |
| 541 | follow and debug your \bt_plugin or program. |
| 542 | |
| 543 | By default, the library's logging is disabled. To enable it, use |
| 544 | bt_logging_set_global_level(). |
| 545 | |
| 546 | To set the library's initial logging level (checked once at library |
| 547 | loading time), set the \c LIBBABELTRACE2_INIT_LOG_LEVEL environment |
| 548 | variable, with one of: |
| 549 | |
| 550 | - \c N or \c NONE |
| 551 | - \c F or \c FATAL |
| 552 | - \c E or \c ERROR |
| 553 | - \c W, \c WARN, or \c WARNING |
| 554 | - \c I or \c INFO |
| 555 | - \c D or \c DEBUG |
| 556 | - \c T or \c TRACE |
| 557 | |
| 558 | By default, the minimal, build-time logging level is \em DEBUG. We |
| 559 | recommend that you build libbabeltrace2 with the \em TRACE minimal |
| 560 | logging level for development. See \ref guide-build-bt2-dev. |
| 561 | |
| 562 | libbabeltrace2 writes its logging statements to the standard error |
| 563 | stream. |
| 564 | |
| 565 | A libbabeltrace2 (and \bt_name project plugin) logging line looks like |
| 566 | this: |
| 567 | |
| 568 | @code{.unparsed} |
| 569 | 05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0 |
| 570 | @endcode |
| 571 | |
| 572 | The line contains, in order: |
| 573 | |
| 574 | -# The date and time (<code>05-11 00:58:03.691</code>). |
| 575 | |
| 576 | -# The process and thread IDs (<code>23402 23402</code>). |
| 577 | |
| 578 | -# The logging level (\c D for \em DEBUG). |
| 579 | |
| 580 | -# The function logging (\c bt_value_destroy). |
| 581 | |
| 582 | -# The file and line number logging (<code>values.c:498</code>). |
| 583 | |
| 584 | -# The message, which typically ends with a list of fields adding |
| 585 | details. |
| 586 | */ |