### _debug_trealloc -- Reallocate Tiled Memory Block (OS/2)

Format

>     #include <stdlib.h>   /* also in <malloc.h> */
>     void *_debug_trealloc(void *ptr, size_t size,
>                          const char *file, size_t line);

Language Level: Extension
The _debug_trealloc function is the debug version of _trealloc. Like _trealloc, it reallocates the block of tiled memory pointed to by ptr to a new size, specified in bytes. The block of memory must have been allocated using a tiled memory management function. _debug_trealloc also sets any new memory it allocates to 0xAA, so you can easily locate instances where your program tries to use the data in memory without initializing it first.

In addition, _debug_trealloc makes an implicit call to _theap_check, and stores the file name file and the line number line where the storage is reallocated. This information can be used later by the _theap_check and _tdump_allocated or _tdump_allocated_delta functions.

If ptr is NULL, _debug_trealloc behaves like _debug_tmalloc (or malloc) and allocates the block of memory.

To use _debug_trealloc, you must compile with the debug memory (/Tm) and tiled memory (/Gt) compiler options. These options map all realloc calls to _debug_trealloc.

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.

_debug_trealloc works just like _debug_realloc except that it reallocates tiled memory instead of regular memory. If you have objects that may be accessed by 16-bit code, you should store them in tiled memory. Tiled memory is guaranteed not to cross 64K boundaries, as long as the object is less than 64K in size. Objects larger than 64K in size are aligned on 64K boundaries, but will also cross 64K boundaries. Tiled memory from the IBM C and C++ Compilers runtime heap is limited to 512 MB per process. You can also create your own heaps of tiled memory, which can be larger in size.

Return Value
_debug_trealloc returns a pointer to the reallocated memory block. The ptr argument to _debug_trealloc is not necessarily the same as the return value, because the _debug_trealloc might change the memory location.

If size is 0, _debug_trealloc returns NULL. If not enough memory is available to expand the block to the given size, the original block is unchanged and NULL is returned.

Example
This example uses _debug_tmalloc to allocate 5 bytes of storage, then attempts to write to storage that was not allocated. The call to _debug_trealloc invokes _theap_check, which detects the error, generates several messages, and stops the program.

Note: You must compile this example with the /Tm /Gt options to map the realloc calls to _debug_trealloc.

    #include <stdlib.h>
    #include <stdio.h>
    #include <string.h>

    int main(void)
    {
       char *ptr;

       if (NULL == (ptr = (char*)malloc(5))) {
          puts("Could not allocate memory block.\n");
          exit(EXIT_FAILURE);
       }
       memset (ptr, 'x', 7);  /* Overwrites storage that was not allocated */

       /* realloc is mapped to _debug_trealloc */
       if (NULL == (ptr = (char*)realloc(ptr, 10))) {
          puts("Could not allocate memory block.\n");
          exit(EXIT_FAILURE);
       }
       free(ptr);
       return 0;

       /****************************************************************************
          The output should be similar to :

          End of allocated object 0x00080120 was overwritten at 0x00080125.
          The first eight bytes of the memory block (in hex) are: 78787878787878DD.
          This memory block was (re)allocated at line number 8 in _debug_treallo.c.
          Heap state was valid at line 8 of _debug_treallo.c.
          Memory error detected at line 15 of _debug_treallo.c.
       ****************************************************************************/
    }

Managing Memory with Multiple Heaps
Memory Management

_debug_realloc -- Reallocate Memory Block
_debug_tcalloc -- Reserve and Initialize Tiled Memory
_debug_tmalloc -- Reserve Tiled Memory
_debug_tfree -- Release Tiled Memory
_debug_theapmin -- Release Unused Tiled Memory
_tdump_allocated -- Get Information about Allocated Tiled Memory
_tdump_allocated_delta -- Get Information about Allocated Tiled Memory
_theap_check -- Validate User Memory Heap
_trealloc -- Reallocate Tiled Storage Block
<malloc.h>
<stdlib.h>
/Tm compiler option
/Gt compiler option