HeapValidate 0BR858

The HeapValidate function attempts to validate a specified heap. The function scans all the memory blocks in the heap, and verifies that the heap control structures maintained by the operating system s heap manager are in a consistent state. You can also use the HeapValidate function to validate a single memory block within a specified heap, without checking the validity of the entire heap.

BOOL HeapValidate(

HANDLE hHeap,	// handle to the heap of interest
DWORD dwFlags,	// bit flags that control heap access during function operation
LPCVOID lpMem	// optional pointer to individual memory block to validate
);

Parameters

hHeap

Handle to the heap of interest. The HeapValidate function attempts to validate this heap, or a single memory block within this heap.

dwFlags

A set of bit flags that control heap access during function operation. The following bit flag has meaning:

Value

Meaning

HEAP_NO_SERIALIZE

If this flag is set, heap access is not serialized while the HeapValidate function accesses the heap; heap access is not mutually exclusive. It is safe to set this flag only in a limited set of specific situations. For a discussion of those situations and heap serialization in general, see the Remarks section of HeapCreateE.PZ6H.

If this flag is clear, heap access is serialized while HeapValidate accesses the heap; heap access is mutually exclusive. This is the safe and simple default condition.

lpMem

Points to a memory block within the specified heap. This parameter may be NULL.

If this parameter is NULL, the function attempts to validate the entire heap specified by hHeap.

If this parameter is not NULL, the function attempts to validate the memory block pointed to by lpMem. It does not attempt to validate the rest of the heap.

Return Values

If the specified heap or memory block is valid, the return value is nonzero.

If the specified heap or memory block is invalid, the return value is zero. On a system set up for debugging, the HeapValidate function then displays debugging messages that describe the part of the heap or memory block that is invalid, and stops at a hard-coded breakpoint so that you can examine the system to determine the source of the invalidity. The HeapValidate function does not set the thread s last error value.

Remarks

There are heap control structures for each memory block in a heap, and for the heap as a whole. When you use the HeapValidate function to validate a complete heap, it checks all of these control structures for consistency.

When you use HeapValidate to validate a single memory block within a heap, it checks only the control structures pertaining to that element. HeapValidate can only validate allocated memory blocks. Calling HeapValidate on a freed memory block will return FALSE because there are no control structures to validate.

If you want to validate the heap elements enumerated by the HeapWalk function, you should only call HeapValidate on the elements that have the PROCESS_HEAP_ENTRY_BUSY bit flag in the wFlags member of the PROCESS_HEAP_ENTRY structure. HeapValidate returns FALSE for all heap elements that do not have this bit set.