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

Parameter	Description
`hFile`	A handle to the file or device (or a specific portion of it) that is to be read. This handle must have been created by the CreateFile function with the GENERIC_READ access right. For more information, see Remarks.
`lpBuffer`	A pointer to the buffer that receives the data from a file or device. If this parameter is NULL and `nNumberOfBytesToRead` is 0, the function returns TRUE and 0 bytes read.
`nNumberOfBytesToRead`	The maximum number of bytes to be read.
`lpNumberOfBytesRead`	A pointer to a 32-bit variable that receives the number of bytes read by this function. When using a handle that was opened with `FILE_FLAG_OVERLAPPED`, the value of this parameter is undefined until the `OVERLAPPED` operation has completed. If `lpOverlapped` is NULL, this parameter must not be NULL.
`lpOverlapped`	A pointer to an OVERLAPPED structure that is required for asynchronous I/O operations. See Remarks for more information. If `hFile` was opened with `FILE_FLAG_OVERLAPPED`, the `lpOverlapped` parameter must not be NULL. If `hFile` was opened without `FILE_FLAG_OVERLAPPED`, the value of this parameter is ignored.

Return Value

Value	Description
TRUE (non-zero)	The read operation was successful. If `lpOverlapped` is NULL, the value of the `lpNumberOfBytesRead` parameter is valid. If `lpOverlapped` is not NULL, the read operation is asynchronous. The final completion status is returned by GetLastError.
FALSE (zero)	The function failed. To get extended error information, call GetLastError.

Remarks

A handle to a file is obtained by calling the CreateFile function.

To read from a file, you must create the file handle with the GENERIC_READ access right.

If hFile is a handle to a communications resource, the function reads from the communications buffer. The size of the buffer is determined by the current settings of the device, as set by the CreateFile, GetCommState, and SetCommState functions.

If hFile is a handle to a console buffer, the behavior of ReadFile depends on whether the console is in front-buffer or back-buffer mode.

If the file was opened with FILE_FLAG_OVERLAPPED, the read operation is performed asynchronously. If the read operation is not completed immediately, ReadFile returns FALSE and GetLastError returns ERROR_IO_PENDING. When the operation is finished, the status is conveyed through the OVERLAPPED structure.

If the file was opened without FILE_FLAG_OVERLAPPED, the read operation is performed synchronously. The function does not return until the read operation has been completed or an error occurs.

If lpOverlapped is NULL, the read operation starts at the current file pointer position and the file pointer is advanced by the number of bytes read.

If lpOverlapped is not NULL, the read operation starts at the offset specified in the OVERLAPPED structure. The Offset and OffsetHigh members of the structure specify the byte offset within the file at which to read. The file pointer is not used by this function. If the read operation is not completed immediately, the Internal, InternalHigh, and Offset members of the OVERLAPPED structure are updated when the operation completes. The hEvent member must point to a valid event object.

If nNumberOfBytesToRead is zero, ReadFile returns TRUE and 0 bytes read, and the file pointer is not advanced.

If the file was opened with FILE_FLAG_NO_BUFFERING, you must align all data transfers with the sectors of the storage device.

A read operation that is initiated on a handle that has the FILE_FLAG_RANDOM_ACCESS flag set can occur at any point in the file.

A read operation that is initiated on a handle that has the FILE_FLAG_SEQUENTIAL_SCAN flag set should occur at or near the current file pointer position.

If the file pointer is beyond the end of the file, no bytes are read.

If lpOverlapped is NULL, and the file is opened with FILE_SHARE_READ, and another thread is using ReadFile to read from the file with an invalid buffer, ReadFile returns FALSE and GetLastError returns ERROR_INVALID_USER_BUFFER.

Important

When you are using a handle to a file that was opened with FILE_FLAG_OVERLAPPED, you should perform all reads and writes on that handle by using the overlapped I/O functions. If you call a function that performs synchronous I/O on that handle, the return value of that function is undefined, and the functions may fail.

Requirements