HeapQueryInformation function (heapapi.h)
Retrieves information about the specified heap.
BOOL HeapQueryInformation(
[in, optional] HANDLE HeapHandle,
[in] HEAP_INFORMATION_CLASS HeapInformationClass,
[out] PVOID HeapInformation,
[in] SIZE_T HeapInformationLength,
[out, optional] PSIZE_T ReturnLength
);
[in, optional] HeapHandle
A handle to the heap whose information is to be retrieved. This handle is returned by either the HeapCreate or GetProcessHeap function.
[in] HeapInformationClass
The class of information to be retrieved. This parameter can be the following value from the HEAP_INFORMATION_CLASS enumeration type.
Value | Meaning |
---|---|
|
Indicates the heap features that are enabled.
The HeapInformation parameter is a pointer to a ULONG variable. If HeapInformation is 0, the heap is a standard heap that does not support look-aside lists. If HeapInformation is 1, the heap supports look-aside lists. For more information, see Remarks. If HeapInformation is 2, the low-fragmentation heap (LFH) has been enabled for the heap. Enabling the LFH disables look-aside lists. |
[out] HeapInformation
A pointer to a buffer that receives the heap information. The format of this data depends on the value of the HeapInformationClass parameter.
[in] HeapInformationLength
The size of the heap information being queried, in bytes.
[out, optional] ReturnLength
A pointer to a variable that receives the length of data written to the HeapInformation buffer. If the buffer is too small, the function fails and ReturnLength specifies the minimum size required for the buffer.
If you do not want to receive this information, specify NULL.
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
To enable the LFH or the terminate-on-corruption feature, use the HeapSetInformation function.
Windows XP and Windows Server 2003: A look-aside list is a fast memory allocation mechanism that contains only fixed-sized blocks. Look-aside lists are enabled by default for heaps that support them. Starting with Windows Vista, look-aside lists are not used and the LFH is enabled by default.
Look-aside lists are faster than general pool allocations that vary in size, because the system does not search for free memory that fits the allocation. In addition, access to look-aside lists is generally synchronized using fast atomic processor exchange instructions instead of mutexes or spinlocks. Look-aside lists can be created by the system or drivers. They can be allocated from paged or nonpaged pool.
The following example uses GetProcessHeap to obtain a handle to the default process heap and HeapQueryInformation to retrieve information about the heap.
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#define HEAP_STANDARD 0
#define HEAP_LAL 1
#define HEAP_LFH 2
int __cdecl _tmain()
{
BOOL bResult;
HANDLE hHeap;
ULONG HeapInformation;
//
// Get a handle to the default process heap.
//
hHeap = GetProcessHeap();
if (hHeap == NULL) {
_tprintf(TEXT("Failed to retrieve default process heap with LastError %d.\n"),
GetLastError());
return 1;
}
//
// Query heap features that are enabled.
//
bResult = HeapQueryInformation(hHeap,
HeapCompatibilityInformation,
&HeapInformation,
sizeof(HeapInformation),
NULL);
if (bResult == FALSE) {
_tprintf(TEXT("Failed to retrieve heap features with LastError %d.\n"),
GetLastError());
return 1;
}
//
// Print results of the query.
//
_tprintf(TEXT("HeapCompatibilityInformation is %d.\n"), HeapInformation);
switch(HeapInformation)
{
case HEAP_STANDARD:
_tprintf(TEXT("The default process heap is a standard heap.\n"));
break;
case HEAP_LAL:
_tprintf(TEXT("The default process heap supports look-aside lists.\n"));
break;
case HEAP_LFH:
_tprintf(TEXT("The default process heap has the low-fragmentation ") \
TEXT("heap enabled.\n"));
break;
default:
_tprintf(TEXT("Unrecognized HeapInformation reported for the default ") \
TEXT("process heap.\n"));
break;
}
return 0;
}
Requirement | Value |
---|---|
Minimum supported client | Windows XP [desktop apps only] |
Minimum supported server | Windows Server 2003 [desktop apps only] |
Target Platform | Windows |
Header | heapapi.h (include Windows.h) |
Library | Kernel32.lib |
DLL | Kernel32.dll |