_heapwalk

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

重要

這個 API 除了偵錯組建之外，不能用於在 Windows 執行階段中執行的應用程式。 如需詳細資訊，請參閱 CRT functions not supported in Universal Windows Platform apps (通用 Windows 平台應用程式中不支援的 CRT 函式)。

語法

int _heapwalk( _HEAPINFO *entryinfo );

參數

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

傳回值

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

傳回值	意義
_HEAPBADBEGIN	找不到初始標頭資訊或其無效。
_HEAPBADNODE	堆積已損毀或找到故障的節點。
_HEAPBADPTR	結構的 _pentry 欄位 _HEAPINFO 不包含堆積的有效指標，或 entryinfo 為 Null 指標。
_HEAPEND	已成功達到堆積的結尾。
_HEAPEMPTY	堆積未初始化。
_HEAPOK	到目前為止，沒有錯誤；已使用下一個堆積項目的相關資訊更新 entryinfo。

此外若是發生錯誤， _heapwalk 會將 errno 設為 ENOSYS。

備註

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

欄位	意義
int *_pentry	堆積項目指標。
size_t _size	堆積項目大小。
int _useflag	表示堆積項目是否為使用中的旗標。

呼叫 _heapwalk 並傳回 _HEAPOK 時，項目大小會被儲存在 _size 欄位，並將 _useflag 欄位設定為 _FREEENTRY 或 _USEDENTRY 其中之一 (兩者都是 Malloc.h 中定義的常數)。 若要取得此堆積中第一個項目的資訊，請將 _heapwalk 指標傳遞至 _pentry 成員為 NULL 的_HEAPINFO 結構。 如果作業系統不支援 _heapwalk，函式會傳 _HEAPEND 回 並設定 errno 為 ENOSYS。

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

需求

常式	必要的標頭	選擇性標頭
_heapwalk	<malloc.h>	<errno.h>

如需相容性詳細資訊，請參閱相容性。

範例

// 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("%8s 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;
    }
}

    USED block at 00310650 of size 0100
    USED block at 00310758 of size 0800
    USED block at 00310F60 of size 0080
    FREE block at 00310FF0 of size 0398
    USED block at 00311390 of size 000D
    USED block at 003113A8 of size 00B4
    USED block at 00311468 of size 0034
    USED block at 003114A8 of size 0039
...
    USED block at 00312228 of size 0010
    USED block at 00312240 of size 1000
    FREE block at 00313250 of size 1DB0
OK - end of heap

另請參閱

記憶體配置
_heapadd
_heapchk
_heapmin
_heapset