fread

Lee datos desde una secuencia.

Sintaxis

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

Parámetros

buffer
Ubicación de almacenamiento de los datos.

size
Tamaño del elemento en bytes.

count
Número máximo de elementos que se va a leer.

stream
Puntero a la estructura FILE .

Valor devuelto

fread devuelve el número de elementos completos que lee la función, que puede ser menor que count si se produce un error o si encuentra el final del archivo antes de alcanzar count. Use la función feof o ferror para distinguir un error de lectura de una condición de final de archivo. Si size o count es 0, fread devuelve 0 y el contenido del búfer queda sin cambios. Si stream o buffer es un puntero nulo, fread invoca el controlador de parámetros no válidos, como se describe en Validación de parámetros. Si la ejecución puede continuar, esta función establece errno en EINVAL y devuelve 0.

Para obtener más información sobre los códigos de retorno, vea errno, _doserrno, _sys_errlist y _sys_nerr.

Comentarios

La función fread lee hasta count elementos de size bytes en la entrada stream y los almacena en buffer. El puntero de archivo asociado a stream (si existe uno) está avanzado por el número de bytes fread leídos. Si la secuencia especificada se abre en modo de texto, las nuevas líneas de estilo Windows se convierten en nuevas líneas de estilo Unix. Es decir, los pares de retorno de carro-avance de línea (CRLF) se reemplazan por caracteres de avance de línea únicos (LF). Este reemplazo no tiene ningún efecto en el puntero de archivo ni en el valor devuelto. Si se produce un error, la posición del puntero de archivo es indeterminada. No se puede determinar el valor de un elemento de lectura parcial.

Cuando se usa en una secuencia en modo de texto, si la cantidad de datos solicitados (es decir, size * count) es mayor o igual que el FILE tamaño interno * del búfer (de forma predeterminada, el tamaño es de 4096 bytes, configurable mediante setvbuf), los datos de secuencia se copian directamente en el búfer proporcionado por el usuario y la conversión de nueva línea se realiza en ese búfer. Dado que los datos convertidos pueden ser más cortos que los datos del flujo copiados en el búfer, los datos que pasen buffer[return_value * size] (donde return_value es el valor devuelto de fread) pueden contener datos no convertidos del archivo. Por este motivo, se recomienda finalizar con NULL los datos de caracteres en buffer[return_value * size] si la intención del búfer es actuar como cadena de estilo C. Consulte fopen para obtener más información sobre los efectos del modo de texto y el modo binario.

Esta función bloquea otros subprocesos. Si necesita una versión que no sea de bloqueo, use _fread_nolock.

De manera predeterminada, el estado global de esta función está limitado a la aplicación. Para cambiar este comportamiento, consulte Estado global en CRT.

Requisitos

Función	Encabezado necesario
fread	<stdio.h>

Para obtener más información sobre compatibilidad, consulte Compatibilidad.

Ejemplo

// 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

Vea también

E/S de secuencia
E/S de archivo de modo binario y texto
fopen
fwrite
_read