### _debug_ucalloc -- Reserve and Initialize Memory from User Heap

Format

>     #include <umalloc.h>
>     void *_debug_ucalloc(Heap_t heap, size_t num, size_t size,
>                          const char *file, size_t line);

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

In addition, _debug_ucalloc makes an implicit call to _uheap_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 _uheap_check and _uheap_allocated or _udump_allocated_delta functions.

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

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

_debug_ucalloc works just like _debug_calloc except that you specify the heap to use; _debug_calloc always allocates from the default heap.

If the heap does not have enough memory for the request, _debug_ucalloc calls the getmore_fn that you specified when you created the heap with _ucreate.

To reallocate or free memory allocated with _debug_ucalloc, use the non-heap-specific _debug_realloc and _debug_free. These functions always check what heap the memory was allocated from.

Return Value
_debug_ucalloc returns a pointer to the reserved space. If size or num was specified as zero, or if your getmore_fn cannot provide enough memory, _debug_ucalloc returns NULL. Passing _debug_ucalloc a heap that is not valid results in undefined behavior.

Example
This example creates a user heap and allocates memory from it with _debug_ucalloc. It then attempts to write to memory that was not allocated. When _debug_free is called, _uheap_check detects the error, generates several messages, and stops the program.

Note: You must compile this example with the /Tm option to map the _ucalloc calls to _debug_ucalloc and free to _debug_free.

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

    int main(void)
    {
       Heap_t  myheap;
       char    *ptr;

       /* Use default heap as user heap */
       myheap = _udefault(NULL);

       if (NULL == (ptr = (char*)_ucalloc(myheap, 100, 1))) {
          puts("Cannot allocate memory from user heap.");
          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 0x00073890 was overwritten at 0x000738f4.
          The first eight bytes of the memory block (in hex) are: 7878787878787878.
          This memory block was (re)allocated at line number 14 in _debug_ucallo.c.
          Heap state was valid at line 14 of _debug_ucallo.c.
          Memory error detected at line 19 of _debug_ucallo.c.
       ****************************************************************************/
    }

Managing Memory with Multiple Heaps
Memory Management

calloc -- Reserve and Initialize Storage
_debug_calloc -- Allocate and Initialize Memory
_debug_free -- Release Memory
_debug_umalloc -- Reserve Memory Blocks from User Heap
_ucalloc -- Reserve and Initialize Memory from User Heap
_ucreate -- Create a Memory Heap
_udump_allocated -- Get Information about Allocated Memory in Heap
_uheap_check -- Validate User Memory Heap
<umalloc.h>
/Tm compiler option