VirtualFreeVlm

[This is preliminary documentation and subject to change.]

The VirtualFreeVlm function decommits a memory region within the VLM address space of the specified process.

BOOL VirtualFreeVlm(
  HANDLE hProcess,   // process within which to free memory
  PVOID64 lpAddress, // address of region of pages to free
  DWORDLONG ullSize, // size in bytes of region
  DWORD dwFreeType   // type of free operation
);
 

Parameters

hProcess

Handle to a process. VirtualFreeVlm frees memory within the virtual address space of this process. The calling process must have had the PROCESS_VM_OPERATION flag set on a preceding call to the OpenProcess function, indicating virtual memory access to the target process, or VirtualFreeVlm fails.

lpAddress

Pointer to the base address of the region of the memory to free. The lpAddress parameter must point to the base address returned by the VirtualAllocVlm function when the region was reserved.

ullSize

Size, in bytes, of the region to release. If the dwFreeType parameter includes the MEM_RELEASE flag, the ullSize parameter must be zero. Otherwise, the region of affected pages includes all pages containing one or more bytes in the range from the value of lpAddress to the value of lpAddress plus the value of ullSize. This functionality means that freeing a 2-byte range straddling a page boundary causes both pages to be freed.

The release can be done only on the whole virtual space region reserved, whereas decommitting can be performed on subareas of a reserved and committed region. Decommitting an uncommitted area has no effect.

dwFreeType

Type of memory deallocation operation. You can specify one of the following flags.

Value	Meaning
MEM_DECOMMIT	Releases the specified region of pages. The pages enter the free state. If you specify this flag and ullSize contains zero, the entire region of pages is decommitted. Otherwise, you must specify lpAddress and ullSize values that are within the range returned by VirtualAllocVlm when the region was reserved. Note that MEM_DECOMMIT only results in the releasing of pages — the virtual address space remains reserved and cannot be reused unless a MEM_RELEASE flag is passed. For more information on reservation of virtual address space, see the discussion of the MEM_RESERVE flag in the VirtualAllocMem topic.
	An attempt to decommit an uncommitted page does not cause VirtualFreeVlm to fail. Thus, a range of committed or uncommitted pages can be decommitted without causing a failure.
MEM_RELEASE	Releases the specified region of pages. The pages enter the free state. If you specify this flag, ullSize must be zero and lpAddress must point to the base address returned by VirtualAllocVlm when the region was reserved. VirtualFreeVlm fails if either of these conditions is not met. If VirtualFreeVlm succeeds, both the pages and the range of virtual address space are relinquished.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

VirtualFreeVlm decommits memory allocated with VirtualAllocVlm. VirtualFreeVlm can perform one of the following operations:

• Decommit a region of committed or uncommitted pages.
• Release a region of reserved pages.
• Decommit and release a region of committed or uncommitted pages.

To release a region of pages, the entire range of pages must be in the same state (all reserved or all committed) and the entire region originally reserved by VirtualAllocVlm must be released at the same time. If only part of the pages in the original reserved region are committed, you must first call VirtualFreeVlm to decommit the committed pages and then call VirtualFreeVlm again to release the entire block.

Pages that have been released are free and available for subsequent allocation operations. Attempting to read from or write to a free page results in an access violation exception.

VirtualFreeVlm can decommit an uncommitted page; this means that a range of committed or uncommitted pages can be decommitted without having to worry about a failure. Decommitting a page releases its physical storage from memory. If a page is decommitted but not released, its state changes to reserved and it can be committed again by a subsequent call to VirtualAllocVlm. Attempting to read from or write to a reserved page results in an access violation exception.

The current state of the entire range of pages to be decommitted must be compatible with the type of free operation specified by the dwFreeType parameter. Otherwise, VirtualFreeVlm fails and no pages are released or decommitted.

QuickInfo

  Windows NT: Requires version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winbase.h.
  Import Library: Use kernel32.lib.

See Also

Memory Management Overview, Memory Management Functions, Very Large Memory (VLM), GlobalAlloc, GlobalFree, OpenProcess, VirtualFree, VirtualAllocVlm