Reads data from a file, starting at the position indicated by the file pointer. After the read operation is complete, the file pointer is adjusted by the number of bytes actually read.

BOOLEAN ReadFile(
    HANDLE hFile,
    LPVOID lpBuffer,
    DWORD nNumberOfBytesToRead,
    LPDWORD lpNumberOfBytesRead,
    LPOVERLAPPED lpOverlapped
);

Parameters

hFile

Handle to the file to read. The file handle must be created with GENERIC_READ access to the file.

lpBuffer

Pointer to the buffer that receives the data read from the file.

nNumberOfBytesToRead

Number of bytes to read from the file.

lpNumberOfBytesRead

Pointer to the number of bytes read. ReadFile sets this value to zero before taking action or checking errors.

lpOverlapped

Ignored.

Remarks

CAUTION: Applications must not read from, write to, reallocate, or free the input buffer that a read operation is using until the read operation completes. Accessing the input buffer while a read operation uses the buffer may lead to corruption of the data read into that buffer.

When a read operation reaches the end of a file, ReadFile returns TRUE and sets *lpNumberOfBytesRead to zero. The following code sample shows a test for end-of-file.

// Attempt a synchronous read operation. 
bResult = ReadFile(hFile, &inBuffer, nBytesToRead, &nBytesRead, NULL) ; 
// Check for end of file. 
if (bResult &&  (nBytesRead == 0) ) 
{ 
    // you are at the end of the file. 
}

Return Values

TRUE

Success.

FALSE

Failure. For extended error information, see GetLastError.

Requirements

Note

This function operates in the real-time portion of your application.

See Also

CreateFile, WriteFile, iwin32 API, iwin32 Overview