Microsoft Windows CE 3.0  

VirtualAlloc

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This function reserves or commits a region of pages in the virtual address space of the calling process. Memory allocated by VirtualAllocis automatically initialized to zero.

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

Parameters

lpAddress
Long pointer to the desired 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 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 GetSystemInfofunction. If this parameter is NULL, the system determines where to allocate the region.
dwSize
Specifies the size, in bytes, of the region. If the lpAddressparameter 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 lpAddressto 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 flags listed in the following 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 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, such as the mallocand LocalAllocfunctions, until it is released. Reserved pages can be committed in subsequent calls to the VirtualAllocfunction.
MEM_RESET Not supported.
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 flags listed in the following table can be specified, along with the PAGE_GUARD and PAGE_NOCACHE protection modifier flags, as desired.
Value Description
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 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 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 and is only valid when used with one of the page protections other than PAGE_NOACCESS.

Return Values

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

Remarks

The following flProtectflags are not supported:

  • PAGE_WRITECOPY
  • PAGE_EXECUTE_WRITECOPY

    VirtualAlloccan perform the following operations:

    • Commit a region of pages reserved by a previous call to the VirtualAllocfunction.
    • Reserve a region of free pages.
    • Reserve and commit a region of free pages.

      You can use VirtualAllocto reserve a block of pages and then make additional calls to VirtualAllocto 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:

      • Free, in which the page is not committed or reserved and is not accessible to the process. VirtualAlloccan 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. VirtualAlloccan commit a reserved page, but it cannot reserve it a second time. The VirtualFreefunction 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. VirtualAlloccan 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. VirtualFreecan decommit a committed page, releasing the page's storage, or it can simultaneously decommit and release a committed page.

        If the lpAddressparameter is not NULL, the function uses the lpAddressand dwSizeparameters 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 flAllocationTypeparameter. Otherwise, the function fails and none of the pages are allocated. This compatibility requirement does not preclude committing an already committed page.

        Requirements

        Runs on Versions Defined in Include Link to
        Windows CE OS 1.0 and later Winbase.h   Coredll.lib
        Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

        See Also

        GetLastError, GetSystemInfo, LocalAlloc, VirtualFree, VirtualProtect, VirtualQuery


        Last updated on Friday, May 26, 2006

        © 2004 Microsoft Corporation. All rights reserved.