_heapwalk
Traverses the heap and returns information about the next entry.
int_heapwalk(_HEAPINFO*entryinfo);
| Routine | Required Header | Optional Headers | Compatibility |
| _heapwalk | <malloc.h> | <errno.h> | Win NT |
For additional compatibility information, see Compatibility in the Introduction.
Libraries
| LIBC.LIB | Single thread static library, retail version |
| LIBCMT.LIB | Multithread static library, retail version |
| MSVCRT.LIB | Import library for MSVCRT.DLL, retail version |
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; _HEAPINFO structure contains information about next entry.
In addition, if an error occurs, _heapwalk sets errno to ENOSYS.
Parameter
entryinfo
Buffer to contain heap information
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.
Example
/* HEAPWALK.C: This program "walks" the heap, starting
* at the beginning (_pentry = NULL). It prints out each
* heap entry's use, location, and size. It also prints
* out information about the overall state of the heap as
* soon as _heapwalk returns a value other than _HEAPOK.
*/
#include <stdio.h>
#include <malloc.h>
void heapdump( void );
void main( void )
{
char *buffer;
heapdump();
if( (buffer = malloc( 59 )) != NULL )
{
heapdump();
free( buffer );
}
heapdump();
}
void heapdump( void )
{
_HEAPINFO hinfo;
int heapstatus;
hinfo._pentry = NULL;
while( ( heapstatus = _heapwalk( &hinfo ) ) == _HEAPOK )
{ printf( "%6s block at %Fp of size %4.4X\n",
( hinfo._useflag == _USEDENTRY ? "USED" : "FREE" ),
hinfo._pentry, hinfo._size );
}
switch( heapstatus )
{
case _HEAPEMPTY:
printf( "OK - empty heap\n" );
break;
case _HEAPEND:
printf( "OK - end of heap\n" );
break;
case _HEAPBADPTR:
printf( "ERROR - bad pointer to heap\n" );
break;
case _HEAPBADBEGIN:
printf( "ERROR - bad start of heap\n" );
break;
case _HEAPBADNODE:
printf( "ERROR - bad node in heap\n" );
break;
}
}
Output
USED block at 002C0004 of size 0014
USED block at 002C001C of size 0054
USED block at 002C0074 of size 0024
USED block at 002C009C of size 0010
USED block at 002C00B0 of size 0018
USED block at 002C00CC of size 000C
USED block at 002C00DC of size 001C
USED block at 002C00FC of size 0010
USED block at 002C0110 of size 0014
USED block at 002C0128 of size 0010
USED block at 002C013C of size 0028
USED block at 002C0168 of size 0088
USED block at 002C01F4 of size 001C
USED block at 002C0214 of size 0014
USED block at 002C022C of size 0010
USED block at 002C0240 of size 0014
USED block at 002C0258 of size 0010
USED block at 002C026C of size 000C
USED block at 002C027C of size 0010
USED block at 002C0290 of size 0014
USED block at 002C02A8 of size 0010
USED block at 002C02BC of size 0010
USED block at 002C02D0 of size 1000
FREE block at 002C12D4 of size ED2C
OK - end of heap