ReadFile Function

Reads data from a specified file or input/output (I/O) device.

Syntax

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

Parameters

Return Value

If the function succeeds, and the lpOverlapped parameter is not NULL and the hEvent member of the OVERLAPPED structure is not NULL, the function returns TRUE. In this case, the hEvent is signaled when the read operation has been completed. If the function succeeds, and lpOverlapped is NULL or the hEvent member is NULL, the function returns TRUE and the number of bytes read is returned in the variable pointed to by lpNumberOfBytesRead. If the function fails, it returns FALSE. To get extended error information, call GetLastError.

Remarks

If the file has been opened with the FILE_FLAG_OVERLAPPED flag, the ReadFile function can be performed either synchronously or asynchronously.

• If lpOverlapped is NULL or if the hEvent member of the OVERLAPPED structure is NULL, the ReadFile function performs a synchronous read. The function does not return until the data has been read or an error occurs.
• If lpOverlapped is not NULL and the hEvent member is not NULL, the read operation is performed asynchronously. The function returns FALSE and GetLastError returns ERROR_IO_PENDING if the read operation cannot be completed immediately. In this case, the hEvent member is signaled when the read operation has been completed.

If the file handle is opened with FILE_SHARE_READ or FILE_SHARE_WRITE, other processes can open the file to read or write, potentially affecting the data read by ReadFile.

The file pointer is advanced by the number of bytes read. If the file pointer is beyond the end of the file, ReadFile reads zero bytes and returns TRUE, with *lpNumberOfBytesRead set to 0.

To read data from a file opened for asynchronous I/O, use a separate thread to perform the read operation or use the completion routine notification capability of the OVERLAPPED_COMPLETION_ROUTINE.

If lpNumberOfBytesRead is NULL, the function can fail.

If lpOverlapped is NULL, the lpNumberOfBytesRead parameter must be valid.

If hFile is a handle to a console buffer, the ReadFile function reads input from the console buffer.

If hFile is a handle to a communications resource, the ReadFile function behaves according to the settings of the communications resource specified by the CreateFile function.

If the file is opened with CreateFile and the FILE_ATTRIBUTE_NORMAL attribute, ReadFile reads from the file normally.

If the file is opened with CreateFile and the FILE_FLAG_NO_BUFFERING attribute, you must read data in multiples of the sector size of the underlying device. You also must align the buffer and the file offset.

Examples

For a code example, see Reading and Writing Files.

Requirements

See Also

CreateFile
CloseHandle
GetFileSizeEx
SetFilePointer
WriteFile
OVERLAPPED
Device Input and Output Control
File Management Functions