VirtualAllocEx
[New
- Windows NT]
The VirtualAllocEx function reserves, commits,
or both, a region of memory within the virtual address space of a specified
process. The function initializes the memory it allocates to zero.
The
difference between the VirtualAllocEx function and the VirtualAlloc function is that VirtualAlloc
allocates memory within the address space of the calling process, while VirtualAllocEx
lets you specify a process.
LPVOID VirtualAllocEx(
|
HANDLE hProcess, |
// process within
which to allocate memory |
|
LPVOID lpAddress, |
// desired starting
address of allocation |
|
DWORD dwSize, |
// size, in bytes,
of region to allocate |
|
DWORD flAllocationType, |
// type of
allocation |
|
DWORD flProtect |
// type of access
protection |
|
); |
|
Parameters
hProcess
Handle to a
process. The function allocates memory within the virtual address space of this
process.
You must have PROCESS_VM_OPERATION access to the process. If you do
not, the function fails.
lpAddress
Pointer that
specifies a desired starting address for the region of pages that you want to
allocate.
If you are reserving memory, the function rounds this address down to
the nearest 64-kilobyte boundary.
If you are committing memory that is already reserved, the function
rounds this address down to the nearest page boundary. To determine the size of
a page on the host computer, use the GetSystemInfo function.
If lpAddress is NULL, the function determines where to allocate
the region.
dwSize
Specifies the
size, in bytes, of the region of memory to allocate.
If lpAddress is NULL, the function rounds dwSize up to
the next page boundary.
If lpAddress is not NULL, the function allocates all pages that
contain one or more bytes in the range from lpAddress to (lpAddress+dwSize).
This means, for example, that a 2-byte range that straddles a page boundary
causes the function to allocate both pages.
flAllocationType
A set of bit
flags that specifies the type of memory allocation. You can set one or more of
the following flags:
|
Flag |
Meaning |
|
MEM_COMMIT |
The
function allocates actual physical storage in memory or in the paging file on
disk for the specified region of memory pages. The function initializes the
memory to zero. |
|
|
An attempt
to commit a memory page that is already committed does not cause the function
to fail. This means that you can commit a range of pages without first
determining the current commitment state of each page. If a memory
page is not yet reserved, setting this flag causes the function to both
reserve and commit the memory page. |
|
MEM_RESERVE |
The
function reserves a range of the process s
virtual address space without allocating any actual physical storage in
memory or in the paging file on disk. Other
memory allocation functions, such as malloc and LocalAlloc, cannot use a reserved
range of memory until it is released. You can
commit reserved memory pages in subsequent calls to the VirtualAllocEx
function. |
|
MEM_TOP_DOWN |
The
function allocates memory at the highest possible address. |
flProtect
A set of bit
flags that specifies access protection for the region of pages you are
allocating. You can specify one of the following flags, along with the
PAGE_GUARD and PAGE_NOCACHE protection modifier flags, as desired:
|
Flag |
Meaning |
|
PAGE_READONLY |
Enables
read permission to the committed region of pages. An attempt to write to the
committed region results in an access violation. If the system differentiates
between read-only permission and execute permission, an attempt to execute
code in the committed region results in an access violation. |
|
PAGE_READWRITE |
Enables
both read and write permission to the committed region of pages. |
|
PAGE_EXECUTE |
Enables
execute permission to the committed region of pages. An attempt to read or
write to the committed region results in an access violation. |
|
PAGE_EXECUTE_READ |
Enables
execute and read permission to the committed region of pages. An attempt to
write to the committed region results in an access violation. |
|
PAGE_EXECUTE_READWRITE |
Enables
execute, read, and write permission to the committed region of pages. |
|
PAGE_GUARD |
Pages in
the region become guard pages. Any attempt to read from or write to a guard
page causes the operating system to raise a STATUS_GUARD_PAGE exception and
turn off the guard page status. Guard pages thus act as a one-shot access
alarm. The
PAGE_GUARD flag is a page protection modifier. An application uses it with
one of the other page protection flags, with one exception: It cannot be used
with PAGE_NOACCESS. When an access attempt leads the operating system to turn
off guard page status, the underlying page protection takes over. If a guard
page exception occurs during a system service, the service typically returns
a failure status indicator. |
|
PAGE_NOACCESS |
Disables
all access to the committed region of pages. An attempt to read from, write
to, or execute in the committed region results in an access violation
exception, called a general protection (GP) fault. |
|
PAGE_NOCACHE |
Allows no
caching of the committed regions of pages. The hardware attributes for the
physical memory should be specified as no
cache. This is not recommended for general usage. It is
useful for device drivers; for example, mapping a video frame buffer with no
caching. This flag is a page protection modifier, only valid when used with
one of the page protections other than PAGE_NOACCESS. |
A set of bit
flags that specifies access protection for the region of pages you are
allocating. You can specify one of the following flags, along with the PAGE_GUARD
and PAGE_NOCACHE protection modifier flags, as desired:
Return Values
If the
function succeeds, the return value is the base address of the allocated region
of pages.
If the
function fails, the return value is NULL. To get extended error information,
call GetLastError.
Remarks
The VirtualAllocEx
function can perform the following operations:
Commit a region of pages
reserved by a previous call to the VirtualAllocEx function.
Reserve a region of free pages.
Reserve and commit a region of
free pages.
You can use VirtualAllocEx
to reserve a block of pages and then make additional calls to VirtualAllocEx
to commit individual pages from the reserved block. This lets you reserve a
range of a process s virtual address space without consuming physical
storage until it is needed.
Each page of
memory in a process s virtual address space is in one of three states:
|
State |
Meaning |
|
Free |
The page is
not committed or reserved and is not accessible to the process. The VirtualAllocEx
function can reserve, or simultaneously reserve and commit, a free page. |
|
Reserved |
The page is
reserved. The range of addresses cannot be used by other allocation
functions, but the page is not accessible and has no physical storage
associated with it. The VirtualAllocEx function can commit a reserved
page, but it cannot reserve it a second time. You can use the VirtualFreeEx function to release a
reserved page in a specified process, making it a free page. |
|
Committed |
Physical
storage 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 or write to that page. When the process
terminates, the system releases the storage for committed pages. The VirtualAllocEx
function can commit an already committed page. This means that you can commit
a range of pages, regardless of whether they have already been committed, and
the function will not fail. You can use the VirtualFreeEx function to decommit a
committed page in a specified process, or to simultaneously decommit and free
a committed page. |
If the lpAddress
parameter is not NULL, the function uses the lpAddress and dwSize
parameters to compute the region of pages to be allocated. The current state of
the entire range of pages must be compatible with the type of allocation
specified by the flAllocationType parameter. Otherwise, the function
fails and none of the pages is allocated. This compatibility requirement does
not preclude committing an already committed page; see the preceding list.
The
PAGE_GUARD protection modifier flag establishes guard pages. Guard pages act as
one-shot access alarms. For more information see Guard Pages.
See Also