_heapwalk(), _bheapwalk(), _fheapwalk(), _nheapwalk()

walk through a heap, gathering debugging information

Synopsis:

#include <malloc.h>
int  _heapwalk( struct _heapinfo *entry );
int _bheapwalk( __segment seg, 
                struct _heapinfo *entry );
int _fheapwalk( struct _heapinfo *entry );
int _nheapwalk( struct _heapinfo *entry );

struct _heapinfo {
  void __far *_pentry; /* heap pointer */
  size_t      _size;    /* heap entry size */
  int         _useflag; /* heap entry 
                          in-use flag */
};

#define _USEDENTRY    0
#define _FREEENTRY    1

Description:

The _heapwalk() functions, along with _heapchk() and _heapset() are provided for debugging heap-related problems in programs.

The _heapwalk() functions walk through the heap, one entry per call, updating the _heapinfo structure with information on the next heap entry. The structure is defined in <malloc.h>. You must initialize the _pentry field with NULL to start the walk through the heap.

Each function walks a particular heap, as listed below:

_heapwalk(): Depends on data model of the program (see below)
_bheapwalk(): Based heap specified by seg value; _NULLSEG specifies all based heaps
_fheapwalk(): Far heap (outside the default data segment)
_nheapwalk(): Near heap (inside the default data segment)

In a small data memory model, _heapwalk() is equivalent to _nheapwalk(); in a large data memory model, _heapwalk() is equivalent to _fheapwalk().

Returns:

One of the following manifest constants, which are defined in <malloc.h>:

_HEAPOK: The heap is OK so far, and the _heapinfo structure contains information about the next entry in the heap.
_HEAPEMPTY: The heap is empty.
_HEAPBADPTR: The _pentry field of the entry structure does not contain a valid pointer into the heap.
_HEAPBADBEGIN: The header information for the heap was not found, or has been damaged.
_HEAPBADNODE: The heap contains a bad node, or is damaged.
_HEAPEND: The end of the heap was reached successfully.

Examples:

#include <stdio.h>
#include <malloc.h>

heap_dump()
  {
    struct _heapinfo h_info;
    int heap_status;

    h_info._pentry = NULL;
    for(;;) {
      heap_status = _heapwalk( &h_info );
      if( heap_status != _HEAPOK ) break;
      printf( "  %s block at %Fp of size %4.4X\n",
        (h_info._useflag == _USEDENTRY ? "USED" : "FREE"),
        h_info._pentry, h_info._size );
    }

    switch( heap_status ) {
      case _HEAPEND:
        printf( "OK - end of heap\n" );
        break;
      case _HEAPEMPTY:
        printf( "OK - heap is empty\n" );
        break;
      case _HEAPBADBEGIN:
        printf( "ERROR - heap is damaged\n" );
        break;
      case _HEAPBADPTR:
        printf( "ERROR - bad pointer to heap\n" );
        break;
      case _HEAPBADNODE:
        printf( "ERROR - bad node in heap\n" );
    }
  }

void main()
  {
    char *p;
    heap_dump();   p = (char *) malloc( 80 );
    heap_dump();   free( p );
    heap_dump();
  }

On 16-bit 80x86 systems, output like the following is produced:

  USED block at 000c:0c06 of size 0008
  USED block at 000c:0c0e of size 0022
  USED block at 000c:0c30 of size 0402
  FREE block at 000c:1032 of size 1BCC
OK - end of heap
  USED block at 000c:0c06 of size 0008
  USED block at 000c:0c0e of size 0022
  USED block at 000c:0c30 of size 0402
  USED block at 000c:1032 of size 0052
  FREE block at 000c:1084 of size 1B7A
OK - end of heap
  USED block at 000c:0c06 of size 0008
  USED block at 000c:0c0e of size 0022
  USED block at 000c:0c30 of size 0402
  FREE block at 000c:1032 of size 1BCC
OK - end of heap

On 32-bit 80386/486 systems, output like the following is produced:

OK - heap is empty
  USED block at 0014:00002a7c of size 0204
  USED block at 0014:00002c80 of size 0054
  FREE block at 0014:00002cd4 of size 1D98
OK - end of heap
  USED block at 0014:00002a7c of size 0204
  FREE block at 0014:00002c80 of size 1DEC
OK - end of heap

Classification:

WATCOM

Safety:
Interrupt handler	No
Signal handler	No
Thread	Yes