Compartir a través de


Función ReadFile (fileapi.h)

Lee los datos del archivo especificado o del dispositivo de entrada/salida (E/S). Las lecturas se producen en la posición especificada por el puntero de archivo si es compatible con 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, flujo 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 de derechos de acceso genéricos y derechos de acceso y seguridad de archivos de .

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

[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

Número máximo de bytes que se van a leer.

[out, optional] lpNumberOfBytesRead

Puntero a la variable que recibe el número de bytes leídos al usar un parámetro de 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 se puede NULL cuando el parámetro de lpOverlapped no es NULL.

Windows 7: Este parámetro no se puede 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 de SUPERPUESTA válida y única; de lo contrario, la función puede notificar incorrectamente 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 de desplazamiento y OffsetHigh miembros de la estructura SUPERPUESTA. Para un hFile de que no admite desplazamientos de bytes, se omite offset 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 de error extendida, llame a la función GetLastError.

Nota

 La ERROR_IO_PENDING de código GetLastError de 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 Comentarios.

Observaciones

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.

La función readFile puede producir un error con ERROR_INVALID_USER_BUFFER o ERROR_NOT_ENOUGH_MEMORY siempre que haya demasiadas solicitudes de E/S asincrónicas 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 de 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.

La función readFile puede producir un error con 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, consulte SetProcessWorkingSetSize.

Si otra operación de lectura 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 de 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, 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, vea 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 de SetCommTimeouts y GetCommTimeouts. Los resultados imprevisibles pueden producirse 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, vea 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 de 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 de superpuesta válida y única, de lo contrario, la función puede notificar incorrectamente 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 de SUPERPUESTAs 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 con 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 E/S de disco asincrónico aparece como sincrónico en Windows.

Consideraciones para trabajar con identificadores de archivos asincrónicos:

  • ReadFile puede devolver 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 el 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 a nivel del sistema (lectura pendiente), ni el desplazamiento ni ninguna otra parte de la estructura se deben modificar, liberar o reutilizar mediante la aplicación hasta que se indique el evento (es decir, se completa la lectura).
    • 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 complete la operación y el sistema actualiza el puntero de archivo antes de ReadFile.
  • 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 complete la operación de lectura. El sistema actualiza el desplazamiento SUPERPUESTO y el puntero de archivo antes de ReadFile.
  • Si lpOverlapped es NULL, cuando una operación de lectura sincrónica llega al final de un archivo, ReadFile devuelve TRUE y establece *lpNumberOfBytesRead en 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, consulte CreateFile y de E/S sincrónica y asincrónica.

Tubería

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 de 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 denominado 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 transaccionada del archivo. Se garantiza que un identificador de lectura de transacciones muestre la misma vista de un archivo mientras dure el identificador. Para obtener más información, vea About Transactional NTFS.

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

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

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 de archivos temporales y Abrir un archivo para leer o escribir.

Requisitos

Requisito Valor
cliente mínimo admitido Windows XP [aplicaciones de escritorio | Aplicaciones para UWP]
servidor mínimo admitido Windows Server 2003 [aplicaciones de escritorio | Aplicaciones para UWP]
de la plataforma de destino de Windows
encabezado de fileapi.h (incluya Windows.h)
biblioteca de Kernel32.lib
DLL de Kernel32.dll

Consulte también

CancelIo

CancelIoEx

CancelSynchronousIo

CreateFile

funciones de administración de archivos

GetCommTimeouts

GetOverlappedResult

GetQueuedCompletionStatus

SUPERPUESTAs

PeekNamedPipe

ReadFileEx

SetCommTimeouts

SetErrorMode

WriteFile