Função ReadFile (fileapi.h)

Lê dados do arquivo ou dispositivo de E/S (entrada/saída) especificado. As leituras ocorrem na posição especificada pelo ponteiro do arquivo, se houver suporte para o dispositivo.

Essa função foi projetada para operações síncronas e assíncronas. Para uma função semelhante projetada exclusivamente para operação assíncrona, consulte ReadFileEx .

Sintaxe

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

Parâmetros

[in] hFile

Um identificador para o dispositivo (por exemplo, um arquivo, fluxo de arquivos, disco físico, volume, buffer de console, unidade de fita, soquete, recurso de comunicação, emaillot ou pipe).

O parâmetro hFile deve ter sido criado com acesso de leitura. Para obter mais informações, consulte de direitos de acesso genéricos e de direitos de acesso e segurança de arquivos.

Para operações de leitura assíncronas, hFile pode ser qualquer identificador aberto com o sinalizador de FILE_FLAG_OVERLAPPED pela função CreateFile ou um identificador de soquete retornado pelo soquete ou aceitar função.

[out] lpBuffer

Um ponteiro para o buffer que recebe os dados lidos de um arquivo ou dispositivo.

Esse buffer deve permanecer válido durante a operação de leitura. O chamador não deve usar esse buffer até que a operação de leitura seja concluída.

[in] nNumberOfBytesToRead

O número máximo de bytes a serem lidos.

[out, optional] lpNumberOfBytesRead

Um ponteiro para a variável que recebe o número de bytes lidos ao usar um parâmetro hFile síncrono. ReadFile define esse valor como zero antes de fazer qualquer verificação de erro ou trabalho. Use NULL para esse parâmetro se essa for uma operação assíncrona para evitar resultados potencialmente incorretos.

Esse parâmetro pode ser NULL somente quando o parâmetro lpOverlapped não estiver NULL.

Windows 7: Esse parâmetro não pode ser NULL.

Para obter mais informações, consulte a seção Comentários.

[in, out, optional] lpOverlapped

Um ponteiro para uma estrutura de OVERLAPPED será necessário se o parâmetro hFile tiver sido aberto com FILE_FLAG_OVERLAPPED, caso contrário, poderá ser NULL.

Se hFile for aberto com FILE_FLAG_OVERLAPPED, o parâmetro lpOverlapped deverá apontar para uma estrutura de SOBREPOSTA válida e exclusiva, caso contrário, a função poderá relatar incorretamente que a operação de leitura está concluída.

Para um hFile que dá suporte a deslocamentos de bytes, se você usar esse parâmetro, deverá especificar um deslocamento de bytes no qual iniciar a leitura do arquivo ou dispositivo. Esse deslocamento é especificado definindo os membros Offset e OffsetHigh da estrutura de OVERLAPPED. Para um hFile que não dá suporte a deslocamentos de bytes, de Deslocamento e OffsetHigh são ignorados.

Para obter mais informações sobre diferentes combinações de e FILE_FLAG_OVERLAPPEDlpOverlapped, consulte a seção Comentários e a seção de Sincronização e Posição do Arquivo .

Valor de retorno

Se a função for bem-sucedida, o valor retornado não será zero (TRUE).

Se a função falhar ou estiver sendo concluída de forma assíncrona, o valor retornado será zero (FALSE). Para obter informações de erro estendidas, chame a função GetLastError.

Observações

A função ReadFile retorna quando ocorre uma das seguintes condições:

• O número de bytes solicitados é lido.
• Uma operação de gravação é concluída na extremidade de gravação do pipe.
• Um identificador assíncrono está sendo usado e a leitura está ocorrendo de forma assíncrona.
• Ocorre um erro.

A função ReadFile pode falhar com ERROR_INVALID_USER_BUFFER ou ERROR_NOT_ENOUGH_MEMORY sempre que houver muitas solicitações de E/S assíncronas pendentes.

Para cancelar todas as operações de E/S assíncronas pendentes, use:

• CancelIo: essa função cancela apenas as operações emitidas pelo thread de chamada para o identificador de arquivo especificado.
• CancelIoEx: essa função cancela todas as operações emitidas pelos threads para o identificador de arquivo especificado.

Use CancelSynchronousIo para cancelar operações de E/S síncronas pendentes.

As operações de E/S canceladas são concluídas com o erro ERROR_OPERATION_ABORTED.

A função ReadFile pode falhar com ERROR_NOT_ENOUGH_QUOTA, o que significa que o buffer do processo de chamada não pôde ser bloqueado por página. Para obter informações adicionais, consulte SetProcessWorkingSetSize.

Se parte de um arquivo for bloqueada por outro processo e a operação de leitura se sobrepor à parte bloqueada, essa função falhará.

Acessar o buffer de entrada enquanto uma operação de leitura estiver usando o buffer pode levar à corrupção dos dados lidos nesse buffer. Os aplicativos não devem ler, gravar, realocar ou liberar o buffer de entrada que uma operação de leitura está usando até que a operação de leitura seja concluída. Isso pode ser particularmente problemático ao usar um identificador de arquivo assíncrono. Informações adicionais sobre identificadores de arquivo síncronos versus assíncronos podem ser encontradas na seção Sincronização e Posição do Arquivo e no tópico de referência CreateFile.

Os caracteres podem ser lidos do buffer de entrada do console usando ReadFile com um identificador para entrada do console. O modo de console determina o comportamento exato da função ReadFile. Por padrão, o modo de console é ENABLE_LINE_INPUT, o que indica que readFile deve ser lido até atingir um retorno de carro. Se você pressionar Ctrl+C, a chamada terá êxito, mas GetLastError retornará ERROR_OPERATION_ABORTED. Para obter mais informações, consulte CreateFile.

Ao ler de um dispositivo de comunicação, o comportamento de ReadFile é determinado pelo tempo limite de comunicação atual como definido e recuperado usando as funções SetCommTimeouts e GetCommTimeouts. Resultados imprevisíveis podem ocorrer se você não definir os valores de tempo limite. Para obter mais informações sobre tempos limite de comunicação, consulte COMMTIMEOUTS.

Se ReadFile tentar ler de um emaillot que tenha um buffer muito pequeno, a função retornará FALSE e GetLastError retornará ERROR_INSUFFICIENT_BUFFER.

Há requisitos estritos para trabalhar com êxito com arquivos abertos com CreateFile usando o sinalizador FILE_FLAG_NO_BUFFERING. Para obter detalhes, consultede Buffer de Arquivos .

Se hFile foi aberto com FILE_FLAG_OVERLAPPED, as seguintes condições estão em vigor:

• O parâmetro lpOverlapped deve apontar para uma estrutura de OVERLAPPED válida e exclusiva; caso contrário, a função pode relatar incorretamente que a operação de leitura está concluída.
• O parâmetro lpNumberOfBytesRead deve ser definido como NULL. Use a função GetOverlappedResult para obter o número real de bytes lidos. Se o parâmetro hFile estiver associado a uma porta de conclusão de E/S, você também poderá obter o número de bytes lidos chamando a função GetQueuedCompletionStatus.

Sincronização e posição do arquivo

Se hFile for aberto com FILE_FLAG_OVERLAPPED, ele será um identificador de arquivo assíncrono; caso contrário, ele é síncrono. As regras para usar a estrutura de OVERLAPPED são ligeiramente diferentes para cada uma, conforme observado anteriormente.

Considerações para trabalhar com identificadores de arquivo assíncronos:

• ReadFile pode retornar antes que a operação de leitura seja concluída. Nesse cenário, ReadFile retorna FALSE e a função GetLastError retorna ERROR_IO_PENDING, o que permite que o processo de chamada continue enquanto o sistema conclui a operação de leitura.
• O parâmetro lpOverlapped não deve ser NULL e deve ser usado com os seguintes fatos em mente:
  • Embora o evento especificado na estrutura de OVERLAPPED seja definido e redefinido automaticamente pelo sistema, o deslocamento especificado na estrutura de OVERLAPPED não é atualizado automaticamente.
  • ReadFile redefine o evento para um estado não atribuído quando ele inicia a operação de E/S.
  • O evento especificado na estrutura OVERLAPPED é definido como um estado sinalizado quando a operação de leitura é concluída; até esse momento, a operação de leitura é considerada pendente.
  • Como a operação de leitura começa no deslocamento especificado na estrutura de OVERLAPPED e readFile pode retornar antes que a operação de leitura no nível do sistema seja concluída (leitura pendente), nem o deslocamento nem qualquer outra parte da estrutura deve ser modificado, liberado ou reutilizado pelo aplicativo até que o evento seja sinalizado (ou seja, a leitura é concluída).
  • Se o EOF (fim do arquivo) for detectado durante operações assíncronas, a chamada para GetOverlappedResult para essa operação retornará FALSE e GetLastError retornará ERROR_HANDLE_EOF.

Considerações para trabalhar com identificadores de arquivo síncronos:

• Se lpOverlapped for NULL, a operação de leitura será iniciada na posição do arquivo atual e ReadFile não retornará até que a operação seja concluída e o sistema atualizará o ponteiro de arquivo antes de readFile retornar.
• Se lpOverlapped não for NULL, a operação de leitura será iniciada no deslocamento especificado na estrutura de OVERLAPPED e ReadFile não retornará até que a operação de leitura seja concluída. O sistema atualiza o deslocamento de OVERLAPPED e o ponteiro de arquivo antes de ReadFile retorna.
• Se lpOverlapped for NULL, quando uma operação de leitura síncrona atingir o final de um arquivo, readFile retornará TRUE e definirá *lpNumberOfBytesRead como zero.
• Se lpOverlapped não estiver NULL, quando uma operação de leitura síncrona atingir o final de um arquivo, ReadFile retornará FALSE e GetLastError retornará ERROR_HANDLE_EOF.

Para obter mais informações, consulte CreateFile e de E/S síncrona e assíncrona.

Tubos

Se um pipe anônimo estiver sendo usado e o identificador de gravação tiver sido fechado, quando ReadFile tentar ler usando o identificador de leitura correspondente do pipe, a função retornará FALSE e GetLastError retornará ERROR_BROKEN_PIPE.

Se um pipe nomeado estiver sendo lido no modo de mensagem e a próxima mensagem for maior do que o parâmetro nNumberOfBytesToRead especificar, ReadFile retornará false e GetLastError retornará ERROR_MORE_DATA. O restante da mensagem pode ser lido por uma chamada subsequente para a função ReadFile ou PeekNamedPipe.

Se o parâmetro lpNumberOfBytesRead for zero quando ReadFile retornar verdadeiro em um pipe, a outra extremidade do pipe chamada função WriteFile com nNumberOfBytesToWrite definida como zero.

Para obter mais informações sobre pipes, consulte Pipes.

Operações transacionadas

Se houver uma transação associada ao identificador de arquivo, a função retornará dados da exibição transacionada do arquivo. Um identificador de leitura transacionado tem a garantia de mostrar a mesma exibição de um arquivo durante a alça. Para obter mais informações, consulte Sobre o NTFS transacional.

No Windows 8 e no Windows Server 2012, essa função é compatível com as tecnologias a seguir.

Exemplos

Para obter um exemplo de código que mostra como testar o fim do arquivo, consulte Testing for the End of a File. Para obter outros exemplos, consulte Criando e usando um arquivo temporário e abrindo um arquivo para leitura ou gravação.

Requisitos

Consulte também

cancelio

CancelIoEx

CancelSynchronousIo

CreateFile

Funções de gerenciamento de arquivos

GetCommTimeouts

GetOverlappedResult

GetQueuedCompletionStatus

SOBREPOSTOS

PeekNamedPipe

ReadFileEx

setCommTimeouts

SetErrorMode

writefile