HeapSetInformation function
Applies to: desktop apps only
Enables features for a specified heap.
Syntax
BOOL WINAPI HeapSetInformation( __in_opt HANDLE HeapHandle, __in HEAP_INFORMATION_CLASS HeapInformationClass, __in PVOID HeapInformation, __in SIZE_T HeapInformationLength );
Parameters
- HeapHandle [in, optional]
-
A handle to the heap where information is to be set. This handle is returned by either the HeapCreate or GetProcessHeap function.
- HeapInformationClass [in]
-
The class of information to be set. This parameter can be one of the following values from the HEAP_INFORMATION_CLASS enumeration type.
Value Meaning - HeapCompatibilityInformation
- 0
Enables heap features. Only the low-fragmentation heap (LFH) is supported. However, it is not necessary for applications to enable the LFH because the system uses the LFH as needed to service memory allocation requests.
Windows XP and Windows Server 2003:The LFH is not enabled by default. To enable the LFH for the specified heap, set the variable pointed to by the HeapInformation parameter to 2. After the LFH is enabled for a heap, it cannot be disabled.
The LFH cannot be enabled for heaps created with HEAP_NO_SERIALIZE or for heaps created with a fixed size. The LFH also cannot be enabled if you are using the heap debugging tools in Debugging Tools for Windows or Microsoft Application Verifier.
When a process is run under any debugger, certain heap debug options are automatically enabled for all heaps in the process. These heap debug options prevent the use of the LFH. To enable the low-fragmentation heap when running under a debugger, set the _NO_DEBUG_HEAP environment variable to 1.
- HeapEnableTerminationOnCorruption
- 1
Enables the terminate-on-corruption feature. If the heap manager detects an error in any heap used by the process, it calls the Windows Error Reporting service and terminates the process.
After a process enables this feature, it cannot be disabled.
Windows Server 2003 and Windows XP: This value is not supported until Windows Vista and Windows XP with SP3. The function succeeds but the HeapEnableTerminationOnCorruption value is ignored. - HeapInformation [in]
-
The heap information buffer. The format of this data depends on the value of the HeapInformationClass parameter.
If the HeapInformationClass parameter is HeapCompatibilityInformation, the HeapInformation parameter is a pointer to a ULONG variable.
If the HeapInformationClass parameter is HeapEnableTerminationOnCorruption, the HeapInformation parameter should be NULL and HeapInformationLength should be 0
- HeapInformationLength [in]
-
The size of the HeapInformation buffer, in bytes.
Return value
If the function succeeds, the return value is nonzero.
If the function fails, the return value is 0 (zero). To get extended error information, call GetLastError.
Remarks
To retrieve the current settings for the heap, use the HeapQueryInformation function.
Setting the HeapEnableTerminateOnCorruption option is strongly recommended because it reduces an application's exposure to security exploits that take advantage of a corrupted heap.
Examples
The following example shows you how to enable the low-fragmentation heap.
#include <windows.h> #include <tchar.h> #include <stdio.h> #define HEAP_LFH 2 int __cdecl _tmain() { BOOL bResult; HANDLE hHeap; ULONG HeapInformation; // // Enable heap terminate-on-corruption. // A correct application can continue to run even if this call fails, // so it is safe to ignore the return value and call the function as follows: // (void)HeapSetInformation(NULL, HeapEnableTerminationOnCorruption, NULL, 0); // If the application requires heap terminate-on-corruption to be enabled, // check the return value and exit on failure as shown in this example. // bResult = HeapSetInformation(NULL, HeapEnableTerminationOnCorruption, NULL, 0); if (bResult != FALSE) { _tprintf(TEXT("Heap terminate-on-corruption has been enabled.\n")); } else { _tprintf(TEXT("Failed to enable heap terminate-on-corruption with LastError %d.\n"), GetLastError()); return 1; } // // Create a new heap with default parameters. // hHeap = HeapCreate(0, 0, 0); if (hHeap == NULL) { _tprintf(TEXT("Failed to create a new heap with LastError %d.\n"), GetLastError()); return 1; } // // Enable the low-fragmenation heap (LFH). Starting with Windows Vista, // the LFH is enabled by default but this call does not cause an error. // HeapInformation = HEAP_LFH; bResult = HeapSetInformation(hHeap, HeapCompatibilityInformation, &HeapInformation, sizeof(HeapInformation)); if (bResult != FALSE) { _tprintf(TEXT("The low-fragmentation heap has been enabled.\n")); } else { _tprintf(TEXT("Failed to enable the low-fragmentation heap with LastError %d.\n"), GetLastError()); return 1; } return 0; }
Requirements
|
Minimum supported client | Windows XP |
|---|---|
|
Minimum supported server | Windows Server 2003 |
|
Header |
|
|
Library |
|
|
DLL |
|
See also
Send comments about this topic to Microsoft
Build date: 2/7/2012
http://msdn.microsoft.com/en-us/library/aa366750.aspx
http://support.microsoft.com/kb/929136/en-us
- 7/3/2010
- Snuff Daddy
- 7/9/2010
- GreenCat
No needs request MSKB 816542.
- 3/7/2009
- Yuhong Bao
According to http://blogs.msdn.com/michael_howard/archive/2008/02/18/faq-about-heapsetinformation-in-windows-vista-and-heap-based-buffer-overruns.aspx a 64-bit app running on Vista or later has HeapEnableTerminationOnCorruption turned on by default.
According to the MSDN info shown above there is no way to disable this feature. This is probably intended for security-sensitive apps. The implication is that your 64-bit app will always terminate immediately upon detection of heap corruption.
Although immediate termination may be appropriate for end-users, it can cause serious headaches during software development. Instant-termination makes it difficult to troubleshoot a heap-overrun problem in your code. There seems to be no documented way to temporarily disable auto-termination, even for testing purposes. Windows Error Reporting (WER) uses an apparently undocumented method to trigger a special exception handler, one that neither try/catch, the Visual Studio debugging IDE, nor SetUnhandledExceptionFilter() can intercept. Again presumably for security reasons.
One possible workaround is to write your own custom WER handler DLL, or to try to read the dump that WER generates. Using the debug heap is not viable for release testing because the debug heap significantly alters the memory layout, leaving latent Heisenbugs that are common in heap-overrun situations.
Edit: Reading the dump that WER generates is actually pretty easy, because it is in a standard format that both VS and WinDbg can read.
Developers need a way to troubleshoot the retail heap during release testing of 64-bit apps. Currently no such mechanism is documented. [If such a mechanism does exist please update this entry, thanks. -Gideon7]
- 2/23/2008
- Gideon7
- 11/30/2008
- Yuhong Bao
