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:

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

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


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

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, Win/16, QNX/16, OS/2 1.x(all)
    _fheapwalk - DOS/16, Win/16, QNX/16, OS/2 1.x(all)
    _nheapwalk - DOS, Win, QNX, OS/2 1.x, OS/2 1.x(MT), OS/2 2.x, NT