| Platform SDK: Memory |
The VirtualFreeEx function releases, decommits, or releases and decommits a region of memory within the virtual address space of a specified process.
BOOL VirtualFreeEx( HANDLE hProcess, // handle to process LPVOID lpAddress, // starting address of memory region SIZE_T dwSize, // size of memory region DWORD dwFreeType // operation type );
You must have PROCESS_VM_OPERATION access to this process. If you do not, the function fails.
If the MEM_RELEASE value is used in the dwFreeType parameter, lpAddress must be the base address returned by the VirtualAllocEx function when the region was reserved.
If the MEM_RELEASE value is used in the dwFreeType parameter, dwSize must be zero. The function frees the entire region that was reserved in the initial allocation call to VirtualAllocEx.
If the MEM_DECOMMIT value is used, the function decommits all memory pages that contain one or more bytes in the range from the lpAddress 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.
The function decommits the entire region that was reserved by VirtualAllocEx. If the following three conditions are met:
The entire region the enters the reserved state.
| Value | Meaning |
|---|---|
| MEM_DECOMMIT | The function decommits the specified region of pages. The pages enter the reserved state.
The function does not fail if you attempt to decommit an uncommitted page. This means that you can decommit a range of pages without first determining their current commitment state. |
| MEM_RELEASE | The function releases the specified region of pages. The pages enter the free state.
If you specify this value, dwSize must be zero, and lpAddress must point to the base address returned by the VirtualAllocEx function when the region was reserved. The function fails if either of these conditions is not met. |
| If any pages in the region are currently committed, the function first decommits and then releases them.
The function does not fail if you attempt to release pages that are in different states, some reserved and some committed. This means that you can release a range of pages without first determining their current commitment state. |
If the function succeeds, the return value is a nonzero value.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Each page of memory in a process's virtual address space is in one of the following states.
| State | Meaning |
|---|---|
| Free | The page is neither committed nor reserved. The page is not accessible to the process. Attempting to read from or write to a free page results in an access violation exception.
You can use the VirtualFreeEx function to put reserved or committed memory pages into the free state. |
| Reserved | The page is reserved. The range of addresses cannot be used by other allocation functions. The page is not accessible and has no physical storage associated with it. Attempting to read from or write to a free page results in an access violation exception.
You can use the VirtualFreeEx function to put committed memory pages into the reserved state, and to put reserved memory pages into the free state. |
| Committed | The page is committed. Physical storage in memory or in the paging file on disk is allocated for the page, and access is controlled by a protection code.
The system initializes and loads each committed page into physical memory only at the first attempt to read from or write to that page. When a process terminates, the system releases all storage for committed pages. You can use the VirtualAllocEx function to put committed memory pages into either the reserved or free state. |
The VirtualFreeEx function can perform the following operations:
The VirtualFreeEx 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. You can subsequently call VirtualAllocEx to commit it, or VirtualFreeEx to release it. Attempting to read from or write to a reserved page results in an access violation exception.
The VirtualFreeEx 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 the VirtualAllocEx 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. Once memory is released or decommitted, 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 require information, do not decommit or free memory containing that information.
Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98: Unsupported.
Header: Declared in Winbase.h; include Windows.h.
Library: Use Kernel32.lib.
Memory Management Overview, Memory Management Functions, VirtualAllocEx