GetWriteWatch function (memoryapi.h)
Retrieves the addresses of the pages that are written to in a region of virtual memory.
64-bit Windows on Itanium-based systems: Due to the difference in page sizes, GetWriteWatch is not supported for 32-bit applications.
Syntax
UINT GetWriteWatch(
[in] DWORD dwFlags,
[in] PVOID lpBaseAddress,
[in] SIZE_T dwRegionSize,
[out] PVOID *lpAddresses,
[in, out] ULONG_PTR *lpdwCount,
[out] LPDWORD lpdwGranularity
);
Parameters
[in] dwFlags
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 0 (zero), GetWriteWatch does not reset the write-tracking state. For more information, see the Remarks section of this topic.
[in] lpBaseAddress
The base address of the memory region for which to retrieve write-tracking information.
This address must be in a memory region that is allocated by the VirtualAlloc function using MEM_WRITE_WATCH.
[in] dwRegionSize
The size of the memory region for which to retrieve write-tracking information, in bytes.
[out] lpAddresses
A 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 has been allocated or the write-tracking state has been reset.
[in, out] lpdwCount
On input, this variable indicates the size of the lpAddresses array, in array elements.
On output, the variable receives the number of page addresses that are returned in the array.
[out] lpdwGranularity
A pointer to a variable that receives the page size, in bytes.
Return value
If the function succeeds, the return value is 0 (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 that are written to in the committed memory region. You can call the GetWriteWatch function to retrieve the addresses of the pages that have been written to since the region has been allocated or the write-tracking state has been 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. However, if you use ResetWriteWatch, 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 do not detect.
The GetWriteWatch function can be useful to profilers, debugging tools, or garbage collectors.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2003 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | memoryapi.h (include Windows.h, Memoryapi.h) |
| Library | onecore.lib |
| DLL | Kernel32.dll |