ReadFile

ReadFile reads data from a file, starting at the position the file pointer indicates. After the read operation has been completed, the file pointer is adjusted by the number of bytes read.

Syntax

BOOL ReadFile(
    [in]                  HANDLE hFile,
    [out]                 LPVOID lpBuffer,
    [in]                  DWORD nNumberOfBytesToRead,
    [out, optional]       LPDWORD lpNumberOfBytesRead,
    [in, out, optional]   LPOVERLAPPED lpOverlapped
);

Parameters

[in] hFile

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

[out] lpBuffer

A pointer to the buffer that receives the data read from the file.

[in] nNumberOfBytesToRead

The number of bytes to be read from the file.

[out, optional] lpNumberOfBytesRead

A pointer to the number of bytes read. ReadFile sets this value to zero before doing any work or error checking.

[in, out, optional] lpOverlapped (not supported)

This parameter must be set to NULL.

Return Value

If the function succeeds, it returns TRUE. If the function fails, it returns FALSE. Call GetLastError to get extended error information.

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

Remarks

ReadFile returns when the number of bytes requested has been read, or an error occurs.

If another process locks part of the file and the read operation overlaps the locked portion, this function fails.

Applications must not read from or write to the input buffer that a read operation is using until the read operation completes. Premature access to the input buffer may corrupt the data read into that buffer.

When a synchronous read operation reaches the end of a file, ReadFile returns TRUE and sets *lpNumberOfBytesRead to zero.

Requirements

See Also:

• CreateFile
• WriteFile