camel-debug: Camel Reference Manual

## camel-debug camel-debug |

## Functions

void | camel_debug_init ()
gboolean | camel_debug ()
gboolean | camel_debug_start ()
void | camel_debug_end ()
#define | CAMEL_CHECK_GERROR()
#define | CAMEL_CHECK_LOCAL_GERROR()
#define | camel_pointer_tracker_track()
void | camel_pointer_tracker_track_with_info ()
void | camel_pointer_tracker_untrack ()
void | camel_pointer_tracker_dump ()
GString * | camel_debug_get_backtrace ()
GString * | camel_debug_get_raw_backtrace ()
void | camel_debug_demangle_backtrace ()
void | camel_debug_ref_unref_push_backtrace ()
void | camel_debug_ref_unref_push_backtrace_for_object ()
void | camel_debug_ref_unref_dump_backtraces ()

## Types and Values

#define | CAMEL_DEBUG_IMAP
#define | CAMEL_DEBUG_IMAP_FOLDER

## Description

## Functions

### camel_debug_init ()

    void
    camel_debug_init (void);

Init camel debug.

CAMEL_DEBUG is set to a comma separated list of modules to debug. The modules can contain module-specific specifiers after a ':', or just act as a wildcard for the module or even specifier. e.g. 'imap' for imap debug, or 'imap:folder' for imap folder debug. Additionaly, ':folder' can be used for a wildcard for any folder operations.

### camel_debug ()

    gboolean
    camel_debug (const gchar *mode);

Check to see if a debug mode is activated. `mode` takes one of two forms, a fully qualified 'module:target', or a wildcard 'module' name. It returns a boolean to indicate if the module or module and target is currently activated for debug output.

#### Parameters

mode | string name of the mode to check for |

#### Returns

Whether the debug `mode` is activated

### camel_debug_start ()

    gboolean
    camel_debug_start (const gchar *mode);

Start debug output for a given mode, used to make sure debug output is output atomically and not interspersed with unrelated stuff.

#### Parameters

mode | string name of the mode to start the debug for |

#### Returns

`TRUE` if mode is set, and in which case, you must call `camel_debug_end()` when finished any screen output.

### camel_debug_end ()

    void
    camel_debug_end (void);

Call this when you're done with your debug output. If and only if you called camel_debug_start, and if it returns TRUE.

### CAMEL_CHECK_GERROR()

    #define             CAMEL_CHECK_GERROR(object, method, expr, error)

This sanity checks return values and GError. If returning failure, make sure the GError is set. If returning success, make sure the GError is NOT set.

Example:

success = class->foo (object, some_data, error); CAMEL_CHECK_GERROR (object, foo, success, error); return success;

#### Parameters

object | a GObject descendant |
method | a method which was run |
expr | an expression to test, which evaluates to `TRUE` or `FALSE` |
error | a pointer to a pointer of a GError, set by the `method` |

Since: 2.32

### CAMEL_CHECK_LOCAL_GERROR()

    #define             CAMEL_CHECK_LOCAL_GERROR(object, method, expr, error)

Same as CAMEL_CHECK_GERROR, but for direct GError pointers.

Example:

success = class->foo (object, some_data, &local_error); CAMEL_CHECK_LOCAL_GERROR (object, foo, success, local_error); return success;

#### Parameters

object | a GObject descendant |
method | a method which was run |
expr | an expression to test, which evaluates to `TRUE` or `FALSE` |
error | a pointer to a GError, set by the `method` |

Since: 3.12

### camel_pointer_tracker_track()

    #define             camel_pointer_tracker_track(ptr)

Adds pointer 'ptr' to pointer tracker. Usual use case is to add object to the tracker in GObject::init and remove it from tracker within GObject::finalize. Since the tracker's functions are called, the application prints summary of the pointers on console on exit. If everything gone right then it prints message about all tracked pointers were removed. Otherwise it prints summary of left pointers in the tracker. Added pointer should be removed with pair function `camel_pointer_tracker_untrack()`.

See `camel_pointer_tracker_dump()`, `camel_pointer_tracker_track_with_info()`.

#### Parameters

ptr | pointer to add to pointer tracker |

Since: 3.6

### camel_pointer_tracker_track_with_info ()

    void
    camel_pointer_tracker_track_with_info (gpointer ptr,
                                           const gchar *info);

Adds pointer to the pointer tracker, with associated information, which is printed in summary of pointer tracker printed by `camel_pointer_tracker_dump()`. For convenience can be used `camel_pointer_tracker_track()`, which adds place of the caller as `info` . Added pointer should be removed with pair function `camel_pointer_tracker_untrack()`.

#### Parameters

ptr | pointer to add to the pointer tracker |
info | info to print in tracker summary |

Since: 3.6

### camel_pointer_tracker_untrack ()

    void
    camel_pointer_tracker_untrack (gpointer ptr);

Removes pointer from the pointer tracker. It's an error to try to remove pointer which was not added to the tracker by `camel_pointer_tracker_track()` or `camel_pointer_tracker_track_with_info()`, or a pointer which was already removed.

#### Parameters

ptr | pointer to remove from the tracker |

Since: 3.6

### camel_pointer_tracker_dump ()

    void
    camel_pointer_tracker_dump (void);

Prints information about currently stored pointers in the pointer tracker. This is called automatically on application exit if `camel_pointer_tracker_track()` or `camel_pointer_tracker_track_with_info()` was called.

Note: If the library is configured with --enable-backtraces, then also backtraces where the pointer was added is printed in the summary.

Since: 3.6

### camel_debug_get_backtrace ()

    GString *
    camel_debug_get_backtrace (void);

Gets current backtrace leading to this function call and demangles it.

#### Returns

Current backtrace, or `NULL`, if cannot determine it.

Note: Getting backtraces only works if the library was configured with --enable-backtraces.

See also `camel_debug_get_raw_backtrace()`

Since: 3.12

### camel_debug_get_raw_backtrace ()

    GString *
    camel_debug_get_raw_backtrace (void);

Gets current raw backtrace leading to this function call. This is quicker than `camel_debug_get_backtrace()`, because it doesn't demangle the backtrace. To demangle it (replace addresses with actual function calls and eventually line numbers, if available) call `camel_debug_demangle_backtrace()`.

#### Returns

Current raw backtrace, or `NULL`, if cannot determine it.

Note: Getting backtraces only works if the library was configured with --enable-backtraces.

See also `camel_debug_get_backtrace()`

Since: 3.30

### camel_debug_demangle_backtrace ()

    void
    camel_debug_demangle_backtrace (GString *bt);

Demangles `bt` , possibly got from `camel_debug_get_raw_backtrace()`, by replacing addresses with actual function calls and eventually line numbers, if available. It modifies lines of `bt` , but skips those it cannot parse.

Note: Getting backtraces only works if the library was configured with --enable-backtraces.

See also `camel_debug_get_raw_backtrace()`

#### Parameters

bt | a GString with a raw backtrace, or `NULL`. | [inout][nullable]

Since: 3.30

### camel_debug_ref_unref_push_backtrace ()

    void
    camel_debug_ref_unref_push_backtrace (const GString *backtrace,
                                          guint object_ref_count);

Adds this backtrace into the set of backtraces related to some object reference counting issues debugging. This is usually called inside `g_object_ref()` and `g_object_unref()`. If the backtrace corresponds to a `g_object_unref()` call, and a corresponding `g_object_ref()` backtrace is found in the current list, then the previous backtrace is removed and this one is skipped.

Any left backtraces in the list are printed at the application end.

A convenient function `camel_debug_ref_unref_push_backtrace_for_object()` is provided too.

#### Parameters

backtrace | a backtrace to push, taken from `camel_debug_get_backtrace()` |
object_ref_count | the current object reference count when the push is done |

Since: 3.20

### camel_debug_ref_unref_push_backtrace_for_object ()

    void
    camel_debug_ref_unref_push_backtrace_for_object
                                   (gpointer _object);

Gets current backtrace of this call and adds it to the list of backtraces with `camel_debug_ref_unref_push_backtrace()`.

Usual usage would be, once GNOME bug 758358 is applied to the GLib sources, or a patched GLib is used, to call this function in an object `init()` function, like this:

static void my_object_init (MyObject *obj) { camel_debug_ref_unref_push_backtrace_for_object (obj); g_track_object_ref_unref (obj, (GFunc) camel_debug_ref_unref_push_backtrace_for_object, NULL); }

Note that the `g_track_object_ref_unref()` can track only one pointer, thus make sure you track the right one (add some logic if multiple objects are created at once).

#### Parameters

_object | a GObject, for which add the backtrace |

Since: 3.20

### camel_debug_ref_unref_dump_backtraces ()

    void
    camel_debug_ref_unref_dump_backtraces (void);

Prints current backtraces stored with `camel_debug_ref_unref_push_backtrace()` or with `camel_debug_ref_unref_push_backtrace_for_object()`.

It's usually not needed to use this function, as the left backtraces, if any, are printed at the end of the application.

Since: 3.20

## Types and Values

### CAMEL_DEBUG_IMAP

    #define CAMEL_DEBUG_IMAP "imap"

### CAMEL_DEBUG_IMAP_FOLDER

    #define CAMEL_DEBUG_IMAP_FOLDER "imap:folder"