Microsoft Learn > Windows Apps > API Reference > Fundamentals > Memory Management

HeapReAlloc function

The HeapReAlloc function resizes a memory allocation that was previously allocated by a call to the HeapAlloc function.

Syntax


LPVOID HeapReAlloc(
  HANDLE hHeap,
  DWORD  flOptions,
  LPVOID lpMem,
  SIZE_T dwBytes
);

Parameters

hHeap
A handle to the heap that was created by a call to the HeapCreate or GetProcessHeap function.
flOptions
A bitmask that affects the behavior of this function. The following values are defined.
  • HEAP_GENERATE_EXCEPTIONS: If the function fails, it calls RaiseException with a status code of STATUS_NO_MEMORY.
  • HEAP_ZERO_MEMORY: If the function succeeds, it initializes all memory in the new allocation to zero.
  • HEAP_REALLOC_IN_USE_REPLACE_DEFINITION: Use this flag to ensure that the reallocated block of memory does not contain the new memory block. This can avoid unexpected behavior when using multiple pointers to the same block of memory.
lpMem
A pointer to the memory block to be reallocated. This pointer is returned by a previous call to HeapAlloc or HeapReAlloc.
dwBytes
The new size, in bytes, of the memory block to be reallocated.

Return value

If the function succeeds, the return value is a pointer to the reallocated memory block. If the function fails, the return value is NULL. To get extended error information, call GetLastError. If dwBytes is zero, and the block pointed to by lpMem was allocated from the heap, the return value is a valid pointer to a zero-sized block that can be passed to HeapFree. If dwBytes is zero and lpMem is not allocated from the heap, the return value is NULL.

Remarks

This function is used to resize a memory allocation. If the new size is larger than the old size, the contents of the memory block are preserved up to the minimum of the old and new sizes. If the new size is smaller than the old size, the contents of the memory block are preserved up to the new size.

If lpMem points to a memory block that was not allocated by HeapAlloc or HeapReAlloc, the behavior is undefined.

If the heap reallocation fails due to insufficient memory, the original memory block pointed to by lpMem is unaffected.

For a more comprehensive memory management solution, consider using HeapAlloc and HeapFree.

Requirements

Minimum supported client
Windows 2000 Professional [desktop apps only]
Minimum supported server
Windows 2000 Server [desktop apps only]
Header
memoryapi.h (include windows.h)
Library
Kernel32.lib
DLL
Kernel32.dll

See also