Windows API Reference

VirtualAlloc Function

The VirtualAlloc function reserves, commits, or changes the state of a region of pages in the virtual address space of the calling process.

Syntax

LPVOID VirtualAlloc(
  [in, optional] LPVOID lpAddress,
  [in]           SIZE_T dwSize,
  [in]           DWORD  flAllocationType,
  [in]           DWORD  flProtect
);

Parameters

  • lpAddress [in, optional]

    The starting address of the region of memory to allocate. If this parameter is NULL, the system determines where to allocate the region.

  • dwSize [in]

    The size of the region of memory to allocate, in bytes. If lpAddress is NULL, this parameter is the size of the region to allocate. If lpAddress is not NULL, this parameter is the number of bytes of memory to reserve or commit.

    If dwSize is greater than the number of free pages that are contiguous starting at lpAddress, the function fails.

    If lpAddress is not NULL, the pages starting at lpAddress and ending at lpAddress+dwSize are allocated. If lpAddress is NULL, the system allocates a region of pages of at least dwSize bytes.

  • flAllocationType [in]

    The type of memory allocation. This parameter can be one of the following values:

    • MEM_COMMIT: Allocates physical memory for the specified region of pages.
    • MEM_RESERVE: Reserves a range of the process's virtual address space without any (physical) storage associated with it.
    • MEM_RESET (Windows 7 and later): Indicates that data in the memory range specified by lpAddress and dwSize is no longer of interest. The pages should not be written to the paging file. In the future, the calling process may read any page in the range. This can return a valid page of zero fill rather than the page's actual contents. This flag cannot be used with any other allocation type flag.
    • MEM_RESET_UNDO (Windows 7 and later): Indicates that the caller wishes to undo the effects of a previous call to VirtualAlloc with MEM_RESET. If the pages have not yet been reused, this flag can return the original page contents. This flag cannot be used with any other allocation type flag.
    • MEM_LARGE_PAGES (Windows 7 and later): Allocates memory using large page support.
    • MEM_PHYSICAL: Allocates physical memory.
    • MEM_TOP_DOWN: Allocates memory using MEM_RESERVE and MEM_COMMIT. The system allocates memory at the highest possible address.

    You must specify either MEM_COMMIT or MEM_RESERVE. You can also combine MEM_COMMIT and MEM_RESERVE with MEM_TOP_DOWN.

  • flProtect [in]

    The memory protection for the region of pages to be allocated. This parameter can be one of the following values:

    • PAGE_EXECUTE: Enables execution from the allocated region of memory. The region cannot be written to.
    • PAGE_EXECUTE_READ: Enables execution from, and reading of, the allocated region of memory.
    • PAGE_EXECUTE_READWRITE: Enables execution of, reading of, and writing to the allocated region of memory.
    • PAGE_EXECUTE_WRITECOPY: Enables execution of, reading of, and writing to the allocated region of memory. Copy-on-write protection is enforced.
    • PAGE_NOACCESS: Enables no access to the allocated region of memory. Any attempt to read from or write to the region generates a protection fault.
    • PAGE_READONLY: Enables reading of the allocated region of memory. Any attempt to write to the region generates a protection fault.
    • PAGE_READWRITE: Enables reading and writing of the allocated region of memory.
    • PAGE_WRITECOPY: Enables reading and writing of the allocated region of memory. Copy-on-write protection is enforced.

    This parameter must not be PAGE_NOACCESS if flAllocationType is MEM_COMMIT. If flAllocationType is MEM_RESERVE, this parameter must be PAGE_NOACCESS.

Return Value

If the function succeeds, the return value is a pointer to 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.

Important Notes

  • When using MEM_RESERVE and MEM_COMMIT together, the initial allocation might be larger than requested if the system finds a suitable region starting at a higher address.
  • The system is not aware of the memory until you call VirtualAlloc.
  • Use VirtualFree to deallocate or uncommit memory allocated by VirtualAlloc.

Example

The following code snippet demonstrates how to allocate a region of memory with read and write permissions.

#include <windows.h>
#include <stdio.h>

int main() {
    LPVOID lpAddress;
    SIZE_T dwSize = 1024; // Allocate 1KB
    DWORD flAllocationType = MEM_COMMIT | MEM_RESERVE;
    DWORD flProtect = PAGE_READWRITE;

    lpAddress = VirtualAlloc(NULL, dwSize, flAllocationType, flProtect);

    if (lpAddress == NULL) {
        fprintf(stderr, "VirtualAlloc failed. Error: %lu\n", GetLastError());
        return 1;
    }

    printf("Memory allocated successfully at address: %p\n", lpAddress);

    // You can now use the allocated memory
    // ...

    // Deallocate the memory
    if (VirtualFree(lpAddress, 0, MEM_RELEASE) == 0) {
        fprintf(stderr, "VirtualFree failed. Error: %lu\n", GetLastError());
        return 1;
    }

    printf("Memory deallocated successfully.\n");

    return 0;
}

See Also