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 includes another function, _heapmin, to return unused memory to the system. IBM C and C++ Compilersalso provides enhanced versions of memory management functions that can help you improve program performance (link to the libhm.a library), work with user heaps, or debug your programs.

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 table below summarizes the different versions of memory management functions, using malloc as an example of how the names of the functions change for each version.

Heap-Specific Functions
Use heap-specific versions of memory allocation functions to allocate and free memory from user-created heaps that you specify. If you want, you can also explicitly specify the runtime heap. The names of user-created heaps are prefixed by _u (for "user heaps"), for example, _umalloc, and they are defined in <umalloc.h>.

When working with user-created heaps, you need to link to the libhu.a library. Heap-specific functions provided in this library are:

• _ucalloc
• _umalloc
• _uheapmin

There are no heap-specific versions of realloc or free. These standard functions always determine which heap memory is allocated from, and can be used with both user-created and runtime memory heaps.

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.

Use the -qheapdebug compiler option to automatically map all calls to the regular memory management functions 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.

You should 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 can't 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

The debug_malloc, debug_realloc, and debug_free functions set the memory areas they affect to a specific, repeating fill pattern. See Debugging Memory Heaps for more information.

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 stderr about each memory block currently allocated by the debug functions.

• _dump_allocated_delta

  Prints information to file handle 2 about each memory block allocated by the debug functions since the last call to _dump_allocated or _dump_allocated_delta.

• _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; and you can also call this function explicitly. The _dump_allocated and _dump_allocated_delta functions must be explicitly called.

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 own heaps.

Use the -qheapdebug compiler option to automatically map all calls to the regular memory management functions 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.

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

The debug_umalloc function sets the memory areas they affect to a specific, repeating fill pattern. See Debugging Memory Heaps for more information.

There are no heap-specific debug versions of _debug_realloc or _debug_free. These functions always determine which heap memory is allocated from, and can be used with both user-created and runtime memory heaps.

Managing Memory with Multiple Memory Heaps
Types of Memory
Debugging Memory Heaps

Creating and Using a Fixed Size Heap
Creating and Using an Expandable Heap
Debugging Problems with Heap Memory
Changing the Default Heap Used in a Program
Example of Creating and Using a User Heap
Example of Creating and Using a Shared-Memory User Heap