_debug_umalloc -- Reserve Memory Blocks from User Heap

Format

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

Language Level: Extension
_debug_umalloc is the debug version of _umalloc. Like _umalloc, it reserves storage space from the heap you specify for a block of size bytes. _debug_umalloc 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_umalloc 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 _udump_allocated or _udump_allocated_delta functions. _debug_umalloc also sets all the memory it allocates to 0xAA; this can help you debug problems where your program uses the data in the memory without initializing it.

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

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

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

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.

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

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

Example
This example creates a heap myheap and uses _debug_umalloc to allocate 100 bytes from it. It then attempts to overwrite storage that was not allocated. The call to _debug_free invokes _uheap_check, which detects the error, generates messages, and ends the program.

Note: You must compile this example with the /Tm option to map _umalloc to _debug_umalloc 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*)_umalloc(myheap, 100))) {
      puts("Cannot allocate memory from user heap.\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 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_umallo.c.
      Heap state was valid at line 14 of _debug_umallo.c.
      Memory error detected at line 19 of _debug_umallo.c.
   ****************************************************************************/
}


Managing Memory with Multiple Heaps
Memory Management


_debug_ucalloc -- Reserve and Initialize Memory from User Heap
_debug_free -- Release Memory
_debug_malloc -- Allocate Memory
malloc -- Reserve Storage Block
_ucreate -- Create a Memory Heap
_udump_allocated -- Get Information about Allocated Memory in Heap
_umalloc -- Reserve Memory Blocks from User Heap
_uheap_check -- Validate User Memory Heap
<umalloc.h>
/Tm compiler option