VirtualQueryVlm

[This is preliminary documentation and subject to change.]

The VirtualQueryVlm function provides information about a range of pages within the virtual address space of a specified process.

DWORD VirtualQueryVlm(
  HANDLE hProcess,    // handle of process
  PVOID64 lpAddress,  // address of region
  PMEMORY_BASIC_INFORMATION_VLM lpBuffer,
                      // address of information buffer
  DWORD dwLength      // size of buffer
);
 

Parameters

hProcess

Handle to the process whose memory information is to be queried. The handle must have PROCESS_QUERY_INFORMATION access.

lpAddress

Pointer to the base address of the region of pages to be queried. This value is rounded down to the next page boundary. The address specified must be 64 bits and can therefore be used to access memory for any process allocated using the VirtualAllocVlm function. If the address specified is zero, then the system sets the address to the lowest possible VLM address and begins the query from this new address.

lpBuffer

Pointer to a MEMORY_BASIC_INFORMATION_VLM structure in which information about the specified page range is returned.

dwLength

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

Return Values

If the function succeeds, the return value is the actual number of bytes returned in the buffer in the lpBuffer parameter.

If the function fails, the return value is zero.

Remarks

VirtualQueryVlm 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. In other words, all pages have the MEM_COMMIT, MEM_RESERVE, MEM_FREE, MEM_PRIVATE, MEM_MAPPED, or MEM_IMAGE flag set.
• If the initial page is not free, all pages in the region are part of the same initial allocation of pages reserved by a call to the VirtualAllocVlm function.
• The access type of all pages is the same. In other words, all pages have the PAGE_READONLY, PAGE_READWRITE, PAGE_NOACCESS, PAGE_WRITECOPY, PAGE_EXECUTE, PAGE_EXECUTE_READ, PAGE_EXECUTE_READWRITE, PAGE_EXECUTE_WRITECOPY, PAGE_GUARD, or PAGE_NOCACHE flag set.

VirtualQueryVlm determines the attributes of the first page in the region and then scans subsequent pages. This scan continues until VirtualQueryVlm either scans the entire range of pages or encounters a page with attributes that do not match those of the first page. VirtualQueryVlm returns the attributes and the size, in bytes, of the region of pages with attributes that match those of the first page. For example, if there is a 40-MB region of free memory and VirtualQueryVlm is called for a page that is 10 MB into the region, VirtualQueryVlm retrieves a state of MEM_FREE and a size of 30 MB.

VirtualQueryVlm is identical to the VirtualQueryEx function, except that it provides information about memory allocated using VirtualAllocVlm.

VirtualQueryVlm sets all members in the lpBuffer MEMORY_BASIC_INFORMATION_VLM structure in all cases because certain members in the structure depend on the values of other members. For example, the Type member is not filled for a MEM_FREE region, and the Protect member is not filled if region queried is not committed to memory. All members are filled with useful information wherever possible.

QuickInfo

  Windows NT: Requires version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winbase.h.
  Import Library: Use kernel32.lib.

See Also

Memory Management Overview, Memory Management Functions, Very Large Memory (VLM), GetSystemInfo, MEMORY_BASIC_INFORMATION_VLM, VirtualAllocVlm, VirtualQueryEx, VirtualQuery