Función ReadFile (fileapi.h)

Artículo
03/14/2023

Lee los datos del archivo o del dispositivo de entrada/salida (E/S) especificados. Las lecturas se producen en la posición especificada por el puntero del archivo si lo admite el dispositivo.

Esta función está diseñada para operaciones sincrónicas y asincrónicas. Para obtener una función similar diseñada únicamente para la operación asincrónica, consulte ReadFileEx.

Sintaxis

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

Parámetros

[in] hFile

Identificador del dispositivo (por ejemplo, un archivo, secuencia de archivos, disco físico, volumen, búfer de consola, unidad de cinta, socket, recurso de comunicaciones, mailslot o canalización).

El parámetro hFile debe haberse creado con acceso de lectura. Para obtener más información, vea Derechos de acceso genéricos y Derechos de acceso y seguridad de archivos.

Para las operaciones de lectura asincrónicas, hFile puede ser cualquier identificador que se abra con la marca FILE_FLAG_OVERLAPPED mediante la función CreateFile o un identificador de socket devuelto por el socket o la función accept .

[out] lpBuffer

Puntero al búfer que recibe los datos leídos de un archivo o dispositivo.

Este búfer debe permanecer válido durante la operación de lectura. El autor de la llamada no debe usar este búfer hasta que se complete la operación de lectura.

[in] nNumberOfBytesToRead

El número máximo de bytes que se deben leer.

[out, optional] lpNumberOfBytesRead

Puntero a la variable que recibe el número de bytes leídos al usar un parámetro hFile sincrónico. ReadFile establece este valor en cero antes de realizar cualquier comprobación de errores o trabajo. Use NULL para este parámetro si se trata de una operación asincrónica para evitar resultados potencialmente erróneos.

Este parámetro solo puede ser NULL cuando el parámetro lpOverlapped no es NULL.

Windows 7: Este parámetro no puede ser NULL.

Para obtener más información, vea la sección Comentarios.

[in, out, optional] lpOverlapped

Se requiere un puntero a una estructura SUPERPUESTA si el parámetro hFile se abrió con FILE_FLAG_OVERLAPPED; de lo contrario, puede ser NULL.

Si hFile se abre con FILE_FLAG_OVERLAPPED, el parámetro lpOverlapped debe apuntar a una estructura SUPERPUESTA válida y única; de lo contrario, la función puede informar incorrectamente de que la operación de lectura está completa.

Para un hFile que admita desplazamientos de bytes, si usa este parámetro, debe especificar un desplazamiento de bytes en el que empezar a leer desde el archivo o dispositivo. Este desplazamiento se especifica estableciendo los miembros Offset y OffsetHigh de la estructura SUPERPUESTA . En el caso de un hFile que no admite desplazamientos de bytes, se omite OffsetHigh y OffsetHigh.

Para obtener más información sobre las diferentes combinaciones de lpOverlapped y FILE_FLAG_OVERLAPPED, vea la sección Comentarios y la sección Sincronización y posición de archivo .

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es distinto de cero (TRUE).

Si se produce un error en la función o se completa de forma asincrónica, el valor devuelto es cero (FALSE). Para obtener información ampliada de los errores, llame a la función GetLastError.

Nota El código GetLastErrorERROR_IO_PENDING no es un error; designa que la operación de lectura está pendiente de finalización de forma asincrónica. Para obtener más información, vea la sección Comentarios.

Comentarios

La función ReadFile devuelve cuando se produce una de las condiciones siguientes:

Se lee el número de bytes solicitados.
Una operación de escritura se completa en el extremo de escritura de la canalización.
Se usa un identificador asincrónico y la lectura se está produciendo de forma asincrónica.
Se produce un error.

Es posible que se produzca un error en la función ReadFilecon ERROR_INVALID_USER_BUFFER o ERROR_NOT_ENOUGH_MEMORY siempre que haya demasiadas solicitudes de E/S asincrónica pendientes.

Para cancelar todas las operaciones de E/S asincrónicas pendientes, use:

CancelIo: esta función solo cancela las operaciones emitidas por el subproceso que realiza la llamada para el identificador de archivo especificado.
CancelIoEx: esta función cancela todas las operaciones emitidas por los subprocesos para el identificador de archivo especificado.

Use CancelSynchronousIo para cancelar las operaciones de E/S sincrónicas pendientes.

Las operaciones de E/S que se cancelan se completan con el error ERROR_OPERATION_ABORTED.

Es posible que se produzca un error en la función ReadFilecon ERROR_NOT_ENOUGH_QUOTA, lo que significa que el búfer del proceso de llamada no pudo estar bloqueado por páginas. Para obtener más información, vea SetProcessWorkingSetSize.

Si otro proceso bloquea parte de un archivo y la operación de lectura se superpone a la parte bloqueada, se produce un error en esta función.

El acceso al búfer de entrada mientras una operación de lectura usa el búfer puede provocar daños en los datos leídos en ese búfer. Las aplicaciones no deben leer, escribir en, reasignar ni liberar el búfer de entrada que usa una operación de lectura hasta que se complete la operación de lectura. Esto puede ser especialmente problemático cuando se usa un identificador de archivo asincrónico. Puede encontrar información adicional sobre los identificadores de archivos sincrónicos frente a asincrónicos en la sección Sincronización y posición de archivo y en el tema de referencia CreateFile .

Los caracteres se pueden leer desde el búfer de entrada de la consola mediante ReadFile con un identificador para la entrada de la consola. El modo de consola determina el comportamiento exacto de la función ReadFile . De forma predeterminada, el modo de consola es ENABLE_LINE_INPUT, lo que indica que ReadFile debe leerse hasta que llegue a un retorno de carro. Si presiona Ctrl+C, la llamada se realiza correctamente, pero GetLastError devuelve ERROR_OPERATION_ABORTED. Para obtener más información, consulte CreateFile.

Al leer desde un dispositivo de comunicaciones, el comportamiento de ReadFile viene determinado por el tiempo de espera de comunicación actual establecido y recuperado mediante las funciones SetCommTimeouts y GetCommTimeouts . Se pueden producir resultados imprevisibles si no se pueden establecer los valores de tiempo de espera. Para obtener más información sobre los tiempos de espera de comunicación, consulte COMMTIMEOUTS.

Si ReadFile intenta leer desde un mailslot que tiene un búfer demasiado pequeño, la función devuelve FALSE y GetLastError devuelve ERROR_INSUFFICIENT_BUFFER.

Hay requisitos estrictos para trabajar correctamente con archivos abiertos con CreateFile mediante la marca FILE_FLAG_NO_BUFFERING . Para obtener más información, consulte Almacenamiento en búfer de archivos.

Si hFile se abrió con FILE_FLAG_OVERLAPPED, se aplican las condiciones siguientes:

El parámetro lpOverlapped debe apuntar a una estructura SUPERPUESTA válida y única; de lo contrario, la función puede informar incorrectamente de que la operación de lectura está completa.
El parámetro lpNumberOfBytesRead debe establecerse en NULL. Use la función GetOverlappedResult para obtener el número real de bytes leídos. Si el parámetro hFile está asociado a un puerto de finalización de E/S, también puede obtener el número de bytes leídos llamando a la función GetQueuedCompletionStatus .

Sincronización y posición de archivo

Si hFile se abre con FILE_FLAG_OVERLAPPED, es un identificador de archivo asincrónico; de lo contrario, es sincrónico. Las reglas para usar la estructura SUPERPUESTA son ligeramente diferentes para cada una, como se indicó anteriormente.

Nota Si se abre un archivo o dispositivo para E/S asincrónica, las llamadas posteriores a funciones como ReadFile que usan ese identificador suelen devolverse inmediatamente, pero también se pueden comportar de forma sincrónica con respecto a la ejecución bloqueada. Para obtener más información, vea http://support.microsoft.com/kb/156932.

Consideraciones para trabajar con identificadores de archivo asincrónicos:

ReadFile puede devolverse antes de que se complete la operación de lectura. En este escenario, ReadFile devuelve FALSE y la función GetLastError devuelve ERROR_IO_PENDING, lo que permite que el proceso de llamada continúe mientras el sistema completa la operación de lectura.
El parámetro lpOverlapped no debe ser NULL y debe usarse teniendo en cuenta los siguientes hechos:
- Aunque el sistema establece y restablece automáticamente el evento especificado en la estructura SUPERPUESTA , el desplazamiento especificado en la estructura SUPERPUESTA no se actualiza automáticamente.
- ReadFile restablece el evento a un estado no asignado cuando comienza la operación de E/S.
- El evento especificado en la estructura SUPERPUESTA se establece en un estado señalado cuando se completa la operación de lectura; hasta ese momento, la operación de lectura se considera pendiente.
- Dado que la operación de lectura se inicia en el desplazamiento especificado en la estructura SUPERPUESTA , y ReadFile puede devolver antes de que se complete la operación de lectura en el nivel del sistema (lectura pendiente), ni el desplazamiento ni ninguna otra parte de la estructura se debe modificar, liberar o reutilizar por la aplicación hasta que se señale el evento (es decir, la lectura se completa).
- Si se detecta un final de archivo (EOF) durante las operaciones asincrónicas, la llamada a GetOverlappedResult para esa operación devuelve FALSE y GetLastError devuelve ERROR_HANDLE_EOF.

Consideraciones para trabajar con identificadores de archivo sincrónicos:

Si lpOverlapped es NULL, la operación de lectura se inicia en la posición del archivo actual y ReadFile no devuelve hasta que se completa la operación y el sistema actualiza el puntero de archivo antes de que ReadFile devuelva.
Si lpOverlapped no es NULL, la operación de lectura se inicia en el desplazamiento especificado en la estructura SUPERPUESTA y ReadFile no devuelve hasta que se completa la operación de lectura. El sistema actualiza el desplazamiento SUPERPUESTO y el puntero de archivo antes de que se devuelva ReadFile .
Si lpOverlapped es NULL, cuando una operación de lectura sincrónica llega al final de un archivo, ReadFile devuelve TRUE y establece en *lpNumberOfBytesRead cero.
Si lpOverlapped no es NULL, cuando una operación de lectura sincrónica llega al final de un archivo, ReadFile devuelve FALSE y GetLastError devuelve ERROR_HANDLE_EOF.

Para obtener más información, vea CreateFile y E/S sincrónica y asincrónica.

Tuberías

Si se usa una canalización anónima y se cierra el identificador de escritura, cuando ReadFile intenta leer mediante el identificador de lectura correspondiente de la canalización, la función devuelve FALSE y GetLastError devuelve ERROR_BROKEN_PIPE.

Si se lee una canalización con nombre en modo de mensaje y el siguiente mensaje es mayor que el parámetro nNumberOfBytesToRead especifica, ReadFile devuelve FALSE y GetLastError devuelve ERROR_MORE_DATA. El resto del mensaje se puede leer mediante una llamada posterior a la función ReadFile o PeekNamedPipe .

Si el parámetro lpNumberOfBytesRead es cero cuando ReadFile devuelve TRUE en una canalización, el otro extremo de la canalización llamó a la función WriteFile con nNumberOfBytesToWrite establecido en cero.

Para obtener más información sobre las canalizaciones, consulte Canalizaciones.

Operaciones de transacción

Si hay una transacción enlazada al identificador de archivo, la función devuelve datos de la vista de transacción del archivo. Se garantiza que un identificador de lectura de transacción muestra la misma vista de un archivo mientras dura el identificador. Para obtener más información, vea Acerca de NTFS transaccional.

En Windows 8 y Windows Server 2012, esta función es compatible con las tecnologías siguientes.

Tecnología	Compatible
Protocolo Bloque de mensajes del servidor (SMB) 3.0	Sí
Conmutación por error transparente (TFO) de SMB 3.0	Sí
SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO)	Sí
Sistema de archivos de Volumen compartido de clúster (CsvFS)	Sí
Sistema de archivos resistente a errores (ReFS)	Sí

Ejemplos

Para obtener un ejemplo de código que muestra cómo probar para el final del archivo, vea Testing for the End of a File. Para obtener otros ejemplos, vea Crear y usar un archivo temporal y Abrir un archivo para leer o escribir.

Requisitos


Cliente mínimo compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	fileapi.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll