Traverse the heap and return information about the next entry.
include <malloc.h>
int _heapwalk( _HEAPINFO *entryinfo );
int _bheapwalk( __segment seg, _HEAPINFO *entryinfo );
int _fheapwalk( _HEAPINFO *entryinfo );
int _nheapwalk(_HEAPINFO*entryinfo);
| entryinfo | Buffer to contain heap information | |
| seg | Based-heap segment selector |
The _heapwalk family of routines helps debug heap-related problems in programs.
The _heapwalk routines walk through the heap, traversing one entry per call, and return 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:
| Element | Description |
| int far *_pentry | Heap entry pointer |
| size_t _size | Size of heap entry |
| int _useflag | Entry “in use” flag |
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 the _heapwalk routine a pointer to a _HEAPINFO structure whose _pentry member is NULL.
The various _heapwalk functions walk through and gather information on these heaps:
| Function | Heap Walked |
| _heapwalk | Depends on data model of program. |
| _bheapwalk | Based heap specified by seg value; _NULLSEG specifies all based heaps. |
| _fheapwalk | Far heap (outside default data segment). |
| _nheapwalk | Near heap (inside default data segment). |
In large data models (that is, compact-, large-, and huge-model programs), _heapwalk maps to _fheapwalk. In small data models (tiny-, small-, and medium-model programs), _heapwalk maps to _nheapwalk.
For _heapwalk, if the seg value is _NULLSEG, all based heap segments will be traversed; otherwise, only the specified based heap is walked.
All three routines return one of the following manifest constants (defined in MALLOC.H):
| Constant | Meaning |
| _HEAPBADBEGIN | The initial header information cannot be found, or it is invalid. |
| _HEAPBADNODE | A bad node has been found, or the heap is damaged. |
| _HEAPBADPTR | The _pentry field of the _HEAPINFO structure does not contain a valid pointer into the heap. |
| _HEAPEND | The end of the heap has been reached successfully. |
| _HEAPEMPTY | The heap has not been initialized. |
| _HEAPOK | No errors so far; the _HEAPINFO structure contains information about the next entry. |
_heapwalk
Standards:None
16-Bit:DOS
32-Bit:DOS32X
_bheapwalk, _fheapwalk
Standards:None
16-Bit:DOS, QWIN, WIN, WIN DLL
32-Bit:None
_nheapwalk
Standards:None
16-Bit:DOS
32-Bit:None
_heapchk functions, _heapset functions
/* 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;
}
}
USED block at 0067:103E of size 000E
USED block at 0067:104E of size 01F4
USED block at 0067:1244 of size 0026
USED block at 0067:126C of size 0200
FREE block at 0067:146E of size 0B90
OK - end of heap
USED block at 0067:103E of size 000E
USED block at 0067:104E of size 01F4
USED block at 0067:1244 of size 0026
USED block at 0067:126C of size 0200
USED block at 0067:146E of size 003C
FREE block at 0067:14AC of size 0B52
OK - end of heap
USED block at 0067:103E of size 000E
USED block at 0067:104E of size 01F4
USED block at 0067:1244 of size 0026
USED block at 0067:126C of size 0200
FREE block at 0067:146E of size 003C
FREE block at 0067:14AC of size 0B52
OK - end of heap