Documentation > Windows > API Reference > Win32 > Functions > Kernel32 > VirtualFree

VirtualFree Function

The VirtualFree function decommits a region of pages or releases a region of memory that was previously committed using the VirtualAlloc or VirtualAllocEx functions.

Syntax

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

Parameters

  • lpAddress: A pointer to the starting page of the region of memory to be freed. This parameter must be greater than 0.
  • dwSize: The size of the region of memory to be freed, in bytes. This parameter must be greater than 0.
  • dwFreeType: The type of operation to perform. This parameter can be one of the following values:
    • MEM_DECOMMIT: Decommits the specified region of pages. A decommitted region no longer has physical backing storage.
    • MEM_RELEASE: Releases the specified region of memory. This value must be used with MEM_DECOMMIT.

Return Value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

You can decommit or release a region of memory in one of two ways:

  • Decommit a region of pages using MEM_DECOMMIT. The memory is still reserved, but the pages are no longer mapped to physical storage.
  • Release a region of pages using MEM_RELEASE. The memory is no longer reserved.

When decommitting or releasing memory, the address must be greater than 0. The dwSize parameter must be greater than 0.

The MEM_RELEASE flag must be used to decommit or release the entire region of memory that was allocated by a single call to VirtualAlloc or VirtualAllocEx. If you decommit pages within a region allocated by a single call to VirtualAlloc or VirtualAllocEx, you must also specify MEM_DECOMMIT.

Requirements

Value
Minimum supported client Windows 2000 Professional
Minimum supported server Windows 2000 Server
Header memoryapi.h (include windows.h)
Library Kernel32.lib
DLL Kernel32.dll
Tip For more information on memory management in Windows, refer to the Microsoft Learn Memory Management documentation.

See Also