2.1.4.1.12 ReadFile

1 Description
2 Syntax
3 Parameters
4 Return
5 Examples
6 Remark
7 See Also
8 Header to Include
9 Reference

Description

Reads data from a file, and starts at the position that the file pointer indicates. You can use this function for both synchronous and asynchronous operations.

Syntax

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

Parameters

hFile: [input] A handle to the file to be read.

The file handle must be created with the GENERIC_READ access right. For more information, see File Security and Access Rights.

For asynchronous read operations, hFile can be any handle that is opened with the FILE_FLAG_OVERLAPPED flag by the CreateFile function, or a socket handle returned by the socket or accept function.

lpBuffer: [output] A pointer to the buffer that receives the data read from a file.
nNumberOfBytesToRead: [input] The maximum number of bytes to be read.
lpNumberOfBytesRead: [output] A pointer to the variable that receives the number of bytes read.
lpOverlapped: [input] A pointer to an OVERLAPPED structure.

This structure is required if hFile is created with FILE_FLAG_OVERLAPPED.

If hFile is opened with FILE_FLAG_OVERLAPPED, the lpOverlapped parameter must not be NULL. It must point to a valid OVERLAPPED structure.

If hFile is created with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the function can report incorrectly that the read operation is complete.

Return

The ReadFile function returns when one of the following conditions occur:

A write operation completes on the write end of the pipe. The number of bytes requested is read. An error occurs.

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero (0). To get extended error information, call GetLastError.

Examples

#include <mswin.h>
// Attempt a synchronous read operation.
void ReadFile_Ex1(HANDLE hFile, LPVOID lpBuffer, DWORD nBytesToRead, DWORD nBytesRead)
{
	BOOL bResult = ReadFile(hFile, 
                   lpBuffer, 
                   nBytesToRead, 
                   &nBytesRead, 
                   NULL) ;
	// Check for the end of file. 
	if (bResult &&  nBytesRead == 0) 
	{ 
		// This is the end of the file. 
	} 
}

Remark

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

An application must meet the following specific requirements when working with files that are opened with FILE_FLAG_NO_BUFFERING:

File access must begin at byte offsets within the file that are integer multiples of the volume sector size. To determine the sector size of a volume, call the GetDiskFreeSpace function. File access must be for numbers of bytes that are integer multiples of the volume sector size. For example, if the sector size is 512 bytes, an application can request read and write operations of 512, 1024, 1536, or 2048 bytes, but not of 335, 981, or 7171 bytes. Buffer addresses for read and write operations must be sector aligned (that is, aligned on addresses in memory that are integer multiples of the volume sector size). One way to sector align buffers is to use the VirtualAlloc function to allocate the buffers. This function allocates memory that is aligned on addresses that are integer multiples of the system page size. Because both page and volume sector sizes are powers of 2 (two), memory aligned by multiples of the system page size is also aligned by multiples of the volume sector size.

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