fread
Считывает данные из потока.
Синтаксис
size_t fread(
void *buffer,
size_t size,
size_t count,
FILE *stream
);
Параметры
buffer
Место хранения данных.
size
Размер элемента в байтах.
count
Максимальное число читаемых элементов.
stream
Указатель на структуру FILE
.
Возвращаемое значение
fread
возвращает количество полных элементов, которые считываются функцией, которая может быть меньше, чем count
при возникновении ошибки, или если она встречает конец файла, прежде чем достичь count
. Отличить ошибку чтения от состояния, связанного с достижением конца файла, можно с помощью функции feof
или ferror
. Если size
или count
равно 0, функция fread
возвращает 0, а содержимое буфера не изменяется. Если stream
или buffer
является пустым указателем, fread
вызывает обработчик недопустимых параметров, как описано в разделе "Проверка параметров". Если продолжение выполнения разрешено, эта функции задает для errno
значение EINVAL
и возвращает 0.
Дополнительные сведения о кодах возврата см. в разделе errno
, _doserrno
_sys_errlist
и _sys_nerr
.
Замечания
Функция fread
считывает максимум count
элементов размером size
байт из входного потока stream
и сохраняет их в buffer
. Указатель файла, связанный с stream
(если существует), расширен по количеству байтов fread
, считываемых. Если данный поток открыт в текстовом режиме, новые строки в стиле Windows преобразуются в новые строки в стиле Unix. То есть пары канала возврата каретки (CRLF) заменяются символами однострочного канала (LF). Замена не влияет на указатель файла или возвращаемое значение. В случае ошибки позиция указателя файла будет неопределенной. Значение элемента частичного чтения не может быть определено.
При использовании в потоке текстового режима, если объем запрошенных данных (т size
* count
. е. ) больше или равен размеру внутреннего FILE
* буфера (по умолчанию размер составляет 4096 байт, настраиваемый с помощью setvbuf
), потоковые данные копируются непосредственно в буфер, предоставленный пользователем, и преобразование новой строки выполняется в этом буфере. Так как преобразованные данные могут быть короче, чем данные потока, скопированные в буфер, данные в прошлом buffer
[return_value
* size
] (где return_value
возвращаемое значение из fread
) могут содержать неконвертированные данные из файла. По этой причине рекомендуется использовать символьные данные buffer
null-завершения по адресу [return_value
* size
], если цель буфера — выступать в качестве строки в стиле C. Дополнительные fopen
сведения о влиянии текстового режима и двоичного режима.
Эта функция блокирует работу других потоков. Неблокирующая версия функции называется _fread_nolock
.
По умолчанию глобальное состояние этой функции ограничивается приложением. Чтобы изменить это поведение, см . статью "Глобальное состояние" в CRT.
Требования
Function | Обязательный заголовок |
---|---|
fread |
<stdio.h> |
Дополнительные сведения о совместимости см. в разделе Совместимость.
Пример
// 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
См. также
Потоковый ввод-вывод
Текстовый и двоичный режим операций ввода-вывода
fopen
fwrite
_read