Parameter

Return Value

_heapwalk returns one of the following integer manifest constants defined in MALLOC.H:

_HEAPBADBEGIN

Initial header information invalid or not found.

_HEAPBADNODE

Heap damaged or bad node found.

_HEAPBADPTR

_pentry field of _HEAPINFO structure does not contain valid pointer into heap.

_HEAPEND

End of heap reached successfully.

_HEAPEMPTY

Heap not initialized.

_HEAPOK

No errors so far; entryinfo is updated with information about the next heap entry.

In addition, if an error occurs, _heapwalk sets errno to ENOSYS.

Remarks

The _heapwalk function helps debug heap-related problems in programs. The function walks through the heap, traversing one entry per call, and returns a pointer to a structure of type _HEAPINFO that contains information about the next heap entry. The _HEAPINFO type, defined in MALLOC.H, contains the following elements:

int *_pentry

Heap entry pointer.

size_t _size

Size of heap entry.

int _useflag

Flag that indicates whether heap entry is in use.

A call to _heapwalk that returns _HEAPOK stores the size of the entry in the _size field and sets the _useflag field to either _FREEENTRY or _USEDENTRY (both are constants defined in MALLOC.H). To obtain this information about the first entry in the heap, pass _heapwalk a pointer to a _HEAPINFO structure whose _pentry member is NULL.

Note Beginning with Visual C++ version 4.0, the underlying heap structure was moved to the C run-time libraries to support the new debugging features. As a result, the only Win32 platform that is supported by _heapwalk is Windows NT. When it is called by any other Win32 platform, _heapwalk returns _HEAPEND and sets errno to ENOSYS.

Requirements

Routine

Required header

Optional headers

Compatibility

_heapwalk

<malloc.h>

<errno.h>

Win NT, Win 2000, Win XP

For additional compatibility information, see Compatibility in the Introduction.

Sample Output

USED block at 00310650 of size 0100
USED block at 00310758 of size 0800
USED block at 00310F60 of size 0080
FREE block at 00310FF0 of size 0398
USED block at 00311390 of size 000D
USED block at 003113A8 of size 00B4
USED block at 00311468 of size 0034
USED block at 003114A8 of size 0039
...
USED block at 00312228 of size 0010
USED block at 00312240 of size 1000
FREE block at 00313250 of size 1DB0
OK - end of heap