HeapWalk 関数 (heapapi.h)

  • [アーティクル]

指定したヒープ内のメモリ ブロックを列挙します。

構文

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

パラメーター

[in] hHeap

ヒープへのハンドル。 このハンドルは、 HeapCreate 関数または GetProcessHeap 関数によって返されます。

[in, out] lpEntry

特定のヒープ列挙体の状態情報を保持する PROCESS_HEAP_ENTRY 構造体へのポインター。

HeapWalk 関数が成功し、値 TRUE が返された場合、この構造体のメンバーにはヒープ内の次のメモリ ブロックに関する情報が含まれます。

ヒープ列挙を開始するには、PROCESS_HEAP_ENTRY構造体の lpData フィールドを NULL に設定します。 特定のヒープ列挙を続行するには、 heapWalk 関数を繰り返し呼び出します。 hHeap、 lpEntry、または PROCESS_HEAP_ENTRY 構造体のメンバーは変更されません。

戻り値

関数が成功すると、戻り値は 0 以外になります。

関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

ヒープの末尾に達してヒープ列挙が正常に終了した場合、関数は FALSE を返し、GetLastError はエラー コード ERROR_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

関連項目

ヒープ関数

HeapLock

HeapReAlloc

HeapUnlock

HeapValidate

メモリ管理関数

PROCESS_HEAP_ENTRY