_uheap_check -- Validate User Memory Heap

Format

#include <umalloc.h>
void _uheap_check(Heap_t heap);

Language Level: Extension
_uheap_check checks all memory blocks in the heap you specify that have been allocated or freed using the heap-specific debug versions of the memory management functions (_debug_ucalloc, _debug_umalloc, and so on). _uheap_check checks that your program has not overwritten freed memory blocks or memory outside the bounds of allocated blocks.

_uheap_check works just like _heap_check, except that you specify the heap to check; _heap_check always checks the default heap.

When you call a heap-specific debug memory management function (such as _debug_umalloc), it calls _uheap_check automatically. You can also call _uheap_check explicitly. Place calls to _uheap_check throughout your code, especially in areas that you suspect have memory problems.

Calling _uheap_check frequently can increase your program's memory requirements and decrease its execution speed (explicitly or, for OS/2, through the tiled debug memory functions). To reduce the overhead of heap-checking, you can use the  CPP_HEAP_SKIP  environment variable to control how often the functions check the heap. For example:

SET CPP_HEAP_SKIP=10

specifies that every tenth call to any debug memory function (regardless of the type or heap) checks the heap. Explicit calls to _uheap_check are always performed.

To use _uheap_check and the debug versions of the memory management functions, specify the debug memory (/Tm) compiler option.

Note: The /Tm option maps all calls to memory management functions (including heap-specific versions) to their debug counterparts. To prevent a call from being mapped, parenthesize the function name.

Return Value
There is no return value.

Example
This example creates a heap and allocates memory from it. It then calls _uheap_check to check the the memory in the heap.

Note: You must compile this example with the /Tm option to map the _ucalloc calls to _debug_ucalloc.

#include <stdlib.h>
#include <stdio.h>
#include <umalloc.h>
#include <string.h>
int main(void)
{
   Heap_t  myheap;
   char    *ptr;
   /* Use default heap as user heap */
   myheap = _udefault(NULL);
   if (NULL == (ptr = (char*)_ucalloc(myheap, 100, 1))) {
      puts("Cannot allocate memory from user heap.");
      exit(EXIT_FAILURE);
   }
   memset(ptr, 'x', 105);     /* overwrite storage that was not allocated */
   _uheap_check(myheap);
   free(ptr);
   return 0;
   /****************************************************************************
      The output should be similar to :
      End of allocated object 0x00073890 was overwritten at 0x000738f4.
      The first eight bytes of the memory block (in hex) are: 7878787878787878.
      This memory block was (re)allocated at line number 13 in _uheap_check.c.
      Heap state was valid at line 13 of _uheap_check.c.
      Memory error detected at line 19 of _uheap_check.c.
   ****************************************************************************/
}


Managing Memory with Multiple Heaps
Memory Management


_heap_check -- Validate Default Memory Heap
_debug_ucalloc -- Allocate and Initialize Memory from User Heap
_debug_umalloc -- Reserve Memory Blocks from User Heap
_debug_realloc -- Reallocate Memory Block
_debug_free -- Release Memory
_uheapchk -- Validate Memory Heap
_uheapset -- Validate and Set Memory Heap
_uheap_walk -- Return Information about Memory Heap
<umalloc.h>
/Tm compiler option