Releases, decommits, or releases and decommits a region of pages within the virtual address space of the calling process.

To free memory allocated in another process by theVirtualAllocEx function, use theVirtualFreeEx function.

Syntax

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

Parameters

[in] lpAddress

A pointer to the base address of the region of pages to be freed.

If thedwFreeType parameter isMEM_RELEASE, this parameter must be the base address returned by theVirtualAlloc function when the region of pages is reserved.

[in] dwSize

The size of the region of memory to be freed, in bytes.

If thedwFreeType parameter isMEM_RELEASE, this parameter must be 0 (zero). The function frees the entire region that is reserved in the initial allocation call toVirtualAlloc.

If thedwFreeType parameter isMEM_DECOMMIT, the function decommits all memory pages that contain one or more bytes in the range from thelpAddress parameter to(lpAddress+dwSize). This means, for example, that a 2-byte region of memory that straddles a page boundary causes both pages to be decommitted. IflpAddress is the base address returned byVirtualAlloc anddwSize is 0 (zero), the function decommits the entire region that is allocated byVirtualAlloc. After that, the entire region is in the reserved state.

[in] dwFreeType

The type of free operation. This parameter must be one of the following values.

When usingMEM_RELEASE, this parameter can additionally specify one of the following values.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is 0 (zero). To get extended error information, callGetLastError.

Remarks

Each page of memory in a process virtual address space has aPage State. TheVirtualFree function can decommit a range of pages that are in different states, some committed and some uncommitted. This means that you can decommit a range of pages without first determining the current commitment state of each page. Decommitting a page releases its physical storage, either in memory or in the paging file on disk.

If a page is decommitted but not released, its state changes to reserved. Subsequently, you can callVirtualAlloc to commit it, orVirtualFree to release it. Attempts to read from or write to a reserved page results in an access violation exception.

TheVirtualFree function can release a range of pages that are in different states, some reserved and some committed. This means that you can release a range of pages without first determining the current commitment state of each page. The entire range of pages originally reserved by theVirtualAlloc function must be released at the same time.

If a page is released, its state changes to free, and it is available for subsequent allocation operations. After memory is released or decommited, you can never refer to the memory again. Any information that may have been in that memory is gone forever. Attempting to read from or write to a free page results in an access violation exception. If you need to keep information, do not decommit or free memory that contains the information.

TheVirtualFree function can be used on an AWE region of memory, and it invalidates any physical page mappings in the region when freeing the address space. However, the physical page is not deleted, and the application can use them. The application must explicitly callFreeUserPhysicalPages to free the physical pages. When the process is terminated, all resources are cleaned up automatically.

Windows 10, version 1709 and later and Windows 11: To delete the enclave when you finish using it, callDeleteEnclave. You cannot delete a VBS enclave by calling theVirtualFree orVirtualFreeEx function. You can still delete an SGX enclave by callingVirtualFree orVirtualFreeEx.

Windows 10, version 1507, Windows 10, version 1511, Windows 10, version 1607 and Windows 10, version 1703: To delete the enclave when you finish using it, call theVirtualFree orVirtualFreeEx function and specify the following values:

• The base address of the enclave for thelpAddress parameter.
• 0 for thedwSize parameter.
• MEM_RELEASE for thedwFreeType parameter.

Examples

For an example, seeReserving and Committing Memory.

Requirements

See also

Memory Management Functions

Virtual Memory Functions

VirtualFreeEx

Vertdll APIs available in VBS enclaves