Functions for debugging memory heaps

Debug versions are available for both regular memory management functions and user-defined heap memory management functions. Each debug version performs the same function as its non-debug counterpart, and you can use them for any type of heap, including shared memory. Each call you make to a debug function also automatically checks the heap by calling _heap_check (described below), and provides information, including file name and line number, that you can use to debug memory problems. The names of the user-defined debug versions are prefixed by _debug_u (for example, _debug_umalloc), and they are defined in umalloc.h.

For a complete list and details about all of the debug memory management functions, see Memory debug library functions.

Table 1. Functions for debugging memory heaps
Default heap function Corresponding user-created heap function
_debug_calloc _debug_ucalloc
_debug_malloc _debug_umalloc
_debug_heapmin _debug_uheapmin
_debug_realloc n/a
_debug_free n/a
To use these debug versions, you can do either of the following:

To compile an application that calls the user-created heap functions, see Compiling and linking a program with user-created heaps.

Notes:
  1. When the -qheapdebug option is specified, code is generated to pre-initialize the local variables for all functions. This makes it much more likely that uninitialized local variables will be found during the normal debug cycle rather than much later (usually when the code is optimized).
  2. Do not use the -brtl option with -qheapdebug.
  3. You should place a #pragma strings (readonly) directive at the top of each source file that will call debug functions, or in a common header file that each includes. This directive is not essential, but it ensures that the file name passed to the debug functions cannot be overwritten, and that only one copy of the file name string is included in the object module.

Additional functions for debugging memory heaps

Three additional debug memory management functions do not have regular counterparts. They are summarized in the following table.

Table 2. Additional functions for debugging memory heaps
Default heap function Corresponding user-created heap function Description
_dump_allocated _udump_allocated Prints information to stderr about each memory block currently allocated by the debug functions.
_dump_allocated_delta _udump_allocated_delta Prints information to file descriptor 2 about each memory block allocated by the debug functions since the last call to _dump_allocated or _dump_allocated_delta.
_heap_check _uheap_check Checks all memory blocks allocated or freed by the debug functions to make sure that no overwriting has occurred outside the bounds of allocated blocks or in a free memory block.

The _heap_check function is automatically called by the debug functions; you can also call this function explicitly. You can then use _dump_allocated or _dump_allocated_delta to display information about currently allocated memory blocks. You must explicitly call these functions.