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

# Overview Of Allocated Memory
[Memory Allocation Debug Support]

Collaboration diagram for Overview Of Allocated Memory:

## Related
| Format Of The Overview Of Allocated Memory
| Invisible Allocations
## Functions
std::ostream & | libcwd::operator<< (std::ostream &o, malloc_report_nt)
| Allow writing of enum malloc_report_nt to an ostream.
unsigned long | libcwd::list_allocations_on (debug_ct &debug_object)
| List all current allocations to a given debug object.With CWDEBUG_ALLOC set to 1, it is possible to write the overview of allocated memory to a Debug Object.
unsigned long | libcwd::list_allocations_on (debug_ct &debug_object, alloc_filter_ct const &filter)
| List all current allocations to a given debug object using a specified format.With CWDEBUG_ALLOC set to 1, it is possible to write the overview of allocated memory to a Debug Object.

## Detailed Description

An example output, using libcw-0.2.5, is given below. Please follow the links to get a short explanation.

    MALLOC  : Allocated memory: 3100 bytes in 14 blocks.
    malloc        0x819f068              sock.cc:92   sockaddr_in []; (sz = 16)  sockbuf_dbct::addr
    malloc        0x819dea0        dbstreambuf.h:582  char []; (sz = 512)  dbstreambuf_ct::dbstreambuf_block_dct::block
                  0x8122240       dbstreambuf.cc:68   dbstreambuf_ct::dbstreambuf_block_dct; (sz = 20)
                  0x81400e8 streambuf::streambuf(int) <unknown type>; (sz = 24)
                  0x8122400               sock.h:225  dbstreambuf_ct; (sz = 144)
    malloc        0x8140678        dbstreambuf.h:582  char []; (sz = 2048)  dbstreambuf_ct::dbstreambuf_block_dct::block
                  0x81405c8       dbstreambuf.cc:68   dbstreambuf_ct::dbstreambuf_block_dct; (sz = 20)
                  0x8140558 streambuf::streambuf(int) <unknown type>; (sz = 24)
                  0x8140428               sock.h:225  dbstreambuf_ct; (sz = 144)
                  0x8140320        reduce_tst.cc:263  sock_dtct<socket_input_ct, socket_ostream_ct>; (sz = 100)
                  0x813fd80            select.cc:106  list_tct<sbll_list_ct, fd_dct>; (sz = 8)  fd_dct::write_fd_list
                  0x8122360            select.cc:104  list_tct<sbll_list_ct, fd_dct>; (sz = 8)  fd_dct::readwrite_fd_list
                  0x81221e0            select.cc:102  list_tct<sbll_list_ct, fd_dct>; (sz = 8)  fd_dct::read_fd_list
                  0x80545c8           libcw_app.h:140  reduce_tst_app_ct; (sz = 24)  The application object

### allocator type

A label in the first column of the Allocated memory Overview indicates with which type of allocator the memory block was allocated. Table 3 lists the labels that are being used for each of the allocator types (see memblk_types_nt for their meaning).

##### Table 3. The values of memblk_types_nt and the corresponding label in the Allocated memory Overview

Type | Label
`memblk_type_new` |
`memblk_type_deleted` | `(deleted)`
`memblk_type_new_array` | `new[]`
`memblk_type_deleted_array` | `(deleted)`
`memblk_type_malloc` | `malloc`
`memblk_type_realloc` | `realloc`
`memblk_type_freed` | `(freed)`
`memblk_type_noheap` | `(NO HEAP)`
`memblk_type_removed` | `(No heap)`
`memblk_type_marker` | `(MARKER)`
`memblk_type_deleted_marker` | `(deleted)`

### start address

The second column of the Allocated memory Overview gives the hexadecimal start address of the allocated memory block. This is the value returned by the allocator (`malloc`, `new` etc). Note that, when CWDEBUG_MAGIC is set, a magic number is put in front of this hexadecimal start address. The result is that you can ignore completely whether CWDEBUG_MAGIC is 0 or 1, in your own program.

### source file location

The third column of the Allocated memory Overview gives the source file location where the memory was allocated, or reallocated in the case of of `realloc`. The format is `<filename>:<line number>`.

When the allocation is done in an object file without debug information and no source file or line number is known, then instead the name of the function in which the allocation was done is given.

### type

The fourth column of the Allocated memory Overview starts with the `type` of the allocated object (i.e., the `class` name). This information is only available when `AllocTag()` was called correctly for this allocation. Otherwise `<unknown type>` is shown instead.

The given `type` is derived, but different, from what type_info_ct::demangled_name() returns. The `*` at the end of the type of the pointer is omitted when the memory block was allocated with `new`, it is replaced with `[size]` when the memory block was allocated with `new[]` and it is replaced with `[]` when the memory block was allocated with `malloc`.

Examples were already given, but a summary is given in table 4 nonetheless. The <length> that is given between square brackets is the rounded down value of the size of the allocated memory block divided by the size of the object that is being pointed to. This will always be accurate for an `operator new []` of course, but its kinda fuzzy for an allocation with `malloc` et al.

##### Table 4. The format of the type field in the Allocated memory Overview, as function of the allocator.

Allocator | Type | Format
`malloc/calloc/realloc` | `void*` | `void*`
`malloc/calloc/realloc` | `int*` | `int [<length>]`
`new` | `MyClass*` | `MyClass`
`new []` | `MyClass*` | `MyClass [<length>]`

### size

The number of allocated bytes is printed as `(sz =` <size>`)`, where <size> is the size of the returned memory block in bytes.

### description

Finally, the description that was passed along with `AllocTag()` is printed.

## Function Documentation

unsigned long libcwd::list_allocations_on | ( | debug_ct & | debug_object,
|  | alloc_filter_ct const & | filter |
| ) |  |  |

List all current allocations to a given debug object using a specified format.With CWDEBUG_ALLOC set to 1, it is possible to write the overview of allocated memory to a Debug Object.

For example:

     Debug(
       alloc_filter_ct alloc_filter(show_objectfile);
       std::vector<std::string> masks;
       masks.push_back("libc.so*");
       masks.push_back("libstdc++*");
       alloc_filter.hide_objectfiles_matching(masks);
       alloc_filter.hide_unknown_locations();
       list_allocations_on(libcw_do, alloc_filter)
     );

which would print on libcw_do using debug channel dc::malloc , not showing allocations that belong to shared libraries matching "libc.so*" or "libstdc++*". The remaining items would show which object file (shared library name or the executable name) they belong to, because we used `show_objectfile` as flag.

Returns:
  the number of unfiltered (listed) allocations.

See also:
  Format Of The Overview Of Allocated Memory

References LibcwDout.

void libcwd::list_allocations_on | ( | debug_ct & | debug_object | ) | `[inline]`

List all current allocations to a given debug object.With CWDEBUG_ALLOC set to 1, it is possible to write the overview of allocated memory to a Debug Object.

By default only the allocations that were made by the current thread will be printed. Use show_allthreads, together with a filter object, in order to get a listing of the allocations of all threads (see below).

The syntax to do this is:

     Debug( list_allocations_on(libcw_do) );        // libcw_do is the (default) debug object.

which would print on libcw_do using debug channel dc::malloc .

Note that not passing formatting information is equivalent with,

     Debug(
         alloc_filter_ct format(0);
         list_allocations_on(debug_object, format)
     );

meaning that all allocations are shown without time, without path and without to which library they belong to.

Returns:
  the number of actually printed allocations.

std::ostream& libcwd::operator<< | ( | std::ostream & | o,
|  | malloc_report_nt |  |
| ) |  |  |

Allow writing of enum malloc_report_nt to an ostream.

See also:
  malloc_report_nt