heapWalk 函数 (heapapi.h)

项目
08/24/2023

枚举指定堆中的内存块。

语法

BOOL HeapWalk(
  [in]      HANDLE               hHeap,
  [in, out] LPPROCESS_HEAP_ENTRY lpEntry
);

parameters

[in] hHeap

堆的句柄。此句柄由 HeapCreate 或 GetProcessHeap 函数返回。

[in, out] lpEntry

指向 PROCESS_HEAP_ENTRY 结构的指针，该结构维护特定堆枚举的状态信息。

如果 HeapWalk 函数成功并返回值 TRUE，则此结构的成员包含有关堆中下一个内存块的信息。

若要启动堆枚举，请将 PROCESS_HEAP_ENTRY 结构的 lpData 字段设置为 NULL。若要继续特定的堆枚举，请重复调用 HeapWalk 函数，不更改 hHeap、 lpEntry 或 PROCESS_HEAP_ENTRY 结构的任何成员。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零。要获得更多的错误信息，请调用 GetLastError。

如果堆枚举通过到达堆的末尾成功终止，则函数返回 FALSE， GetLastErrorERROR_NO_MORE_ITEMS返回错误代码。

注解

HeapWalk 函数主要用于调试，因为枚举堆可能非常耗时。在枚举期间锁定堆会阻止其他线程访问堆，并可能降低性能，尤其是在对称多处理 (SMP) 计算机上。副作用可能会持续到堆解锁。使用 HeapLock 和 HeapUnlock 函数在堆枚举期间控制堆锁定。

若要启动堆枚举，请将 lpEntry 指向的 PROCESS_HEAP_ENTRY 结构的 lpData 字段设置为 NULL，调用 HeapWalk。

若要继续堆枚举，请使用相同的 hHeap 和 lpEntry 值调用 HeapWalk，并且PROCESS_HEAP_ENTRY结构与前面对 HeapWalk 的调用不同。重复此过程，直到无需进一步枚举，或直到函数返回 FALSE 且 GetLastError 返回 ERROR_NO_MORE_ITEMS，指示已枚举所有堆的内存块。

无需特殊调用 HeapWalk 即可终止堆枚举，因为不会在PROCESS_HEAP_ENTRY 结构的内容之外维护枚举状态数据。

如果在堆枚举期间未锁定堆，HeapWalk 在多线程应用程序中可能会失败。

示例

枚举堆

要求


最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows Server 2003 [仅限桌面应用]
目标平台	Windows
标头	heapapi.h (包括 Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll