Click above to get retro games delivered to your door ever month!

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:

    Function     Heap Walked

_heapwalk
    Depends on data model of the program

_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, the _heapwalk function is equivalent to
    the  _nheapwalk function; in a large data memory model, the _heapwalk
    function is equivalent to the  _fheapwalk function.

Returns:
    These functions return one of the following manifest constants which are
    defined in <malloc.h>.

    Constant     Meaning

_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.


Example:
    #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();
      }

    produces the following:

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

    OK - heap is empty
      USED block at 23f8:0ab6 of size 0202
      USED block at 23f8:0cb8 of size 0052
      FREE block at 23f8:0d0a of size 1DA2
    OK - end of heap
      USED block at 23f8:0ab6 of size 0202
      FREE block at 23f8:0cb8 of size 1DF4
    OK - end of heap

    On 32-bit 80386/486 systems, the following output 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

Systems:
     _heapwalk - All

    _bheapwalk - DOS/16, Windows, QNX/16, OS/2 1.x(all)
    _fheapwalk - DOS/16, Windows, QNX/16, OS/2 1.x(all)
    _nheapwalk - DOS, Windows, Win386, Win32, QNX, OS/2 1.x, OS/2 1.x(MT),
    OS/2-32

See Also:
    _heapchk, _heapenable, _heapgrow, _heapmin, _heapset, _heapshrink