Функция ReadFile (fileapi.h)

Статья
03/14/2023

Считывает данные из указанного файла или устройства ввода-вывода. Операции чтения выполняются в позиции, указанной указателем файла, если устройство поддерживает.

Эта функция предназначена как для синхронных, так и для асинхронных операций. Аналогичную функцию, предназначенную исключительно для асинхронных операций, см. в разделе ReadFileEx.

Синтаксис

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

Параметры

[in] hFile

Дескриптор для устройства (например, файл, файловый поток, физический диск, том, буфер консоли, ленточный накопитель, сокет, ресурс связи, почтовый слопот или канал).

Параметр hFile должен быть создан с доступом на чтение. Дополнительные сведения см. в разделах Универсальные права доступа и Безопасность файлов и права доступа.

Для асинхронных операций чтения hFile может быть любым дескриптором, который открывается с флагом FILE_FLAG_OVERLAPPED функцией CreateFile , или дескриптор сокета, возвращаемый функцией сокета или accept .

[out] lpBuffer

Указатель на буфер, который получает данные, считываемые из файла или устройства.

Этот буфер должен оставаться действительным в течение операции чтения. Вызывающий объект не должен использовать этот буфер до завершения операции чтения.

[in] nNumberOfBytesToRead

Максимальное число байтов для чтения.

[out, optional] lpNumberOfBytesRead

Указатель на переменную, которая получает количество считываемых байтов при использовании синхронного параметра hFile . ReadFile устанавливает это значение равным нулю перед выполнением какой-либо работы или проверки ошибок. Используйте значение NULL для этого параметра, если это асинхронная операция, чтобы избежать потенциально ошибочных результатов.

Этот параметр может иметь значение NULL , только если параметр lpOverlapped не равен NULL.

Windows 7: Этот параметр не может иметь значение NULL.

Дополнительные сведения см. в разделе «Примечания».

[in, out, optional] lpOverlapped

Указатель на структуру OVERLAPPED требуется, если параметр hFile был открыт с FILE_FLAG_OVERLAPPED, в противном случае он может иметь значение NULL.

Если hFile открывается с FILE_FLAG_OVERLAPPED, параметр lpOverlapped должен указывать на допустимую и уникальную структуру OVERLAPPED , в противном случае функция может неправильно сообщить о завершении операции чтения.

Для файла hFile , поддерживающего смещение байтов, при использовании этого параметра необходимо указать смещение байтов, с которого следует начать чтение из файла или устройства. Это смещение задается путем задания элементов Offset и OffsetHigh структуры OVERLAPPED . Для файла hFile , который не поддерживает смещения байтов, offset и OffsetHigh игнорируются.

Дополнительные сведения о различных сочетаниях lpOverlapped и FILE_FLAG_OVERLAPPED см. в разделах Примечания и Синхронизация и положение файлов .

Возвращаемое значение

Если функция выполнена успешно, возвращается ненулевое значение (TRUE).

Если функция завершается асинхронно, возвращаемое значение равно нулю (FALSE). Чтобы получить расширенные сведения об ошибке, вызовите функцию GetLastError .

ПримечаниеERROR_IO_PENDING кода GetLastError не является ошибкой; он указывает, что операция чтения ожидает завершения асинхронно. Дополнительные сведения см. в подразделе "Примечания".

Число запрошенных байтов считывается.
Операция записи завершается в конце канала записи.
Используется асинхронный дескриптор, а чтение выполняется асинхронно.
Происходит ошибка.

Функция ReadFile может завершиться сбоем при ERROR_INVALID_USER_BUFFER или ERROR_NOT_ENOUGH_MEMORY при наличии слишком большого количества невыполненных асинхронных запросов ввода-вывода.

Чтобы отменить все ожидающие асинхронные операции ввода-вывода, используйте один из следующих способов:

CancelIo — эта функция отменяет только операции, выданные вызывающим потоком для указанного дескриптора файла.
CancelIoEx — эта функция отменяет все операции, выполняемые потоками для указанного дескриптора файла.

Используйте CancelSynchronousIo для отмены ожидающих синхронных операций ввода-вывода.

Операции ввода-вывода, отмененные с ошибкой ERROR_OPERATION_ABORTED.

Функция ReadFile может завершиться сбоем с ERROR_NOT_ENOUGH_QUOTA, что означает, что буфер вызывающего процесса не может быть заблокирован на странице. Дополнительные сведения см. в разделе SetProcessWorkingSetSize.

Если часть файла заблокирована другим процессом, а операция чтения перекрывает заблокированную часть, эта функция завершается ошибкой.

Доступ к входным буферам во время операции чтения с использованием буфера может привести к повреждению данных, считываемых в этот буфер. Приложения не должны считывать, записывать в, перераспределять или освобождать входной буфер, который используется операцией чтения, пока операция чтения не завершится. Это может быть особенно проблематично при использовании асинхронного дескриптора файлов. Дополнительные сведения о синхронных и асинхронных дескрипторах файлов можно найти в разделе Синхронизация и положение файла , а также в справочном разделе CreateFile .

Символы можно считывать из входного буфера консоли с помощью readFile с дескриптором для ввода консоли. Режим консоли определяет точное поведение функции ReadFile . По умолчанию режим консоли ENABLE_LINE_INPUT, что означает, что ReadFile должен читать, пока не достигнет возврата каретки. Если нажать клавиши CTRL+C, вызов будет выполнен успешно, но GetLastError возвращает ERROR_OPERATION_ABORTED. Дополнительные сведения см. в разделе CreateFile.

При чтении с устройства связи поведение ReadFile определяется текущим временем ожидания обмена данными, заданным и полученным с помощью функций SetCommTimeouts и GetCommTimeouts . Если не задать значения времени ожидания, могут возникнуть непредсказуемые результаты. Дополнительные сведения об истечении времени ожидания связи см. в разделе COMMTIMEOUTS.

Если ReadFile пытается выполнить чтение из почтового объекта с слишком маленьким буфером, функция возвращает false , а GetLastError возвращает ERROR_INSUFFICIENT_BUFFER.

Существуют строгие требования для успешной работы с файлами, открытыми с помощью CreateFile с помощью флага FILE_FLAG_NO_BUFFERING . Дополнительные сведения см. в разделе Буферизация файлов.

Если hFile был открыт с помощью FILE_FLAG_OVERLAPPED, действуют следующие условия:

Параметр lpOverlapped должен указывать на допустимую и уникальную структуру OVERLAPPED , в противном случае функция может неправильно сообщить о завершении операции чтения.
Параметр lpNumberOfBytesRead должен иметь значение NULL. Используйте функцию GetOverlappedResult , чтобы получить фактическое количество прочитанных байтов. Если параметр hFile связан с портом завершения ввода-вывода, можно также получить количество прочитанных байтов, вызвав функцию GetQueuedCompletionStatus .

Синхронизация и положение файлов

Если hFile открывается с помощью FILE_FLAG_OVERLAPPED, это асинхронный дескриптор файла; в противном случае он является синхронным. Правила использования структуры OVERLAPPED немного отличаются для каждой из них, как отмечалось ранее.

Примечание Если файл или устройство открывается для асинхронного ввода-вывода, последующие вызовы функций, таких как ReadFile с использованием этого дескриптора, обычно возвращаются немедленно, но также могут работать синхронно в отношении заблокированного выполнения. Дополнительные сведения см. в разделе http://support.microsoft.com/kb/156932.

Рекомендации по работе с асинхронными дескрипторами файлов:

ReadFile может вернуться до завершения операции чтения. В этом сценарии ReadFile возвращает значение FALSE , а функция GetLastError возвращает ERROR_IO_PENDING, что позволяет продолжить вызывающий процесс, пока система завершает операцию чтения.
Параметр lpOverlapped не должен иметь значение NULL и должен использоваться со следующими фактами:
- Хотя событие, указанное в структуре OVERLAPPED , устанавливается и сбрасывается системой автоматически, смещение, указанное в структуре OVERLAPPED , не обновляется автоматически.
- ReadFile сбрасывает событие до состояния без знака при запуске операции ввода-вывода.
- Событие, указанное в структуре OVERLAPPED , устанавливается в состояние сигналов после завершения операции чтения; до этого времени операция чтения считается ожидающей.
- Так как операция чтения начинается со смещением, указанным в структуре OVERLAPPED , и ReadFile может вернуться до завершения операции чтения на уровне системы (ожидание чтения), ни смещение, ни какая-либо другая часть структуры не должны быть изменены, освобождены или повторно использоваться приложением до тех пор, пока не будет показано событие (т. е. чтение завершается).
- Если во время асинхронных операций обнаруживается конец файла (EOF), вызов Метода GetOverlappedResult для этой операции возвращает значение FALSE , а GetLastError возвращает ERROR_HANDLE_EOF.

Рекомендации по работе с синхронными дескрипторами файлов:

Если lpOverlapped имеет значение NULL, операция чтения начинается в текущей позиции файла и ReadFile не возвращается, пока операция не будет завершена, а система обновит указатель на файл до возврата ReadFile .
Если значение lpOverlapped не равно NULL, операция чтения начинается со смещения, указанного в структуре OVERLAPPED , и ReadFile не возвращается до завершения операции чтения. Система обновляет смещение OVERLAPPED и указатель на файл перед возвратом ReadFile .
Если lpOverlapped имеет значение NULL, то, когда синхронная операция чтения достигает конца файла, ReadFile возвращает значение TRUE и задает значение *lpNumberOfBytesRead нулю.
Если lpOverlapped не имеет значение NULL, то, когда синхронная операция чтения достигает конца файла, ReadFile возвращает значение FALSE , а GetLastError возвращает ERROR_HANDLE_EOF.

Дополнительные сведения см. в разделах CreateFile и Синхронный и асинхронный ввод-вывод.

Трубы

Если используется анонимный канал и дескриптор записи закрыт, при попытке чтения ReadFile с помощью соответствующего дескриптора чтения канала функция возвращает ЗНАЧЕНИЕ FALSE , а GetLastError возвращает ERROR_BROKEN_PIPE.

Если именованный канал считывается в режиме сообщения, а следующее сообщение длиннее, чем указано в параметре nNumberOfBytesToRead , ReadFile возвращает значение FALSE , а GetLastError — ERROR_MORE_DATA. Оставшуюся часть сообщения можно прочитать при последующем вызове функции ReadFile или PeekNamedPipe .

Если параметр lpNumberOfBytesRead равен нулю, когда ReadFile возвращает значение TRUE в канале, другой конец канала вызывает функцию WriteFile с параметром nNumberOfBytesToWrite , равным нулю.

Дополнительные сведения о канале см. в разделе Каналы.

Транзакция операций

Если к дескрипторе файла привязана транзакция, то функция возвращает данные из представления файла с транзакциями. Дескриптор чтения с транзакцией гарантированно отображает одно и то же представление файла на протяжении всего дескриптора. Дополнительные сведения см. в разделе Сведения о транзакционной ntfs.

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технология	Поддерживается
Протокол SMB 3.0	Да
SMB 3.0 Transparent Failover (TFO)	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	Да
Восстанавливаемая файловая система (ReFS)	Да

Примеры

Пример кода, в который показано, как проверить конец файла, см. в разделе Testing for the End of a File. Другие примеры см. в разделах Создание и использование временного файла и Открытие файла для чтения или записи.

Требования


Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	fileapi.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll