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.
A version of this page is also available for
4/8/2010

This function releases or decommits, or both, a region of pages within the virtual address space of the calling process.

Syntax 

BOOL VirtualFree(
  LPVOID 
lpAddress,
  DWORD 
dwSize,
  DWORD 
dwFreeType
);

Parameters

lpAddress

[in] Pointer to the base address of the region of pages to be freed.

If the dwFreeTypeparameter includes the MEM_RELEASE flag, this parameter must be the base address returned by the VirtualAllocfunction when the region of pages was reserved.

dwSize

[in] Specifies the size, in bytes, of the region to be freed.

If the dwFreeTypeparameter includes the MEM_RELEASE flag, this parameter must be zero.

Otherwise, the region of affected pages includes all pages containing one or more bytes in the range from the lpAddressparameter to lpAddressplus dwSize. This means that a 2-byte range straddling a page boundary causes both pages to be freed.

dwFreeType

[in] Specifies the type of free operation.

You can specify one of the following flags.

Value Description

MEM_DECOMMIT

Decommits the specified region of committed pages.

An attempt to decommit an uncommitted page does not cause the function to fail. This means that a range of committed or uncommitted pages can be decommitted without being concerned about a failure.

MEM_RELEASE

Releases the specified region of reserved pages.

If this flag is specified, the dwSizeparameter must be zero or the function fails.

Return Value

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

VirtualFreecan 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 range of pages must be in the same state (all reserved or all committed) and the entire region originally reserved by the VirtualAllocfunction must be released at the same time.

If only part of the pages in the original reserved region are committed, first call VirtualFreeto decommit the committed pages and then call VirtualFreeagain to release the entire block.

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

VirtualFreecan decommit an uncommitted page. This means that a range of committed or uncommitted pages can be decommitted without being concerned about a failure.

Decommitting a page releases its physical storage, either in memory or in the paging file on disk. If a page is decommitted but not released, its state changes to reserved and it can be committed again by a subsequent call to VirtualAlloc.

Attempting to read from or write to a reserved page results in an access violation exception.

The current state of the range of pages must be compatible with the type of free operation specified by the dwFreeTypeparameter. Otherwise, the function fails and no pages are released or decommitted.

Requirements

Header winbase.h
Library coredll.lib
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also