VirtualFree

A region of pages within the virtual address space of a calling process can be decommitted and/or released with the VirtualFree function:

Parameters

lpAddress

A pointer that specifies the base address of the region of pages to be freed.

dwSize

A number that specifies the size in bytes of the freed region. It will be rounded up to the next host-page-size boundary. If this value is zero and the lpAddress parameter is the starting address of the allocated region, the complete range of pages allocated together is freed or decommitted. This value must be zero if dwFreeType is set to MEM_RELEASE; if it is not, the function will fail, returning FALSE.

dwFreeType

A set of flags that describes the type of free that is to be performed for the specified region of pages. One of the following:

Return Value

The return value is TRUE if the function successfully freed the specified memory. Otherwise it is FALSE, in which case extended error information is available from the GetLastError function.

Comments

This function can be used to decommit a region of previously committed pages (i.e. from an allocation of virtual memory), to release a region of previously reserved pages, and to decommit and release a region of previously committed pages.

Process address map entries are scanned from the base address upward until the entire range of pages can be freed or until a failure occurs. If the entire range cannot be freed, an appropriate status value is returned and no pages are freed.

Each page in the process virtual address space can be in one of three states:

1.Free – Not committed or reserved and inaccessible

2.Committed – Allocated backing storage with access controlled by a protection code

3.Reserved – Reserved, not committed, and inaccessible

For each of these states, each page considered for allocation is handled as follows:

1.Free – A page that is free cannot be released or decommitted.

2.Committed – A page that is committed can be released and/or decommitted.

3.Reserved – A page that is reserved can be released but cannot be decommitted.

If the desired type of free is allowed for the specified dwSize, then page attributes are established as necessary in the process address map, and the current length of the freed region is updated.

If the desired type of free cannot be performed on the entire range, then an appropriate status value is returned and none of the specified region is freed.

Decommitting a page causes the backing storage for the page to be released to the appropriate paging file and the address map entry for the corresponding page to be returned to the reserved state.

Decommitted and released pages are given a protection value of no access.

See Also

VirtualAlloc, GlobalAlloc, GlobalFree, HeapAlloc, HeapFree, LocalAlloc, LocalFree