libcwd: The C++ Debugging Support Library - Reference Manual
Author: Carlo Wood
Description: C++ debugging support library with ostream debug output
Keywords: libcwd, debug output, debug facility, debug channel, object orientation, OO, C++, nested debug output, ostream, memory allocation, debugging, source file and line number

Main Page Reference Manual Namespace List Compound List Namespace Members Compound Members File Members

# Format Of The Overview Of Allocated Memory
[Overview Of Allocated Memory]

Collaboration diagram for Format Of The Overview Of Allocated Memory:

## Typedefs
typedef unsigned short int | libcwd::alloc_format_t
| The type used for the formatting flags of an alloc_filter_ct object.

## Detailed Description

The format of the Overview Of Allocated Memory can be altered and/or the content can be filtered by passing an object of type libcwd::alloc_filter_ct to the function list_allocations_on. This object is constructed out of `alloc_format_t` constants which act as bits in a bit-mask.

It is possible to include the time at which each allocation was made by passing the bit `show_time`. This will prepend "hours:minutes:seconds.microseconds" to the output:

    04:07:16.712874 malloc    0x8078648          alloctag.cc:65   void*; (sz = 220)

It is also possible to show the full path of the location file by passing the bit `show_path`. This makes the output look like:

    malloc    0x8078648 /home/carlo/c++/libcwd/testsuite/libcwd.tst/alloctag.cc:65   void*; (sz = 220)

It is also possible to show the name of the object file (shared library or executable name) to which the allocation belongs by using the bit `show_objectfile`. The name of the corresponding object file is prepended to the location:

    malloc    0x8078648 tst_alloctag_shared:         alloctag.cc:65   void*; (sz = 220)

Finally, it is possible to show the mangled function name where the allocation was done by using the bit `show_function`. The mangled name of the corresponding function is prepended to the location:

    new[]     0x8199158 _Z7new1000j           module.cc:47   char[1000]; (sz = 1000)

The flags can be combined with the bit-wise OR operator.

Example:

    #ifdef CWDEBUG
    libcwd::alloc_filter_ct filter(libcwd::show_time | libcwd::show_path);
    #endif

    Debug( list_allocations_on(libcw_do, filter) );

Filtering

There are four criteria on which can be filtered: the time at which an allocation was made, the shared library that an allocation belongs too, the name of the source file from which an allocation was made and whether or not an AllocTag was used for the allocation.

It is possible to give a time interval of the allocations that should be shown. For each of the limits (start and end) one can use the constant struct timeval libcwd::alloc_filter_ct::no_time_limit to indicate that there is no limit required.

It is also possible to specify a list of wildcard masks (of the kind where a '*' matches anything) that will be matched against the names of the shared libraries, hiding the allocations that belong to the libraries whose name match.

It is also possible to specify a list of wildcard masks (of the kind where a '*' matches anything) that will be matched against the names of the source file from which the allocation was done, only showing the allocations that whose name match.

Finally, it is also possible to hide all allocations except when one of the AllocTag macros was used. Please note that using this option makes it hard to see whether or not your application has any memory leaks in the case the leak has no `AllocTag` added.

Examples:

In order to show all allocations that were done one hour or more ago, one could do:

    #ifdef CWDEBUG
    libcwd::alloc_filter_ct filter(libcwd::show_time);
    struct timeval end;
    gettimeofday(&end, 0);
    end.tv_sec -= 3600;
    filter.set_time_interval(libcwd::alloc_filter_ct::no_time_limit, end);
    #endif

    Debug( list_allocations_on(libcw_do, filter) );

In order to hide all allocations that belong to any shared library (only leaving the allocations that belong to the executable), one could do:

    #ifdef CWDEBUG
    libcwd::alloc_filter_ct filter(libcwd::show_objectfile);
    std::vector<std::string> masks;
    masks.push_back("lib*");
    filter.hide_objectfiles_matching(masks);
    #endif

    Debug( list_allocations_on(libcw_do, filter) );

In order to hide allocations done from a specific function in a specific shared library, one could do:

    #ifdef CWDEBUG
    libcwd::alloc_filter_ct filter(libcwd::show_objectfile|libcwd::show_function);
    std::vector<std::pair<std::string, std::string> > hide_list;
    hide_list.push_back(std::pair<std::string, std::string>("libdl.so.2", "_dlerror_run"));
    hide_list.push_back(std::pair<std::string, std::string>("libstdc++.so.6", "__cxa_get_globals"));
    filter.hide_functions_matching(hide_list);
    #endif

    Debug( list_allocations_on(libcw_do, filter) );

Note that also here it is allowed to use masks, for both the object file as well as the mangled function name.

In order to hide all allocations that are done from inside the header files of installed libraries (like the STL), one could do:

    #ifdef CWDEBUG
    libcwd::alloc_filter_ct filter(libcwd::show_path);
    std::vector<std::string> masks;
    masks.push_back("/usr/include/*.h");
    filter.hide_sourcefiles_matching(masks);
    #endif

    Debug( list_allocations_on(libcw_do, filter) );

In order to hide everything except those allocations that one explicitely added an AllocTag for, one could do:

    #ifdef CWDEBUG
    libcwd::alloc_filter_ct filter;
    filter.hide_untagged_allocations();
    #endif

    Debug( list_allocations_on(libcw_do, filter) );