GetProcessHeaps function (heapapi.h)
Returns the number of active heaps and retrieves handles to all of the active heaps for the calling process.
Syntax
DWORD GetProcessHeaps(
[in] DWORD NumberOfHeaps,
[out] PHANDLE ProcessHeaps
);
Parameters
[in] NumberOfHeaps
The maximum number of heap handles that can be stored into the buffer pointed to by ProcessHeaps.
[out] ProcessHeaps
A pointer to a buffer that receives an array of heap handles.
Return value
The return value is the number of handles to heaps that are active for the calling process.
If the return value is less than or equal to NumberOfHeaps, the function has stored that number of heap handles in the buffer pointed to by ProcessHeaps.
If the return value is greater than NumberOfHeaps, the buffer pointed to by ProcessHeaps is too small to hold all the heap handles for the calling process, and the function stores NumberOfHeaps handles in the buffer. Use the return value to allocate a buffer that is large enough to receive all of the handles, and call the function again.
If the return value is zero, the function has failed because every process has at least one active heap, the default heap for the process. To get extended error information, call GetLastError.
Remarks
The GetProcessHeaps function obtains a handle to the default heap of the calling process, plus handles to any additional private heaps created by calling the HeapCreate function on any thread in the process.
The GetProcessHeaps function is primarily useful for debugging, because some of the private heaps retrieved by the function may have been created by other code running in the process and may be destroyed after GetProcessHeaps returns. Destroying a heap invalidates the handle to the heap, and continued use of such handles can cause undefined behavior in the application. Heap functions should be called only on the default heap of the calling process and on private heaps that the process creates and manages.
To obtain a handle to the process heap of the calling process, use the GetProcessHeap function.
Examples
For an example, see Getting Process Heaps.
Requirements
| 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 |