ReadFile

The ReadFile function reads data from a file. The function starts reading data at the position indicated by the file pointer. After the read completes, the file pointer is adjusted by the number of bytes actually read, except when the file handle is created with FILE_FLAG_OVERLAPPED. If the file handle was created for overlapped I/O, the application must adjust the position of the file pointer after the read.

Parameters

hFile

Identifies the file that is to be read. The file handle must have been created with GENERIC_READ access to the file.

lpBuffer

Points to the buffer to receive the data read from the file.

nNumberOfBytesToRead

Specifies the number of bytes to read from the file.

lpNumberOfBytesRead

Specifies the number of bytes read by this call. ReadFile sets this value to zero before doing any work or error checking. If this parameter is zero when ReadFile returns TRUE on a named pipe, then the other end of the message mode pipe called WriteFile with nNumberOfBytesToWrite set to zero.

lpOverlapped

Points to an OVERLAPPED structure. This structure is required if hFile was created with FILE_FLAG_OVERLAPPED.

If hFile was created with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the current position of the file pointer is unknown, ReadFile returns FALSE, and GetLastError returns ERROR_INVALID_PARAMETER.

If hFile was not created with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the read operation starts at the current file position and ReadFile does not return until the operation completes.

If hFile was created with FILE_FLAG_OVERLAPPED and lpOverlapped is not NULL, the read operation starts at the offset specified in the OVERLAPPED structure and ReadFile may return before the read operation completes. In this case, ReadFile returns FALSE and the GetLastError function returns ERROR_IO_PENDING. This allows the caller to continue processing while the read operation completes. The event specified in the OVERLAPPED structure is set to the signalled state upon completion of the read operation.

If hFile was not created with FILE_FLAG_OVERLAPPED and lpOverlapped is not NULL, the read operation starts at the offset specified in the OVERLAPPED structure and ReadFile does not return until the read operation completes.

The OVERLAPPED structure has the following form:

typedef struct _OVERLAPPED { /* o */

DWORD Internal;

DWORD InternalHigh;

DWORD Offset;

DWORD OffsetHigh;

HANDLE hEvent;

} OVERLAPPED;

typedef OVERLAPPED *LPOVERLAPPED;

Return Value

The return value is TRUE if the function was successful, or FALSE if an error occurred. Use the GetLastError function to obtain extended error information.

If the return value is TRUE and the number of bytes read is zero, the file pointer was beyond the current end of the file at the time of the read.

Comments

This function will fail if part of the file is locked by another process and the read overlaps the locked portion.

Characters can be read from the console input buffer using ReadFile with a handle to console input. The exact behavior of the function is determined by the console mode.

If a named pipe is being read in message mode and the next message is longer than nNumberOfBytesToRead, ReadFile will return FALSE and GetLastError will return ERROR_MORE_DATA. The remainder of the message may be read by a subsequent ReadFile or PeekNamedPipe.

When reading from a communications device, ReadFile will normally wait until the requested number of bytes have been received. SetCommTimeouts can be used to force ReadFile to return with fewer bytes.

See Also

CreateFile, GetOverlappedResult, PeekNamedPipe, ReadFileEx, SetCommTimeouts, WriteFile, OVERLAPPED