Why does ReadProcessMemory have `lpNumberOfBytesRead`?

Question

From ReadProcessMemory in MSDN:

lpBaseAddress [in]:
A pointer to the base address in the specified process from which to read. Before any data transfer occurs, the system verifies that all data in the base address and memory of the specified size is accessible for read access, and if it is not accessible the function fails.

nSize [in]:
The number of bytes to be read from the specified process.

lpNumberOfBytesRead [out]
A pointer to a variable that receives the number of bytes transferred into the specified buffer. If lpNumberOfBytesRead is NULL, the parameter is ignored.

So.. ReadProcessMemory can only completely succeed or completely fail. And the size is obviously known to the caller -- had to pass it in to make the call. Why have the lpNumberOfBytesRead?

Answer 1

From winerror.h:

//
// MessageId: ERROR_PARTIAL_COPY
//
// MessageText:
//
//  Only part of a ReadProcessMemory or WriteProcessMemory request was completed.
//
#define ERROR_PARTIAL_COPY               299L

ReadProcessMemory would return FALSE and GetLastError would return ERROR_PARTIAL_COPY when the copy hits a page fault. This is a common scenario in dumpers, which have to work on a potentially corrupted process so they can't be sure if the requested area is valid or not (the pointer they chased to get the start address could be corrupted and point to la-la-land), but they would still like to copy as much as possible into the dump.

Answer 2

Maybe in some previous API versions this function did not completely fail, but could return partial results. So the out parameter is kept for compatibility, but newer programs can pass a NULL and ignore it.