_theap_check -- Validate User Memory Heap (OS/2)

Format

#include <stdlib.h>  /* also in <malloc.h> */
void _theap_check(void);

Language Level: Extension
_theap_check checks all tiled memory blocks in the tiled runtime heap that have been allocated or freed using the tiled debug memory management functions (_debug_tcalloc, _debug_tmalloc, and so on). _theap_check checks that your program has not overwritten tiled memory that has been freed or that is outside the bounds of allocated tiled memory blocks.

_theap_check works just like _heap_check except that it checks tiled memory instead of regular memory.

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

Calling _theap_check frequently (explicitly or through the tiled debug memory functions) can increase your program's memory requirements and decrease its execution speed. 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:

 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 _theap_check are always performed.

To use _theap_check and the tiled debug versions of the memory management functions, specify the debug memory (/Tm) and tiled memory (/Gt) compiler options.

Note: The /Tm /Gt options map all calls to regular memory management functions to their tiled debug versions. To prevent a call from being mapped, parenthesize the function name.

Return Value
There is no return value.

Example
This example allocates and frees memory from the tiled runtime heap, and then calls _theap_check to check the heap.

Note: You must compile this example with the /Tm /Gt options to map the memory management functions to their tiled debug versions.

#include <stdlib.h>
#include <stdio.h>
int main(void)
{
   char *ptr;
   if (NULL == (ptr = (char*)malloc(10))) {
      puts("Could not allocate memory block.\n");
      exit(EXIT_FAILURE);
   }
   *(ptr - 1) = 'x';      /* overwrites storage that was not allocated */
   _theap_check();
   free(ptr);
   return 0;
   /****************************************************************************
      The output should be similar to :
      Header information of object 0x00080120 was overwritten at 0x0008011c.
      The first eight bytes of the memory block (in hex) are: AAAAAAAAAAAAAAAA.
      This memory block was (re)allocated at line number 8 in _theap_chec.c.
      Heap state was valid at line 8 of _theap_check.c.
   ****************************************************************************/
}


Managing Memory with Multiple Heaps
Memory Management


_heap_check -- Validate Default Memory Heap
_debug_tcalloc -- Reserve and Initialize Tiled Memory
_debug_tfree -- Release Tiled Memory
_debug_theapmin -- Release Unused Memory
_debug_tmalloc -- Reserve Tiled Memory
_debug_trealloc -- Reallocate Tiled Memory
_dump_allocated -- Get Information about Allocated Memory
<malloc.h>
<stdlib.h>
/Tm compiler option
/Gt compiler option