freadfread

从流读取数据。Reads data from a stream.

语法Syntax

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

参数Parameters

bufferbuffer
数据的存储位置。Storage location for data.

sizesize
项目大小(以字节为单位)。Item size in bytes.

countcount
要读取的项的最大数量。Maximum number of items to be read.

streamstream
指向文件结构的指针。Pointer to FILE structure.

返回值Return Value

fread返回实际读取的完整项的数量, 如果发生错误, 或者在到达计数之前遇到文件末尾, 则此值可能小于计数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. 使用feofferror函数将读取错误与文件结尾条件区分开来。Use the feof or ferror function to distinguish a read error from an end-of-file condition. 如果大小计数为 0, 则fread将返回 0, 并且缓冲区内容将保持不变。If size or count is 0, fread returns 0 and the buffer contents are unchanged. 如果缓冲区是 null 指针, fread将调用无效参数处理程序, 如参数验证中所述。If stream or buffer is a null pointer, fread invokes the invalid parameter handler, as described in Parameter Validation. 如果允许执行继续, 则此函数会将errno设置为EINVAL , 并返回0。If execution is allowed to continue, this function sets errno to EINVAL and returns 0.

有关这些错误代码的详细信息, 请参阅 _doserrno、errno、 _sys_errlist _和_sys nerrSee _doserrno, errno, _sys_errlist, and _sys_nerr for more information on these error codes.

备注Remarks

Fread函数从输入中读取的大小为字节的项, 并将其存储在缓冲区中。The fread function reads up to count items of size bytes from the input stream and stores them in buffer. 关联的文件指针 (如果有) 以实际读取的字节数为增量增加。The file pointer associated with stream (if there is one) is increased by the number of bytes actually read. 如果在文本模式下打开给定的流, 则会将 Windows 样式的换行符转换为 Unix 样式的换行符。If the given stream is opened in text mode, Windows-style newlines are converted into Unix-style newlines. 也就是说, 回车换行符 (CRLF) 对替换为单行换行符 (LF) 字符。That is, carriage return-line feed (CRLF) pairs are replaced by single line feed (LF) characters. 该替换不会影响文件指针或返回值。The replacement has no effect on the file pointer or the return value. 如果发生错误,文件指针位置不确定。The file-pointer position is indeterminate if an error occurs. 无法确定部分读取项的值。The value of a partially read item cannot be determined.

在文本模式流上使用时, 如果所请求的数据量 (即,大小 * 计数) 大于或等于内部文件 *缓冲区大小 (默认为4096字节, 则可使用setvbuf), 流数据直接复制到用户提供的缓冲区中, 并在该缓冲区中完成行转换。When 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. 由于转换后的数据可能比复制到缓冲区中的流数据短,因此,数据的缓冲区[return_value * 大小] (其中return_valuefread中的返回值)可能包含文件中未转换的数据。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. 出于此原因,如果缓冲区的意图是要充当 C 样式字符串,则建议以 null 终止字符数据[的形式为return_value * 。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. 有关文本模式和二进制模式效果的详细信息, 请参阅fopenSee fopen for details on the effects of text mode and binary mode.

此函数将锁定其他线程。This function locks out other threads. 如果需要非锁定版本,请使用 _fread_nolockIf you need a non-locking version, use _fread_nolock.

要求Requirements

函数Function 必需的标头Required header
freadfread <stdio.h><stdio.h>

有关其他兼容性信息,请参阅 兼容性For additional compatibility information, see Compatibility.

示例Example

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

请参阅See also

流 I/OStream I/O
文本和二进制文件 i/oText and Binary File I/O
fopenfopen
fwritefwrite
_read_read