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.

Answer 3

I'm guessing that the area might be accessible in terms of permissions, but an error in a page fault might only allow part of it to be read. That's just a guess though.

Edit: See this page: ReactOS - STATUS_PARTIAL_COPY

> // Otherwise, we failed  probably during the move

It seems like any problem that's out of the control of the function might return this error code.

Answer 4

There's an inherent race condition. Copies aren't instant. Sure, the function checks up front whether it's likely to succeed, but it is possible that the memory range becomes unmapped during the copy. It's another running process you're looking at, after all, quite likely unaware ofyour ongoing ReadProcessMemory() .

(Remus Rusanu also hinted at such a partial copy, but suggested a corrupted process as the root cause, not a race.)

Answer 5

Another possibility, aside from 9000's answer is that the parameter is there for future expansion purposes. Perhaps at one point (and maybe even now) there were plans to provide ReadProcessMemory implementations that could partially fail so the out parameter was put there for that reason. This would be a (not particularly good) way to avoid the whole API/APIEx/APIEx2/whatever problem that Win32's APIs have laboured under for years.