Expand Minimize

HeapQueryInformation function

Retrieves information about the specified heap.

Syntax


BOOL WINAPI HeapQueryInformation(
  _In_opt_   HANDLE HeapHandle,
  _In_       HEAP_INFORMATION_CLASS HeapInformationClass,
  _Out_      PVOID HeapInformation,
  _In_       SIZE_T HeapInformationLength,
  _Out_opt_  PSIZE_T ReturnLength
);

Parameters

HeapHandle [in, optional]

A handle to the heap whose information is to be retrieved. This handle is returned by either the HeapCreate or GetProcessHeap function.

HeapInformationClass [in]

The class of information to be retrieved. This parameter can be the following value from the HEAP_INFORMATION_CLASS enumeration type.

ValueMeaning
HeapCompatibilityInformation
0

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.

 

HeapInformation [out]

A pointer to a buffer that receives the heap information. The format of this data depends on the value of the HeapInformationClass parameter.

HeapInformationLength [in]

The size of the heap information being queried, in bytes.

ReturnLength [out, optional]

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.

Return value

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.

Remarks

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.

Examples

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;
}


Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

HeapApi.h (include Windows.h);
WinBase.h on Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

See also

GetProcessHeap
Heap Functions
HeapCreate
HeapSetInformation
Memory Management Functions

 

 

Community Additions

ADD
Show:
© 2014 Microsoft