fread

Lê dados de um fluxo.

Sintaxe

size_t fread(
   void *buffer,
   size_t size,
   size_t count,
   FILE *stream
);

Parâmetros

buffer
Local de armazenamento de dados.

size
Tamanho do item em bytes.

count
Número máximo de itens a serem lidos.

stream
Ponteiro para a estrutura FILE.

Valor retornado

fread retorna o número de itens completos que a função leu, que pode ser menor do count que se ocorrer um erro ou se encontrar o final do arquivo antes de chegar a count. Use a função feof ou ferror para diferenciar um erro de leitura de uma condição de fim de arquivo. Se size ou count for 0, fread retornará 0 e o conteúdo do buffer permanecerá inalterado. Se stream ou buffer for um ponteiro nulo, fread invoca o manipulador de parâmetro inválido, conforme descrito em Validação de parâmetro. Se a execução tiver permissão para continuar, essa função define errno como EINVAL e retorna 0.

Para obter mais informações sobre códigos de retorno, confira errno, _doserrno, _sys_errlist e _sys_nerr.

Comentários

A função fread lê até count itens de size bytes do stream de entrada e os armazena em buffer. O ponteiro de arquivo associado a stream (se houver) é avançado pelo número de bytes fread lidos. Se o fluxo fornecido for aberto no modo de texto, as novas linhas no estilo do Windows serão convertidas em novas linhas no estilo Unix. Ou seja, os pares de CRLF (feed de linha de retorno de carro) serão substituídos por caracteres de LF (feed de linha única). A substituição não interfere no ponteiro do arquivo ou no valor retornado. A posição do ponteiro do arquivo será indeterminada se ocorrer um erro. O valor de um item parcialmente lido não pode ser determinado.

Quando usado em um fluxo de modo de texto, se a quantidade de dados solicitada (ou seja, size * count) for maior ou igual ao tamanho do buffer interno FILE * (por padrão, o tamanho é de 4096 bytes, configurável usando setvbuf), os dados de fluxo serão copiados diretamente para o buffer fornecido pelo usuário e a conversão de nova linha será feita nesse buffer. Como os dados convertidos podem ser mais curtos do que os dados de fluxo copiados para o buffer, os dados passados buffer[return_value * size] (em que return_value é o valor retornado de fread) poderão conter dados não convertidos do arquivo. Por esse motivo, recomendamos que você coloque terminação nula nos dados de caracteres em buffer[return_value * size] se a intenção do buffer for atuar como uma cadeia de caracteres no estilo C. Confira fopen para obter detalhes sobre os efeitos do modo de texto e do modo binário.

Essa função bloqueia outros threads. Se precisar de uma versão sem bloqueio, use _fread_nolock.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, confira Estado global no CRT.

Requisitos

Função	Cabeçalho necessário
fread	<stdio.h>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

// crt_fread.c
// This program opens a file named FREAD.OUT and
// writes 25 characters to the file. It then tries to open
// FREAD.OUT and read in 25 characters. If the attempt succeeds,
// the program displays the number of actual items read.

#include <stdio.h>

int main( void )
{
   FILE *stream;
   char list[30];
   int  i, numread, numwritten;

   // Open file in text mode:
   if( fopen_s( &stream, "fread.out", "w+t" ) == 0 )
   {
      for ( i = 0; i < 25; i++ )
         list[i] = (char)('z' - i);
      // Write 25 characters to stream
      numwritten = fwrite( list, sizeof( char ), 25, stream );
      printf( "Wrote %d items\n", numwritten );
      fclose( stream );

   }
   else
      printf( "Problem opening the file\n" );

   if( fopen_s( &stream, "fread.out", "r+t" ) == 0 )
   {
      // Attempt to read in 25 characters
      numread = fread( list, sizeof( char ), 25, stream );
      printf( "Number of items read = %d\n", numread );
      printf( "Contents of buffer = %.25s\n", list );
      fclose( stream );
   }
   else
      printf( "File could not be opened\n" );
}

Wrote 25 items
Number of items read = 25
Contents of buffer = zyxwvutsrqponmlkjihgfedcb

Confira também

E/S de fluxo
E/S de arquivo de texto e modo binário
fopen
fwrite
_read