### _debug_tmalloc -- Reserve Tiled Memory (OS/2)

Format

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

Language Level: Extension
_debug_tmalloc is the debug version of _tmalloc. Like _tmalloc, it allocates tiled memory from the tiled runtime heap for an object of length size bytes. _debug_tmalloc also sets all the memory it allocates to `0xAA`, so you can easily locate instances where your program uses the data in the memory without initializing it first.

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

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

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_tmalloc works just like _debug_malloc except that it allocates 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. You can also create your own heaps of tiled memory.

To reallocate or free memory allocated with _debug_tmalloc, use _debug_trealloc, and _debug_tfree; you can also use _trealloc and _tfree if you don't want debug information about the operation.

Return Value
_debug_tmalloc returns a pointer to the reserved space. If size was specified as zero, _debug_tmalloc returns NULL.

Example
This example allocates 100 bytes of memory, then tries to write to memory that was not allocated. The call to _debug_tfree 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 free calls to _debug_tfree.

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

    int main(void)
    {
       char *ptr;

       /* malloc is mapped to _debug_tmalloc */
       if (NULL == (ptr = (char*)malloc(100))) {
          puts("Could not allocate memory block.\n");
          exit(EXIT_FAILURE);
       }
       memset (ptr, 'x', 105);  /* Overwrites storage that was not allocated */
       free(ptr);
       return 0;

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

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

Managing Memory with Multiple Heaps
Memory Management

_debug_malloc -- Allocate Memory
_debug_tfree -- Release Tiled Memory
_debug_trealloc -- Reallocate Tiled Memory Block
malloc -- Reserve Storage Block
_tdump_allocated -- Get Information about Allocated Tiled Memory
_tdump_allocated_delta -- Get Information about Allocated Tiled Memory
_theap_check -- Validate User Memory Heap
<malloc.h>
<stdlib.h>
/Tm compiler option
/Gt compiler option