AllocateUserPhysicalPages

The AllocateUserPhysicalPages function allocates physical memory pages to be mapped and unmapped within any Address Windowing Extensions (AWE) region of the specified process.

BOOL AllocateUserPhysicalPages(
  HANDLE hProcess,           // handle to process
  PULONG_PTR NumberOfPages,  // number of pages
  PULONG_PTR UserPfnArray    // address of storage
);

Parameters

hProcess

[in] Handle to a process. The function allocates memory within the virtual address space of this process. The user executing the calling application must have Lock Pages in Memory privileged access to this process. If you do not, the function fails.

NumberOfPages

[in/out] Specifies the size, in pages, of the physical memory to allocate. Use the GetSystemInfo function to determine the page size of the computer. This parameter also returns the number of pages actually allocated, which may be less than the number requested.

UserPfnArray

[out] Specifies the virtual address in which to store the page frame numbers of the allocated memory. The size of the memory allocated should be at least NumberOfPages times the size of the data type ULONG_PTR.

Do not attempt to modify this buffer. It contains operating system data, corruption of which could be catastrophic. There is no information in it that is useful to your application.

Return Values

If the function succeeds, the return value is TRUE. Fewer pages than requested may actually be allocated. The caller must check the value of the NumberOfPages parameter on return to see how many pages were allocated. All allocated page frame numbers are sequentially placed in the memory pointed to by the UserPfnArray parameter.

If the function fails, the return value is FALSE and no frames are allocated. To get extended error information, call GetLastError.

Remarks

The AllocateUserPhysicalPages function is used to allocate physical memory. Memory allocated by this function must be physically present in the system. Once allocated, it is locked down and unavailable to the rest of the virtual memory management system of Windows 2000.

Note that a given physical page cannot be simultaneously mapped at more than one virtual address.

Physical pages can reside at any physical address. You should make no assumptions about the contiguity of the physical pages.

Use the GetSystemInfo function to determine the page size of the computer.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.

See Also

Memory Management Overview, Memory Management Functions, Address Windowing Extensions, MapUserPhysicalPages, MapUserPhysicalPagesScatter, FreeUserPhysicalPages, GetSystemInfo