fread - read binary data

Syntax	#include <stdio.h> size_t fread(void *ptr, size_t size, size_t nitems, FILE *stream);
Description	fread() reads, into the array pointed to by ptr, up to nitems elements whose size is specified by size in bytes, from the stream pointed to by stream. The file position indicator for the stream (if defined) is advanced by the number of bytes successfully read. If an error occurs, the resulting value of the file position indicator for the stream is indeterminate. If a partial member is read, its value is indeterminate. fread() can mark the structure component st_atime for the file to which stream is assigned for changing (see sys/stat.h). The structure component st_atime is updated as soon as fgetc(), fgets(), fgetwc(), fgetws(), fread(), fscanf(), getc(), getchar(), gets() or scanf() are called successfully for stream and return data which is not was not provided by a preceding call to ungetc() or ungetwc(). BS2000 Record I/O fread() reads a record (or block) from the current file position. Number of bytes to be read: In the following, n is the total number of bytes to be read, i.e. n = size * nitems If n is greater than the current record length, only the current record will be read. If n is less than the current record length, only the first n bytes of the record will be read, and the next read operation will access the data of the next record. fread() returns the same value as for stream I/O, i.e. the number of elements read in their entirety. For record I/O , it is best to use only element length 1, since the return value will then correspond to the length of the record read (without any record length field). (End)
Return val.	Number of elements successfully read
		upon successful completion. The return value is less than nitems only if a read error or end-of-file is encountered.
	0	if size or nitems id equal to 0. The contents of the array pointed to by ptr and the state of the stream remain unchanged. errno is not set. if a read error occurs. The error indicator for the stream is set, and errno is set to indicate the error.
Errors	See fgetc().
Notes	ferror() or feof() must be used to distinguish between an error condition and an end-of-file condition. The array to which ptr points must be large enough to hold the data elements read. To ensure that size specifies the correct number of bytes for a data element, the sizeof() function should be used for the size of the data unit to which ptr points. fread() reads beyond the newline (\n) character and is therefore specially suitable for reading binary files. BS2000 The following applies in the case of text files with SAM access mode and variable record length for which a maximum record length is also specified: When the specification split=no was entered for fopen(), records of maximum length are not concatenated with the subsequent record when they are read. By default or with the specification split=yes, when a record with maximum record length is read, it is assumed that the following record is the continuation of this record and the records are concatenated (End). The program environment determines whether fread() is executed for a BS2000 or POSIX file.
See also	feof(), ferror(), fgetc(), fopen(), getc(), gets(), scanf(), stdio.h, sys/stat.h.