### Heap Errors

Heap errors can occur when your code inadvertently overwrites control information that the memory management functions use to control heap usage. Each block of allocated storage within a heap consists of a data area, which starts at the address returned by the allocating function, as well as a control area adjacent to the data area, which is needed by the memory management functions to free the storage properly when you deallocate the storage. If you overwrite a control structure in the heap (for example, by writing to elements outside the allocated bounds of an array, or by copying a string into too small a block of allocated storage), the control information is corrupted and may cause incorrect program behavior even if the data areas of other allocated blocks are not overwritten.

You should consider the following points when you are trying to locate heap errors:

Finding heap errors outside the debugger

To detect heap errors, you can compile your program to use the heap-checking versions of memory management functions (use the /Tm option). When you run a program compiled with this option, each call to a memory management function causes a heap check to be performed on the default heap. This heap check involves checking the control structures for each allocated block of storage within the heap, and ensuring that none were overwritten. If an error is encountered, the program terminates and information is written to standard error including the address where heap corruption occurred, the source file and line number at which a valid heap state was last detected, and the source file and line number at which the memory error was detected.

Heap checking for default and other heaps

Heap checking is only enabled for the default heap used by each executable. If the debug versions of the memory management functions do not report heap corruption and you still suspect a problem, you may be using additional heaps and corrupting them. You can debug usage of nondefault heaps by adding calls to the _uheapchk C Library function to your source code. See your compiler documentation for more information.

Pinpointing heap errors within the debugger

You can pinpoint the cause of a heap error from within the debugger, provided the heap causing the error is known to be the default heap, by continually narrowing down the gap between the last line at which the heap was valid, and the first line at which corruption occurred. From within the Source window, use a combination of run commands, step commands, line and function breakpoints, and the Check heap when stopping setting on the Run menu, to narrow the scope of your search.

Check heap when stopping may expose other coding errors

For semantically incorrect programs, Check heap when stopping is intrusive in that it may cause different results where a program is incorrectly accessing data on the stack. This is because Check heap when stopping causes the process and thread being debugged to call a heap check function each time execution stops, and this heap check function affects the safe area of the stack by overwriting part of that area with its stack frame. For example, if a called function returns the address of a local variable, that local variable's contents will be accessible from the calling function, and will not change, as long as the stack frame used by the called function is not overwritten by a subsequent call. However, if you issue a Step return command from the called function while Check heap when stopping is enabled, the heap checking function is called immediately on return from the called function, and the storage pointed to by the returned pointer may overwritten by the stack frame of the heap checking function.

Check heap when stopping affects performance

Heap checking within the debugger has a high overhead cost for step commands, because the heap is checked after each step. If you are stepping through large sections of code, or frequently stopping at breakpoints, and you find debug performance too slow, try turning on Check heap when stopping only in those areas you suspect are causing heap errors.

Notes on Check Heap when Stopping

- For the Check heap when stopping choice to work, you have to compile your application using the IBM C and C++ /Tm+compiler option.
- If you enable the Check heap when stopping choice and run your application to termination, and the application contains a heap error, the heap check is not made. To check the heap just before termination, set a breakpoint on the last line of your application.
- (OS/2 only): If you are debugging a multiple thread program and a thread stops while running in compiler memory management code that is holding a memory semaphore, the heap check will not be performed.
- (OS/2 only): If the stopping thread is running in 16-bit code, the heap check will not be performed.

Debug Heap Use