### Differentiating between Memory Management Functions

The memory management functions defined by ANSI are calloc, malloc, realloc, and free. These regular functions allocate and free memory from the default runtime heap. (IBM C and C++ Compilers has added the function, _heapmin, to return unused memory to the system.) IBM C and C++ Compilers also provides different versions of each of these functions as extensions to the ANSI definition.

All the versions actually work the same way; they differ only in what heap they allocate from, and in whether they save information to help you debug memory problems. The memory allocated by all of these functions is suitably aligned for storing any type of object.

The following table summarizes the different versions of memory managment functions, using malloc as an example of how the names of the functions change for each version. They are all described in greater detail after the table.

| Regular Version | Debug Version
Default Heap | malloc | _debug_malloc
User Heap | _umalloc | _debug_umalloc

To use these extensions, you must set the language level to extended, either with the lang(level, extended) compiler option, or the #pragma langlvl(extended) directive.

Heap-Specific Functions
Use the heap-specific versions to allocate and free memory from a user-created heap that you specify. (You can also explicity use the runtime heap, if you want.) Their names are prefixed by _u (for "user heaps"), for example, _umalloc, and they are defined in <umalloc.h>.

The functions provided are:

- _ucalloc
- _umalloc
- _uheapmin

Notice that no heap-specific version exists for realloc or free. Because they both always check what heap the memory was allocated from, you can always use the regular versions, regardless of what heap the memory came from.

Debug Functions
Use these functions to allocate and free memory from the default runtime heap, just as you would use the regular versions. They also provide information that you can use to debug memory problems.

Note: The information provided by these functions is Diagnosis, Modification, and Tuning information only. It is not intended to be used as a programming interface.

When you use the debug memory compiler option, /Tm, all calls to the regular memory management functions are mapped to their debug versions. You can also call the debug versions explicitly.

Note: If you parenthesize the calls to the regular memory management functions, they are not mapped to their debug versions.

We recommend that you place a #pragma strings(readonly) directive at the top of each source file that will call debug functions, or in a common header file that each includes. This directive is not essential, but it ensures that the file name passed to the debug functions cannot be overwritten, and that only one copy of the file name string is included in the object module.

The names of the debug versions are prefixed by _debug_, for example, _debug_malloc, and they are defined in <malloc.h> and <stdlib.h>.

The functions provided are:

- _debug_calloc
- _debug_free
- _debug_heapmin
- _debug_malloc
- _debug_realloc

In addition to their usual behavior, these functions also store information (file name and line number) about each call made to them. Each call also automatically checks the heap by calling _heap_check (described below).

Three additional debug memory management functions do not have regular counterparts:

- _dump_allocated
  Prints information to file standard error handle (the usual destination of stderr) about each memory block currently allocated by the debug functions. You can change the destination of the information with the _set_crt_msg_handle function.
- _dump_allocated_delta
  Prints information to file standard error handle about each memory block allocated by the debug functions since the last call to _dump_allocated or _dump_allocated_delta. Again, you can change the destination of the information with the _set_crt_msg_handle function.
- _heap_check
  Checks all memory blocks allocated or freed by the debug functions to make sure that no overwriting has occurred outside the bounds of allocated blocks or in a free memory block.

The debug functions call _heap_check automatically; you can also call it explicitly. To use _dump_allocated and _dump_allocated_delta, you must call them explicitly.

Heap-Specific Debug Functions
The heap-specific functions also have debug versions that work just like the regular debug versions. Use these functions to allocate and free memory from the user-created heap you specify, and also provide information that you can use to debug memory problems in your heaps.

Note: The information provided by these functions is Diagnosis, Modification, and Tuning information only. It is not intended to be used as a programming interface.

You can call them explicitly, or you can use the debug memory compiler option, /Tm, to map calls to the heap-specific functions to their debug counterparts.

Note: If you parenthesize the calls to the heap-specific memory management functions, they are not mapped to their debug versions.

The names of the heap-specific debug versions are prefixed by _debug_u, for example, _debug_umalloc, and they are defined in <umalloc.h>.

The functions provided are:

- _debug_ucalloc
- _debug_uheapmin
- _debug_umalloc
- _udump_allocated
- _udump_allocated_delta
- _uheap_check

Notice that no heap-specific debug version exists for realloc or free. Because they both always check what heap the memory was allocated from, you always use the regular debug verions (_debug_realloc and _debug_free), regardless of what heap the memory came from.

Alphabetical Listing of IBM C and C++ Compilers Functions and Macros