GetProcessHeaps function

Returns the number of active heaps and retrieves handles to all of the active heaps for the calling process.


DWORD WINAPI GetProcessHeaps(
  _In_  DWORD   NumberOfHeaps,
  _Out_ PHANDLE ProcessHeaps


NumberOfHeaps [in]

The maximum number of heap handles that can be stored into the buffer pointed to by ProcessHeaps.

ProcessHeaps [out]

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.


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.


For an example, see Getting Process Heaps.


Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]


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)





See also

Heap Functions
Memory Management Functions