| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
ISO C |
both |
#include <stdio.h>
size_t fread(void * __restrict__buffer, size_t size, size_t count, FILE * __restrict__stream);
#define _OPEN_SYS_UNLOCKED_EXT 1
#include <stdio.h>
size_t fread_unlocked(void * __restrict__buffer, size_t size,
size_t count, FILE * __restrict__stream);Reads up to count items of size length from the input stream pointed to by stream and stores them in the given buffer. The file position indicator advances by the number of bytes read.
If there is an error during the read operation, the file position indicator is undefined. If a partial element is read, the element's value is undefined.
When you are using fread() for record I/O, set size to 1 and count to the maximum expected length of the record, to obtain the number of bytes. Only one record is read, regardless of count, when using record I/O.
When you are using fread() for blocked I/O, set size to 1 and count to the maximum expected length of the block, to obtain the number of bytes. Only one block is read, regardless of count, when using blocked I/O.
fread() has the same restriction as any read operation for a read immediately following a write or a write immediately following a read. Between a write and a subsequent read, there must be an intervening flush or reposition. Between a read and a subsequent write, there must also be an intervening flush or reposition unless an EOF has been reached.
fread_unlocked() is functionally equivalent to fread() with the exception that it is not thread-safe. This function can safely be used in a multithreaded application if and only if it is called while the invoking thread owns the (FILE*) object, as is the case after a successful call to either the flockfile() or ftrylockfile() function.
fread() returns the number of complete items successfully read.
If size or count is 0, fread() returns 0, and the contents of the array and the state of the stream remain unchanged. For record I/O and blocked I/O, it is possible that the number of complete items can be less than count. However, this result does not necessarily indicate that an error has occurred.
If the Physical File System does not support simple reads from directories, fread() will return 0 if it is used for a directory. Users should use Opendir() and readdir() instead.
The ferror() and feof() functions are used to distinguish between a read error and an EOF. Note that EOF is only reached when an attempt is made to read “past” the last byte of data. Reading up to and including the last byte of data does not turn on the EOF indicator.
⁄* CELEBF38
This example attempts to read NUM_ALPHA characters from the
file myfile.dat.
If there are any errors with either &fread. or &fopen., a
message is printed.
*⁄
#include <stdio.h>
#define NUM_ALPHA 26
int main(void)
{
FILE * stream;
int num; ⁄* number of characters read from stream *⁄
⁄* Do not forget that the '\0' char occupies one character too! *⁄
char buffer[NUM_ALPHA + 1];
buffer[NUM_ALPHA] = '\0';
if (( stream = fopen("myfile.dat", "r"))!= NULL )
{
num = fread( buffer, sizeof( char ), NUM_ALPHA, stream );
if (num == NUM_ALPHA) { ⁄* fread success *⁄
printf( "Number of characters read = %i\n", num );
printf( "buffer = %s\n", buffer );
fclose( stream );
}
else { ⁄* fread failed *⁄
if ( ferror(stream) ) ⁄* possibility 1 *⁄
printf( "Error reading myfile.dat" );
else if ( feof(stream)) { ⁄* possibility 2 *⁄
printf( "EOF found\n" );
printf( "Number of characters read %d\n", num );
printf( "buffer = %.*s\n", num, buffer);
}
}
}
else
printf( "Error opening myfile.dat" );
}