|
Overview |
|
|
|
Group |
|
|
|
Quick Info
Windows NT
| Yes
| Win95
| No
| Win32s
| No
| Import Library
| kernel32.lib
| Header File
| winbase.h
| Unicode
| No
| Platform Notes
| None
|
|
|
VirtualFreeEx
[New - Windows NT]
The VirtualFreeEx function releases, decommits, or both, a region of memory within the virtual
address space of a specified process.
The difference between the VirtualFreeEx function and the VirtualFree function is that VirtualFree frees memory within the address space of the calling process, while VirtualFreeEx lets you specify a process.
BOOL VirtualFreeEx(
HANDLE hProcess,
| // process within which to free memory
| LPVOID lpAddress,
| // starting address of memory region to free
| DWORD dwSize,
| // size, in bytes, of memory region to free
| DWORD dwFreeType
| // type of free operation
| );
|
|
Parameters
hProcess
Handle to a process. The function frees memory within the virtual address
space of this process.
You must have PROCESS_VM_OPERATION access to this process. If you do not, the
function fails.
lpAddress
Pointer to the starting address of the region of memory to free.
If the MEM_RELEASE flag is set in the dwFreeType parameter, lpAddress must be the base address returned by the VirtualAllocEx function when the region was reserved.
dwSize
Specifies the size, in bytes, of the region of memory to free.
If the MEM_RELEASE flag is set 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 flag is set, 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 MEM_DECOMMIT flag is set
- lpAddress is the base address returned by the VirtualAllocEx function when the region was reserved
- dwSize is zero
The entire region the enters the reserved state.
dwFreeType
Set of bit flags that specifies the type of free operation. You must set one
of the following two flags:
Flag
| 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 flag, 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.
|
Return Values
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.
Remarks
Each page of memory in a process's virtual address space is in one of three
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 operating 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 operating 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:
- Decommit a region of committed or uncommitted pages. After this operation, the
pages are in the reserved state.
- Release a region of reserved pages. After this operation, the pages are in the
free state.
- Decommit and release a region of committed or uncommitted pages. After this
operation, the pages are in the free state.
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. Attempting to read from or write to a free page
results in an access violation exception.
See Also
GlobalAlloc, GlobalFree, VirtualAlloc, VirtualAllocEx, VirtualFree
Related Links
Software for Delphi and C++ Builder developers
Software for Visual Studio .NET developers
Software for Visual Basic 6 developers
Delphi Tips&Tricks
MegaDetailed.NET
TMS Scripter Studio Pro components for Delphi/C++Builder
More Online Helps
Win32 Multimedia Programmer's Reference (mmedia.hlp)
OLE Programmer's Reference (ole.hlp)
Microsoft Windows Pen API Programmer's Reference (penapi.hlp)
Microsoft Windows Sockets 2 Reference (sock2.hlp)
Microsoft Windows Telephony API (TAPI) Programmer's Reference (tapi.hlp)
Unix Manual Pages
|
