GetWsChangesEx function (psapi.h)

Article
10/13/2021

Retrieves extended information about the pages that have been added to the working set of the specified process since the last time this function or the InitializeProcessForWsWatch function was called.

Syntax

BOOL GetWsChangesEx(
  [in]      HANDLE                         hProcess,
  [out]     PPSAPI_WS_WATCH_INFORMATION_EX lpWatchInfoEx,
  [in, out] PDWORD                         cb
);

Parameters

[in] hProcess

A handle to the process. The handle must have the PROCESS_QUERY_INFORMATION access right. For more information, see Process Security and Access Rights.

[out] lpWatchInfoEx

A pointer to a user-allocated buffer that receives an array of
PSAPI_WS_WATCH_INFORMATION_EX structures. The array is terminated with a structure whose FaultingPc member is NULL.

[in, out] cb

The size of the lpWatchInfoEx buffer, in bytes.

Return value

If the function succeeds, the return value is nonzero.

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

The GetLastError function returns ERROR_INSUFFICIENT_BUFFER if the lpWatchInfoEx buffer is not large enough to contain all the working set change records; the buffer is returned empty. Reallocate a larger block of memory for the buffer and call again.

Remarks

The operating system uses one buffer per process to maintain working set change records. If more than one application (or multiple threads in the same application) calls this function with the same process handle, neither application will have a complete accounting of the working set changes because each call empties the buffer.

The operating system does not record new change records while it is processing the query (and emptying the buffer). This function sets the error code to NO_MORE_ENTRIES if a concurrent query is received while it is processing another query.

If the buffer becomes full, no new records are added to the buffer until this function or the InitializeProcessForWsWatch function is called. You should call GetWsChangesEx with enough frequency to prevent possible data loss. If records are lost, the array is terminated with a structure whose FaultingPc member is NULL and whose FaultingVa member is set to the number of records that were lost.

Starting with Windows 7 and Windows Server 2008 R2, Psapi.h establishes version numbers for the PSAPI functions. The PSAPI version number affects the name used to call the function and the library that a program must load.

If PSAPI_VERSION is 2 or greater, this function is defined as K32GetWsChangesEx in Psapi.h and exported in Kernel32.lib and Kernel32.dll. If PSAPI_VERSION is 1, this function is defined as GetWsChangesEx in Psapi.h and exported in Psapi.lib and Psapi.dll as a wrapper that calls K32GetWsChangesEx.

Programs that must run on earlier versions of Windows as well as Windows 7 and later versions should always call this function as GetWsChangesEx. To ensure correct resolution of symbols, add Psapi.lib to the TARGETLIBS macro and compile the program with -DPSAPI_VERSION=1. To use run-time dynamic linking, load Psapi.dll.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	psapi.h
Library	Kernel32.lib on Windows 7 and Windows Server 2008 R2; Psapi.lib (if PSAPI_VERSION=1) on Windows 7 and Windows Server 2008 R2; Psapi.lib on Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP
DLL	Kernel32.dll on Windows 7 and Windows Server 2008 R2; Psapi.dll (if PSAPI_VERSION=1) on Windows 7 and Windows Server 2008 R2; Psapi.dll on Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP