VirtualAlloc Function

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

Description

The VirtualAlloc function reserves, commits, or changes the state of a region of pages in the virtual address space of the calling process. It can also optionally place the new region within a specified memory range, specify whether pages that are opened with write access can be written to, and control the access permissions of the pages.

Syntax

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

Parameters

Parameter	Description
`lpAddress`	`lpAddress` [in, optional] A pointer to the base address of the region of pages to be allocated. If this parameter is `NULL`, the system determines where to allocate the region.
`dwSize`	`dwSize` [in] The size, in bytes, of the region of pages to be allocated. If `lpAddress` is not `NULL`, the pages pointed to by `lpAddress` and any pages within the byte range specified by `dwSize` are allocated. If `lpAddress` is `NULL`, the system allocates a region of pages up to `dwSize` bytes. If `dwSize` is greater than 0, it is rounded up to the nearest multiple of the page size. The actual number of bytes allocated for the region is therefore a multiple of the page size.
`flAllocationType`	`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. `MEM_RESERVE`: Reserves a range of the process's virtual address space without any commitment of physical storage. `MEM_RESET`: Indicates that data in the memory range specified by `lpAddress` and `dwSize` is no longer of interest. The pages should not be committed under demand paging. This is a hint to the system. `MEM_RESET_UNDO`: Undoes the effect of `MEM_RESET`. `MEM_LARGE_PAGES`: Allocates memory using large page support. `MEM_PHYSICAL`: Allocates physical memory. `MEM_TOP_DOWN`: Allocates memory at the highest possible address. You can also combine `MEM_COMMIT` and `MEM_RESERVE`.
`flProtect`	`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. `PAGE_EXECUTE_READ`: Enables execution and read-only access to the allocated region of memory. `PAGE_EXECUTE_READWRITE`: Enables execution, read, and write access to the allocated region of memory. `PAGE_EXECUTE_WRITECOPY`: Enables execution, read, and write access to the allocated region of memory. Changes to the underlying pages are copy-on-write. `PAGE_NOACCESS`: No access to the allocated region of memory. Any attempt to read from or write to the region generates a protection fault. `PAGE_READONLY`: Read-only access to the allocated region of memory. Any attempt to write to the region generates a protection fault. `PAGE_READWRITE`: Read-only and write access to the allocated region of memory. `PAGE_WRITECOPY`: Read-only and write access to the allocated region of memory. Changes to the underlying pages are copy-on-write. `PAGE_TARGETS_INVALID`: Marks all physical pages in the specified range as invalid. `PAGE_TARGETS_NO_UPDATE`: Marks all physical pages in the specified range as not being updated. You can also use the `PAGE_GUARD` flag in conjunction with other page protection flags. This flag enables guard pages. Any access to a currently guarded page triggers a STATUS_GUARD_PAGE_VIOLATION exception and the page's guard attribute is cleared. The next access to the page will succeed without protection violation.

Return Value

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 is used to reserve or commit a region of memory pages.
For MEM_RESERVE, flProtect can be PAGE_NOACCESS.
For MEM_COMMIT, flProtect can be any of the PAGE_XXX values except PAGE_NOACCESS.
When committing pages, the memory type specified by flAllocationType must be compatible with the memory type of the region already specified by lpAddress.
If lpAddress is not NULL, the starting address of the block of pages to be allocated is within the range of addresses specified by lpAddress when the region was created by a previous call to VirtualAlloc.
To decommit a region of pages, call VirtualFree.
If the system cannot commit the region of memory or if lpAddress is invalid, the function fails.

Example

The following code example allocates a region of memory and then commits it.

// Allocate 4K of memory
LPVOID lpMsgBuf = VirtualAlloc(
    NULL,                   // System chooses the address
    4096,                   // Size of allocation
    MEM_RESERVE | MEM_COMMIT, // Reserve and commit
    PAGE_READWRITE          // Read-write access
);

if (lpMsgBuf == NULL)
{
    // Handle error
    printf("VirtualAlloc failed: %d\n", GetLastError());
    return 1;
}

// Use the allocated memory...

// Free the allocated memory
if (!VirtualFree(lpMsgBuf, 0, MEM_RELEASE))
{
    // Handle error
    printf("VirtualFree failed: %d\n", GetLastError());
    return 1;
}

Microsoft Docs