VirtualAlloc

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function reserves or commits a region of pages in the virtual address space of the calling process.

Memory allocated by VirtualAlloc is initialized to zero.

LPVOID VirtualAlloc(
  LPVOID lpAddress,
  DWORD dwSize,
  DWORD flAllocationType,
  DWORD flProtect
);

• lpAddress
  [in] Long pointer to the specified starting address of the region to be allocated.

  If the memory is being reserved, the specified address is rounded down to the next 64-KB boundary.

  If the memory is 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
  [in] Specifies the size, in bytes, of the region. It is an error to set this parameter to 0.

  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 plus dwSize. This means that a 2-byte range straddling a page boundary causes both pages to be included in the allocated region.

• flAllocationType
  [in] Specifies the type of allocation.

  The following table shows flags you can specify for this parameter in any combination.

  Expand table

  Value	Description
  MEM_COMMIT	Allocates physical storage in memory or in the paging file on disk for the specified region of pages. An attempt to commit a committed page does not cause the function to fail. This means that a range of committed or decommitted pages can be committed without being concerned about a failure.
  MEM_RESERVE	Reserves a range of the virtual address space of the process without allocating physical storage. The reserved range cannot be used by any other allocation operations, such as the malloc and LocalAlloc functions, until it is released. Reserved pages can be committed in subsequent calls to the VirtualAlloc function.
  MEM_RESET	Not supported.
  MEM_TOP_DOWN	Allocates memory at the highest possible address. This flag is ignored in Windows Mobile.

• flProtect
  [in] Specifies the type of access protection.

  If the pages are being committed, you can specify any of the following flags, along with the PAGE_GUARD and PAGE_NOCACHE protection modifier flags.

  Expand table

  Value	Description
  PAGE_EXECUTE	Enables execute access to the committed region of pages.
  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. An attempt to read from or write to a guard page causes the system to raise a STATUS_ACCESS_VIOLATION 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 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 use. It is useful for device drivers; for example, mapping a video frame buffer with no caching. This flag is a page protection modifier and is only valid when used with a page protection other than PAGE_NOACCESS.
  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.

The base address of the allocated region of pages indicates success. NULL indicates failure. To get extended error information, call GetLastError.

After reserving and committing a page in a client process with the following code:

LPBYTE p = (LPBYTE) VirtualAllocEx(hClientProc, NULL, 0x1000, MEM_COMMIT, PAGE_READWRITE);

You cannot simply write to *p with the following code:

*p = whatever;

You cannot write to *p directly because the address in the client process's virtual memory is not directly accessible. To read/write to the memory pointed by the pointer returned, use ReadProcessMemory and WriteProcessMemory. For example:

WriteProcessMemory(hClientProc, p, &whatever, 1, &cbReturned);

The following flProtect flags are not supported:

• PAGE_WRITECOPY
• PAGE_EXECUTE_WRITECOPY

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 virtual address space of the process is in one of three states:

• Free, in which 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, in which 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, in which 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 you can commit a range of pages, regardless of whether they have 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 no pages are allocated. This compatibility requirement does not preclude committing an already committed page.

Before Windows Embedded CE 6.0 , if you call VirtualAlloc with dwSize >= 2 MB, flAllocationType set to MEM_RESERVE, and flProtect set to PAGE_NOACCESS, it automatically reserves memory at the shared memory region. This preserves per-process virtual memory.

Security Note:
Memory in a shared memory region is readable and writable by other processes on the system. You must not store confidential information in those regions, and must validate any data read out of them.

For Windows Mobile Version 5.0, you cannot commit 32 MB or more at a time. You can reserve more than 32 MB at a time if fdwProtect=PAGE_NOACCESS and lpAddress=0. In addition, you cannot commit memory across a 32 MB boundary. For example, if you reserve 16 MB and it happens to cross a 32 MB boundary, you will need to make two VirtualAlloc calls to commit the memory.

Memory Management Functions
GetSystemInfo
LocalAlloc
VirtualFree
VirtualProtect
VirtualQuery