### _debug_calloc -- Allocate and Initialize Memory

Format

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

Language Level: Extension
_debug_calloc is the debug version of calloc. Like calloc, it allocates memory from the default 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_calloc makes an implicit call to _heap_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 _heap_check and _dump_allocated or _dump_allocated_delta functions.

To use _debug_calloc, you must compile with the debug memory (/Tm) compiler option. This option maps all calloc calls to _debug_calloc.

Note: The /Tm option maps all calls to memory management functions (including a heap-specific version and a tiled version for OS/2) to their debug counterparts. To prevent a call from being mapped, parenthesize the function name.

To reallocate or free memory allocated by _debug_calloc, use _debug_realloc and _debug_free; you can also use realloc and free if you do not want debug information about the operation.

A heap-specific version (_debug_ucalloc), and a tiled version of this function are available for OS/2 (_debug_tcalloc). _debug_calloc always allocates memory from the default heap.

Return Value
_debug_calloc returns a pointer to the reserved space. If not enough memory is available, or if num or size is 0, _debug_calloc returns NULL.

Example
This example reserves storage of 100 bytes. It then attempts to write to storage that was not allocated. When _debug_calloc is called again, _heap_check detects the error, generates several messages, and stops the program.

Note: You must compile this example with the /Tm option to map the calloc calls to _debug_calloc.

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

    int main(void)
    {
       char *ptr1, *ptr2;

       if (NULL == (ptr1 = (char*)calloc(1, 100))) {
          puts("Could not allocate memory block.");
          exit(EXIT_FAILURE);
       }
       memset(ptr1, 'a', 105);         /* overwrites storage that was not allocated */
       ptr2 = (char*)calloc(2, 20);      /* this call to calloc invokes _heap_check */
       puts("_debug_calloc did not detect that a memory block was overwritten.");
       return 0;

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

          End of allocated object 0x00073890 was overwritten at 0x000738f4.
          The first eight bytes of the memory block (in hex) are: 6161616161616161.
          This memory block was (re)allocated at line number 9 in _debug_callo.c.
          Heap state was valid at line 9 of _debug_callo.c.
          Memory error detected at line 14 of _debug_callo.c.
       ****************************************************************************/
    }

Managing Memory with Multiple Heaps
Memory Management

calloc -- Reserve and Initialize Storage
_debug_ucalloc -- Reserve and Initialize Memory from User Heap
_debug_free -- Release Memory
_debug_malloc -- Allocate Memory
_debug_realloc -- Reallocate Memory Block
_dump_allocated -- Get Information about Allocated Memory
_dump_allocated_delta -- Get Information about Allocated Memory
_heap_check -- Validate Default Memory Heap
<malloc.h>
<stdlib.h>
/Tm compiler option