VirtualAlloc
The VirtualAlloc
function reserves or commits a region of pages in the virtual address space of
the calling process. Memory allocated by this function is automatically
initialized to zero.
LPVOID VirtualAlloc(
|
LPVOID lpAddress, |
// address of
region to reserve or commit |
|
DWORD dwSize, |
// size of region |
|
DWORD flAllocationType, |
// type of
allocation |
|
DWORD flProtect |
// type of access
protection |
|
); |
|
Parameters
lpAddress
Specifies the
desired starting address of the region to allocate. If the memory is being
reserved, the specified address is rounded down to the next 64-kilobyte
boundary. If the memory is already reserved and is being committed, the address
is rounded down to the next page boundary. To determine the size of a page on
the host computer, use the GetSystemInfo function. If this parameter is NULL, the system
determines where to allocate the region.
dwSize
Specifies the
size, in bytes, of the region. If the lpAddress parameter is NULL, this
value is rounded up to the next page boundary. Otherwise, the allocated pages
include all pages containing one or more bytes in the range from lpAddress
to (lpAddress+dwSize). This means that a 2-byte range straddling
a page boundary causes both pages to be included in the allocated region.
flAllocationType
Specifies the
type of allocation. You can specify any combination of the following flags:
|
Flag |
Meaning |
|
MEM_COMMIT |
Allocates
physical storage in memory or in the paging file on disk for the specified
region of pages. |
|
|
An attempt
to commit an already committed page will not cause the function to fail. This
means that a range of committed or decommitted pages can be committed without
having to worry about a failure. |
|
MEM_RESERVE |
Reserves a
range of the process s virtual address space without allocating any physical
storage. The reserved range cannot be used by any other allocation operations
(the malloc function, the LocalAlloc2_D2EE function, and so on) until it is
released. Reserved pages can be committed in subsequent calls to the VirtualAlloc
function. |
|
MEM_TOP_DOWN |
Allocates
memory at the highest possible address. |
flProtect
Specifies the
type of access protection. If the pages are being committed, any one of the
following flags can be specified, along with the PAGE_GUARD and PAGE_NOCACHE
protection modifier flags, as desired:
|
Flag |
Meaning |
|
PAGE_READONLY |
Enables
read access 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 access and execute access, an attempt to execute code in
the committed region results in an access violation. |
|
PAGE_READWRITE |
Enables
both read and write access to the committed region of pages. |
|
PAGE_EXECUTE |
Enables
execute access 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 access 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 access 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. |
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
VirtualAlloc can perform the following operations:
Commit a region of pages
reserved by a previous call to the VirtualAlloc function.
Reserve a region of free pages.
Reserve and commit a region of
free pages.
You can use VirtualAlloc
to reserve a block of pages and then make additional calls to VirtualAlloc
to commit individual pages from the reserved block. This enables a process to
reserve a range of its virtual address space without consuming physical storage
until it is needed.
Each page in
the 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. VirtualAlloc
can reserve, or simultaneously reserve and commit, a free page. |
|
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. VirtualAlloc
can commit a reserved page, but it cannot reserve it a second time. The VirtualFree function can release a
reserved page, 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. VirtualAlloc
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. VirtualFree can decommit a committed page, releasing the
page s storage, or it can simultaneously decommit and
release 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 are 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. See Guard Pages.
See Also