_heapwalk

發行項
03/27/2013

周遊堆積並傳回用於下一個項目的相關資訊。

重要事項
這個應用程式開發介面無法在 Windows 執行階段執行的應用程式，但在偵錯組建。如需詳細資訊，請參閱 CRT 函式不支援使用 /ZW。

int _heapwalk( 
   _HEAPINFO *entryinfo 
);

參數

entryinfo
包含堆積資訊的緩衝區。

傳回值

下列整數資訊清單常數的_heapwalk 傳回在 Malloc.h 定義的。

_HEAPBADBEGIN
初始標頭資訊無效或找不到。
_HEAPBADNODE
堆積損毀的或找到的錯誤節點。
_HEAPBADPTR
_HEAPINFO 結構的_pentry 欄位未包含有效的指標輸入堆積或 entryinfo 為 null 指標。
_HEAPEND
已成功到達的堆積的結尾。
_HEAPEMPTY
無法初始化堆積。
_HEAPOK
到目前為止沒有錯誤; entryinfo 更新以及下堆積輸入的資訊。

此外，如果發生錯誤，則為 _heapwalk ，將 errno 設為 ENOSYS。

備註

_heapwalk 函式可協助偵錯中程式的堆積相關的問題。函式透過堆積查核，周遊呼叫每一個項目，並將指標傳回包含下堆積輸入的資訊型別 _HEAPINFO 的結構。_HEAPINFO 型別，定義在 Malloc.h，包含下列項目。

int *_pentry
堆積輸入指標。
size_t _size
堆積之輸入的大小。
int _useflag
旗標表示堆積輸入是否正在使用中。

在 _size 中傳回 _HEAPOK 存放區之輸入的大小並將 _useflag 欄位設為 _FREEENTRY 或 _USEDENTRY (對 _heapwalk 的呼叫都是在 Malloc.h 定義的常數)。取得與第一個項目的這個資訊在堆積，傳遞 _heapwalk 指標到 _pentry 成員為 NULL的 _HEAPINFO 結構。如果作業系統不支援 _heapwalk(例如， Windows 98)，則函式會傳回 _HEAPEND 和 errno 設為 ENOSYS。

這個函式會驗證其參數。如果 entryinfo 為 null 指標，無效的參數叫用處理常式，如參數驗證中所述。如果允許繼續執行， errno 會被設置為 EINVAL 且 _HEAPBADPTR 會回傳零。

需求

程序	必要的標頭檔	選擇性標頭
_heapwalk	<malloc.h>	<errno.h>

如需更多關於相容性的資訊，請參閱入門介紹中的相容性 (Compatibility) 。

範例

// crt_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
// or if the loop has iterated 100 times.

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

void heapdump(void);

int main(void)
{
    char *buffer;

    heapdump();
    if((buffer = (char *)malloc(59)) != NULL)
    {
        heapdump();
        free(buffer);
    }
    heapdump();
}

void heapdump(void)
{
    _HEAPINFO hinfo;
    int heapstatus;
    int numLoops;
    hinfo._pentry = NULL;
    numLoops = 0;
    while((heapstatus = _heapwalk(&hinfo)) == _HEAPOK &&
          numLoops < 100)
    {
        printf("%6s block at %Fp of size %4.4X\n",
               (hinfo._useflag == _USEDENTRY ? "USED" : "FREE"),
               hinfo._pentry, hinfo._size);
        numLoops++;
    }

    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;
    }
}