Memory Management Functions

You are here: Windows API Reference > Memory Management > Memory Management Functions

This section details the core functions used for managing memory within the Windows operating system. These functions provide granular control over memory allocation, deallocation, protection, and access.

VirtualAlloc

LPVOID VirtualAlloc( LPVOID lpAddress, SIZE_T dwSize, DWORD flAllocationType, DWORD flProtect );

Reserves, commits, or changes the state of a region of pages in the virtual address space of the calling process.

lpAddress: The starting address of the region of pages to be allocated. If this parameter is NULL, the system determines where to allocate the region.
dwSize: The size of the region of pages to be allocated, in bytes.
flAllocationType: The type of memory allocation. This parameter can be one or more of the following values: MEM_COMMIT, MEM_RESERVE, MEM_RESET, MEM_RESET_UNDO, MEM_LARGE_PAGES, MEM_PHYSICAL, MEM_TOP_DOWN.
flProtect: The memory protection for the region of pages to be allocated. This parameter can be one or more of the following values: PAGE_EXECUTE, PAGE_EXECUTE_READ, PAGE_EXECUTE_READWRITE, PAGE_EXECUTE_WRITECOPY, PAGE_NOACCESS, PAGE_READONLY, PAGE_READWRITE, PAGE_WRITECOPY.

Return Value: If the function succeeds, the return value is the base address of the allocated region of pages. If the function fails, the return value is NULL. To get extended error information, call GetLastError.

VirtualFree

BOOL VirtualFree( LPVOID lpAddress, SIZE_T dwSize, DWORD dwFreeType );

Decommits a region of pages or releases a region of memory that was previously reserved by the calling process.

lpAddress: A pointer to the starting address of the region of pages to be freed.
dwSize: The size of the region of pages to be freed, in bytes. This parameter must be zero if dwFreeType is MEM_RELEASE.
dwFreeType: The type of freeing operation. This parameter can be one of the following values: MEM_DECOMMIT or MEM_RELEASE.

Return Value: If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

HeapAlloc

LPVOID HeapAlloc( HANDLE hHeap, DWORD dwFlags, SIZE_T dwBytes );

Allocates a specified number of bytes from a heap. The allocated memory is uninitialized.

hHeap: A handle to the heap from which the memory will be allocated. This handle is returned by the HeapCreate function.
dwFlags: The allocation flags. This parameter can be zero or one or more of the following flags: HEAP_GENERATE_EXCEPTIONS, HEAP_NO_SERIALIZE, HEAP_ZERO_MEMORY.
dwBytes: The number of bytes to be allocated from the heap. If this parameter is _HEAP_MAXREQ, the function allocates the maximum number of bytes that the process can allocate from a heap.

Return Value: If the function succeeds, and dwFlags does not include HEAP_Generate_Exceptions, the return value is a pointer to the allocated memory. If the function fails, and dwFlags does not include HEAP_Generate_Exceptions, the return value is NULL. To get extended error information, call GetLastError.

HeapFree

BOOL HeapFree( HANDLE hHeap, DWORD dwFlags, LPVOID lpMem );

Frees a block of memory that was previously allocated from a specified heap by using the HeapAlloc or HeapReAlloc function.

hHeap: A handle to the heap that contains the memory block to be freed. This handle is returned by the HeapCreate function.
dwFlags: Heap free flags. Must be zero.
lpMem: A pointer to the memory block to be freed. This pointer is returned by the HeapAlloc or HeapReAlloc function.

Return Value: If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

GlobalAlloc

HGLOBAL GlobalAlloc( UINT uFlags, SIZE_T uBytes );

Allocates the specified number of bytes from the general-purpose memory allocation functions.

uFlags: The allocation attributes. This parameter can be one or more of the following values: GMEM_FIXED, GMEM_MOVEABLE, GMEM_ZEROINIT, GHND, GPTR.
uBytes: The number of bytes to allocate. If this parameter is 0 and uFlags specifies GMEM_MOVEABLE, the function returns a handle to a zero-byte memory object that can be resized later. If uBytes is 0 and uFlags specifies GMEM_FIXED, the function returns NULL.

Return Value: If the function succeeds, and uFlags specifies GMEM_MOVEABLE, the return value is a handle to the newly allocated memory object. If uFlags specifies GMEM_FIXED, the return value is a pointer to the newly allocated memory object. If the function fails, the return value is NULL. To get extended error information, call GetLastError.

GlobalFree

HGLOBAL GlobalFree( HGLOBAL hMem );

Frees the specified fixed or movable memory object.

hMem: A handle to the memory object to be freed. This handle must have been created by a previous call to the GlobalAlloc function.

Return Value: If the function succeeds, the return value is NULL. If the function fails, the return value is a handle to the memory object. To get extended error information, call GetLastError.

LocalAlloc

HLOCAL LocalAlloc( UINT uFlags, SIZE_T uBytes );

Allocates the specified number of bytes from the local memory allocation functions.

uFlags: The allocation attributes. This parameter can be one or more of the following values: LMEM_FIXED, LMEM_MOVEABLE, LMEM_ZEROINIT, LHND, LPTR.
uBytes: The number of bytes to allocate. If this parameter is 0 and uFlags specifies LMEM_MOVEABLE, the function returns a handle to a zero-byte memory object that can be resized later. If uBytes is 0 and uFlags specifies LMEM_FIXED, the function returns NULL.

Return Value: If the function succeeds, and uFlags specifies LMEM_MOVEABLE, the return value is a handle to the newly allocated memory object. If uFlags specifies LMEM_FIXED, the return value is a pointer to the newly allocated memory object. If the function fails, the return value is NULL. To get extended error information, call GetLastError.

LocalFree

HLOCAL LocalFree( HLOCAL hMem );

Frees the specified fixed or movable local memory object.

hMem: A handle to the memory object to be freed. This handle must have been created by a previous call to the LocalAlloc function.

Return Value: If the function succeeds, the return value is NULL. If the function fails, the return value is a handle to the memory object. To get extended error information, call GetLastError.

Important: Applications should prefer using the VirtualAlloc family of functions over the older GlobalAlloc and LocalAlloc functions for general-purpose memory allocation when possible, as they provide more flexibility and control over memory management.