FreeUserPhysicalPages function (memoryapi.h)

Article
02/22/2024

Frees physical memory pages that are allocated previously by using AllocateUserPhysicalPages or AllocateUserPhysicalPagesNuma. If any of these pages are currently mapped in the Address Windowing Extensions (AWE) region, they are automatically unmapped by this call. This does not affect the virtual address space that is occupied by a specified Address Windowing Extensions (AWE) region.

64-bit Windows on Itanium-based systems: Due to the difference in page sizes, FreeUserPhysicalPages is not supported for 32-bit applications.

Syntax

BOOL FreeUserPhysicalPages(
  [in]      HANDLE     hProcess,
  [in, out] PULONG_PTR NumberOfPages,
  [in]      PULONG_PTR PageArray
);

Parameters

[in] hProcess

The handle to a process.

The function frees memory within the virtual address space of this process.

[in, out] NumberOfPages

The size of the physical memory to free, in pages.

On return, if the function fails, this parameter indicates the number of pages that are freed.

[in] PageArray

A pointer to an array of page frame numbers of the allocated memory to be freed.

Return value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. In this case, the NumberOfPages parameter reflect how many pages have actually been released. To get extended error information, call GetLastError.

Remarks

In a multiprocessor environment, this function maintains coherence of the hardware translation buffer. When this function returns, all threads on all processors are guaranteed to see the correct mapping.

To compile an application that uses this function, define the _WIN32_WINNT macro as 0x0500 or later. For more information, see Using the Windows Headers.

Examples

For an example, see AWE Example.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	memoryapi.h (include Windows.h, Memoryapi.h)
Library	onecore.lib
DLL	Kernel32.dll