GetWriteWatch

The GetWriteWatch function retrieves the addresses of the pages that have been written to in a region of virtual memory.

UINT GetWriteWatch(
  DWORD dwFlags,          // write-tracking state
  PVOID lpBaseAddress,    // base address of region
  SIZE_T dwRegionSize,    // size of region
  PVOID  *lpAddresses,    // array of page addresses
  PULONG_PTR lpdwCount,   // number of addresses returned
  PULONG lpdwGranularity  // page size
); 

Parameters

dwFlags

[in] Indicates whether the function resets the write-tracking state. To reset the write-tracking state, set this parameter to WRITE_WATCH_FLAG_RESET. If this parameter is zero, GetWriteWatch does not reset the write-tracking state. For more information, see the following Remarks section.

lpBaseAddress

[in] Specifies the base address of the memory region for which to retrieve write-tracking information. This address must be in a memory region that was allocated by the VirtualAlloc function using MEM_WRITE_WATCH.

dwRegionSize

[in] Specifies the size, in bytes, of the memory region for which to retrieve write-tracking information.

lpAddresses

[out] Pointer to a buffer that receives an array of page addresses in the memory region. The addresses indicate the pages that have been written to since the region was allocated or the write-tracking state was reset.

lpdwCount

[in/out] On input, this variable indicates the size, in array elements, of the lpAddresses array. On output, the variable receives the number of page addresses returned in the array.

lpdwGranularity

[out] Pointer to a variable that receives the page size, in bytes.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero value.

Remarks

When you call the VirtualAlloc function to reserve or commit memory, you can specify MEM_WRITE_WATCH. This value causes the system to keep track of the pages in the committed memory region that have been written to. You can then call the GetWriteWatch function to retrieve the addresses of the pages that have been written to since the region was allocated or the write-tracking state was reset.

To reset the write-tracking state, set the WRITE_WATCH_FLAG_RESET value in the dwFlags parameter. Alternatively, you can call the ResetWriteWatch function to reset the write-tracking state. If you use ResetWriteWatch, however, you must ensure that no threads write to the region during the interval between the GetWriteWatch and ResetWriteWatch calls. Otherwise, there may be written pages that you fail to detect.

The GetWriteWatch function can be useful to profilers, debugging tools, or garbage collectors.

Requirements

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

See Also

Memory Management Overview, Memory Management Functions, ResetWriteWatch, VirtualAlloc