### _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