freadfread

Lee datos desde una secuencia.Reads data from a stream.

SintaxisSyntax

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

ParámetrosParameters

búferbuffer
Ubicación de almacenamiento de los datos.Storage location for data.

sizesize
Tamaño del elemento en bytes.Item size in bytes.

countcount
Número máximo de elementos que se va a leer.Maximum number of items to be read.

misionesstream
Puntero a la estructura FILE.Pointer to FILE structure.

Valor devueltoReturn Value

fread devuelve el número de elementos completos leídos realmente, que puede ser menor que Count si se produce un error o si se encuentra el final del archivo antes de llegar al recuento.fread returns the number of full items actually read, which may be less than count if an error occurs or if the end of the file is encountered before reaching count. Utilice la función feof o ferror para distinguir un error de lectura de una condición de final de archivo.Use the feof or ferror function to distinguish a read error from an end-of-file condition. Si size o Count es 0, fread devuelve 0 y el contenido del búfer no cambia.If size or count is 0, fread returns 0 and the buffer contents are unchanged. Si Stream o buffer es un puntero nulo, fread invoca el controlador de parámetros no válidos, tal y como se describe en validación de parámetros.If stream or buffer is a null pointer, fread invokes the invalid parameter handler, as described in Parameter Validation. Si la ejecución puede continuar, esta función establece errno en EINVAL y devuelve 0.If execution is allowed to continue, this function sets errno to EINVAL and returns 0.

Vea _ doserrno, errno, _ Sys _ errlist y _ Sys _ NERR para obtener más información sobre estos códigos de error.See _doserrno, errno, _sys_errlist, and _sys_nerr for more information on these error codes.

ObservacionesRemarks

La función fread lee hasta el número de elementos de tamaño de bytes del flujo de entrada y los almacena en el búfer.The fread function reads up to count items of size bytes from the input stream and stores them in buffer. El puntero de archivo asociado al flujo (si hay alguno) se incrementa según el número de bytes leídos realmente.The file pointer associated with stream (if there is one) is increased by the number of bytes actually read. Si la secuencia especificada se abre en modo de texto, las líneas nuevas de estilo Windows se convierten en nuevas líneas de estilo Unix.If the given stream is opened in text mode, Windows-style newlines are converted into Unix-style newlines. Es decir, los pares de retorno de carro y avance de línea (CRLF) se reemplazan por caracteres de avance de línea (LF).That is, carriage return-line feed (CRLF) pairs are replaced by single line feed (LF) characters. Este reemplazo no tiene ningún efecto en el puntero de archivo ni en el valor devuelto.The replacement has no effect on the file pointer or the return value. Si se produce un error, la posición del puntero de archivo es indeterminada.The file-pointer position is indeterminate if an error occurs. No se puede determinar el valor de un elemento leído parcialmente.The value of a partially read item cannot be determined.

Cuando se usa en una secuencia en modo de texto, si la cantidad de datos solicitados (es decir, el * recuento de tamaño) es mayor o igual que el tamaño del búfer de archivos interno * (de forma predeterminada, es 4096 bytes, que se pueden configurar mediante setvbuf (), los datos de flujo se copian directamente en el búfer proporcionado por el usuario y la conversión de nueva línea seWhen used on a text mode stream, if the amount of data requested (that is, size * count) is greater than or equal to the internal FILE * buffer size (by default this is 4096 bytes, configurable by using setvbuf), stream data is copied directly into the user-provided buffer, and newline conversion is done in that buffer. Dado que los datos convertidos pueden ser más cortos que los datos de secuencia copiados en el búfer, los datos pasados [ RETURN_VALUE * tamaño del búfer] (donde RETURN_VALUE es el valor devuelto de fread) pueden contener datos no convertidos del archivo.Since the converted data may be shorter than the stream data copied into the buffer, data past buffer[return_value * size] (where return_value is the return value from fread) may contain unconverted data from the file. Por esta razón, se recomienda que termine los datos de caracteres en el búfer [ RETURN_VALUE * tamaño] si el propósito del búfer es actuar como una cadena de estilo C.For this reason, we recommend you null-terminate character data at buffer[return_value * size] if the intent of the buffer is to act as a C-style string. Consulte fopen para obtener más información sobre los efectos del modo de texto y el modo binario.See fopen for details on the effects of text mode and binary mode.

Esta función bloquea otros subprocesos.This function locks out other threads. Si necesita una versión que no sea de bloqueo, use _fread_nolock.If you need a non-locking version, use _fread_nolock.

De forma predeterminada, el ámbito de este estado global de esta función es la aplicación.By default, this function's global state is scoped to the application. Para cambiar esto, vea estado global en CRT.To change this, see Global state in the CRT.

RequisitosRequirements

FunciónFunction Encabezado necesarioRequired header
freadfread <stdio.h>

Para obtener información adicional sobre compatibilidad, consulte Compatibilidad.For additional compatibility information, see Compatibility.

EjemploExample

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

Consulte tambiénSee also

E/S de secuenciaStream I/O
E/s de archivos binarios y de textoText and Binary File I/O
fopenfopen
fwritefwrite
_read_read