Export (0) Print
Expand All
Expand Minimize
4 out of 5 rated this helpful - Rate this topic

VirtualQuery function

Retrieves information about a range of pages in the virtual address space of the calling process.

To retrieve information about a range of pages in the address space of another process, use the VirtualQueryEx function.

Syntax


SIZE_T WINAPI VirtualQuery(
  _In_opt_  LPCVOID lpAddress,
  _Out_     PMEMORY_BASIC_INFORMATION lpBuffer,
  _In_      SIZE_T dwLength
);

Parameters

lpAddress [in, optional]

A pointer to the base address of the region of pages to be queried. This value is rounded down to the next page boundary. To determine the size of a page on the host computer, use the GetSystemInfo function.

If lpAddress specifies an address above the highest memory address accessible to the process, the function fails with ERROR_INVALID_PARAMETER.

lpBuffer [out]

A pointer to a MEMORY_BASIC_INFORMATION structure in which information about the specified page range is returned.

dwLength [in]

The size of the buffer pointed to by the lpBuffer parameter, in bytes.

Return value

The return value is the actual number of bytes returned in the information buffer.

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

Remarks

VirtualQuery provides information about a region of consecutive pages beginning at a specified address that share the following attributes:

  • The state of all pages is the same (MEM_COMMIT, MEM_RESERVE, MEM_FREE, MEM_PRIVATE, MEM_MAPPED, or MEM_IMAGE).
  • If the initial page is not free, all pages in the region are part of the same initial allocation of pages created by a single call to VirtualAlloc, MapViewOfFile, or one of the following extended versions of these functions: VirtualAllocEx, VirtualAllocExNuma, MapViewOfFileEx, MapViewOfFileExNuma.
  • The access granted to all pages is the same (PAGE_READONLY, PAGE_READWRITE, PAGE_NOACCESS, PAGE_WRITECOPY, PAGE_EXECUTE, PAGE_EXECUTE_READ, PAGE_EXECUTE_READWRITE, PAGE_EXECUTE_WRITECOPY, PAGE_GUARD, or PAGE_NOCACHE).

The function determines the attributes of the first page in the region and then scans subsequent pages until it scans the entire range of pages or until it encounters a page with a nonmatching set of attributes. The function returns the attributes and the size of the region of pages with matching attributes, in bytes. For example, if there is a 40 megabyte (MB) region of free memory, and VirtualQuery is called on a page that is 10 MB into the region, the function will obtain a state of MEM_FREE and a size of 30 MB.

If a shared copy-on-write page is modified, it becomes private to the process that modified the page. However, the VirtualQuery function will continue to report such pages as MEM_MAPPED (for data views) or MEM_IMAGE (for executable image views) rather than MEM_PRIVATE. To detect whether copy-on-write has occurred for a specific page, either access the page or lock it using the VirtualLock function to make sure the page is resident in memory, then use the QueryWorkingSetEx function to check the Shared bit in the extended working set information for the page. If the Shared bit is clear, the page is private.

This function reports on a region of pages in the memory of the calling process, and the VirtualQueryEx function reports on a region of pages in the memory of a specified process.

Windows Phone 8: This API is supported.

Windows Phone 8.1: This API is supported.

Requirements

Minimum supported client

Windows XP [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2003 [desktop apps | Windows Store apps]

Header

WinBase.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

See also

GetSystemInfo
MapViewOfFile
Memory Management Functions
MEMORY_BASIC_INFORMATION
Virtual Memory Functions
VirtualQueryEx

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.