Reads data from a file or input buffer.
BOOL ReadFile(
HANDLE hFile,
LPVOID lpBuffer,
DWORD nNumberOfBytesToRead,
LPDWORD lpNumberOfBytesRead,
LPOVERLAPPED lpOverlapped
);
hFile
A handle to the file or device that is to be read.
lpBuffer
A pointer to the buffer that receives the data read from a file. If this pointer is NULL and nNumberOfBytesToRead is 0, the function returns TRUE and reads zero bytes.
nNumberOfBytesToRead
The maximum number of bytes to be read. This value must not be greater than the size of the buffer specified by lpBuffer.
lpNumberOfBytesRead
A pointer to a 32-bit unsigned integer variable that receives the number of bytes actually read by the function. When using OVERLAPPED structure, this parameter can be NULL. If this parameter is NULL, and the function returns FALSE, the reason for failure is provided by GetLastError.
lpOverlapped
A pointer to an OVERLAPPED structure that is used for asynchronous I/O operations. For files opened with the FILE_FLAG_OVERLAPPED flag, this parameter is required. If not using overlapped I/O, this parameter can be NULL.
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
If lpOverlapped is NULL, lpNumberOfBytesRead will contain the number of bytes read. If lpOverlapped is not NULL, the number of bytes read is stored in the Internal member of the OVERLAPPED structure upon completion of the operation.
The ReadFile function retrieves data from a file or device specified by a handle. The read operation starts at the position indicated by the file pointer of the handle. For certain types of handles, such as console input, the function reads data according to the specific device's behavior.
If the file handle is associated with a communications device, ReadFile reads data according to the current communications timeouts. Timeouts are determined by the COMMTIMEOUTS structure that is set by using the SetCommTimeouts function.
If the file handle is associated with a named pipe, the ReadFile function behaves according to the mode of the pipe (blocking or non-blocking).
If the file handle is associated with a mail slot, ReadFile reads the first message from the mail slot.
ReadFile might return fewer bytes than requested, even if there are no errors. This can happen if the end of the file is reached, if the file is opened in non-blocking mode and the read operation would block, or if the file handle is associated with a device that returns fewer bytes than requested. Always check the value pointed to by lpNumberOfBytesRead to determine the actual number of bytes read.
#include <windows.h>
#include <stdio.h>
int main() {
HANDLE hFile;
char buffer[1024];
DWORD bytesRead;
BOOL success;
// Open a file for reading
hFile = CreateFile(
TEXT("example.txt"), // File name
GENERIC_READ, // Access mode
0, // Share mode
NULL, // Security attributes
OPEN_EXISTING, // Creation disposition
FILE_ATTRIBUTE_NORMAL, // Flags and attributes
NULL); // Template file
if (hFile == INVALID_HANDLE_VALUE) {
printf("Error opening file: %lu\n", GetLastError());
return 1;
}
// Read from the file
success = ReadFile(
hFile, // Handle to the file
buffer, // Buffer to store data
sizeof(buffer),// Number of bytes to read
&bytesRead, // Number of bytes actually read
NULL); // Overlapped structure
if (!success) {
printf("Error reading file: %lu\n", GetLastError());
CloseHandle(hFile);
return 1;
}
// Null-terminate the buffer to treat it as a string
buffer[bytesRead] = '\0';
printf("Successfully read %lu bytes:\n%s\n", bytesRead, buffer);
// Close the file handle
CloseHandle(hFile);
return 0;
}