VirtualFree
The VirtualFree
function releases or decommits (or both) a region of pages within the virtual
address space of the calling process.
BOOL VirtualFree(
|
LPVOID lpAddress, |
// address of
region of committed pages |
|
DWORD dwSize, |
// size of region |
|
DWORD dwFreeType |
// type of free
operation |
|
); |
|
Parameters
lpAddress
Points to the
base address of the region of pages to be freed. If the dwFreeType
parameter includes the MEM_RELEASE flag, this parameter must be the base
address returned by the VirtualAlloc function when the region of pages was
reserved.
dwSize
Specifies the
size, in bytes, of the region to be freed. If the dwFreeType parameter
includes the MEM_RELEASE flag, this parameter must be zero. Otherwise, the
region of affected pages includes all pages containing one or more bytes in the
range from the lpAddress parameter to (lpAddress+dwSize).
This means that a 2-byte range straddling a page boundary causes both pages to
be freed.
dwFreeType
Specifies the
type of free operation. One, but not both, of the following flags can be
specified:
|
Flag |
Meaning |
|
MEM_DECOMMIT |
Decommits
the specified region of committed pages. |
|
|
An attempt
to decommit an uncommitted page will not cause the function to fail. This
means that a range of committed or uncommitted pages can be decommitted
without having to worry about a failure. |
|
MEM_RELEASE |
Releases
the specified region of reserved pages. If this flag is specified, the dwSize
parameter must be zero, or the function fails. |
Return Values
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
VirtualFree can perform one of the following operations:
Decommit a region of committed
or uncommitted pages.
Release a region of reserved
pages.
Decommit and release a region
of committed or uncommitted pages.
To release a
region of pages, the entire range of pages must be in the same state (all
reserved or all committed) and the entire region originally reserved by the VirtualAlloc
function must be released at the same time. If only part of the pages in the
original reserved region are committed, you must first call VirtualFree
to decommit the committed pages and then call VirtualFree again to
release the entire block.
Pages that
have been released are free pages available for subsequent allocation
operations. Attempting to read from or write to a free page results in an
access violation exception.
VirtualFree can decommit an uncommitted page; this means that a
range of committed or uncommitted pages can be decommitted without having to
worry about a failure. 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, and it can be committed again by a
subsequent call to VirtualAlloc. Attempting to read from or write to a
reserved page results in an access violation exception.
The current
state of the entire range of pages must be compatible with the type of free
operation specified by the dwFreeType parameter. Otherwise, the function
fails and no pages are released or decommitted.
See Also