### _debug_tcalloc -- Reserve and Initialize Tiled Memory (OS/2)

Format

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

Language Level: Extension
_debug_tcalloc is the debug version of _tcalloc. Like _tcalloc, it allocates tiled memory from the tiled runtime heap for an array of num elements, each of length size bytes. It then initializes all bits of each element to 0.

In addition, _debug_tcalloc 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_tcalloc, you must compile with the debug memory (/Tm) and tiled memory (/Gt) compiler options. These options map all calloc calls to _debug_tcalloc.

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.

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

_debug_tcalloc works just like _debug_calloc 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.

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

Example
This example reserves 100 bytes of tiled memory. It then attempts to write to storage that was not allocated. The second _debug_tcalloc call invokes _theap_check, which detects the error, generates several messages, and stops the program.

Note: You must compile this program with the /Tm /Gt options to map the calloc calls to _debug_tcalloc.

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

    int main(void)
    {
       char *ptr;

       /* calloc is mapped to _debug_tcalloc */
       if (NULL == (ptr = (char*)calloc(1, 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_tcallo.c.
          Heap state was valid at line 10 of _debug_tcallo.c.
          Memory error detected at line 15 of _debug_tcallo.c.
       ****************************************************************************/
    }

Managing Memory with Multiple Heaps
Memory Management

calloc -- Reserve and Initialize Storage
_debug_calloc -- Allocate and Initialize Memory
_debug_tfree -- Release Tiled Memory
_debug_tmalloc -- Reserve Tiled Memory
_debug_trealloc -- Reallocate Tiled Memory 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