# fread

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           fread — binary input
    


## SYNOPSIS



           #include <stdio.h>
    
           size_t fread(void *restrict _ptr_ , size_t _size_ , size_t _nitems_ ,
               FILE *restrict _stream_);
    


## DESCRIPTION



           The functionality described on this reference page is aligned with
           the ISO C standard. Any conflict between the requirements
           described here and the ISO C standard is unintentional. This
           volume of POSIX.1‐2017 defers to the ISO C standard.
    
           The _fread_() function shall read 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_.  For each object, _size_ calls
           shall be made to the _fgetc_() function and the results stored, in
           the order read, in an array of **unsigned char** exactly overlaying
           the object. The file position indicator for the stream (if
           defined) shall be advanced by the number of bytes successfully
           read. If an error occurs, the resulting value of the file position
           indicator for the stream is unspecified. If a partial element is
           read, its value is unspecified.
    
           The _fread_() function may mark the last data access timestamp of
           the file associated with _stream_ for update. The last data access
           timestamp shall be marked for update by the first successful
           execution of _fgetc_(), _fgets_(), _fread_(), _fscanf_(), _getc_(),
           _getchar_(), _getdelim_(), _getline_(), _gets_(), or _scanf_() using _stream_
           that returns data not supplied by a prior call to _ungetc_().
    


## RETURN VALUE



           Upon successful completion, _fread_() shall return the number of
           elements successfully read which is less than _nitems_ only if a
           read error or end-of-file is encountered. If _size_ or _nitems_ is 0,
           _fread_() shall return 0 and the contents of the array and the state
           of the stream remain unchanged. Otherwise, if a read error occurs,
           the error indicator for the stream shall be set, and _errno_ shall
           be set to indicate the error.
    


## ERRORS



           Refer to fgetc(3p).
    
           _The following sections are informative._
    


## EXAMPLES



       **Reading from a Stream**
           The following example transfers a single 100-byte fixed length
           record from the _fp_ stream into the array pointed to by _buf_.
    
               #include <stdio.h>
               ...
               size_t elements_read;
               char buf[100];
               FILE *fp;
               ...
               elements_read = fread(buf, sizeof(buf), 1, fp);
               ...
    
           If a read error occurs, _elements_read_ will be zero but the number
           of bytes read from the stream could be anything from zero to
           _sizeof_(_buf_)-1.
    
           The following example reads multiple single-byte elements from the
           _fp_ stream into the array pointed to by _buf_.
    
               #include <stdio.h>
               ...
               size_t bytes_read;
               char buf[100];
               FILE *fp;
               ...
               bytes_read = fread(buf, 1, sizeof(buf), fp);
               ...
    
           If a read error occurs, _bytes_read_ will contain the number of
           bytes read from the stream.
    


## APPLICATION USAGE



           The _ferror_() or _feof_() functions must be used to distinguish
           between an error condition and an end-of-file condition.
    
           Because of possible differences in element length and byte
           ordering, files written using _fwrite_() are application-dependent,
           and possibly cannot be read using _fread_() by a different
           application or by the same application on a different processor.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *