FREAD(3P)                                           POSIX Programmer's Manual                                          FREAD(3P)



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult 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 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 indica-
       tor 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 st_atime field of the file associated with stream for update. The st_atime field  shall
       be  marked  for  update  by  the  first  successful execution of fgetc(), fgets(), fgetwc(), fgetws(), fread(), fscanf(),
       getc(), getchar(), gets(), or scanf() using stream that returns data  not  supplied  by  a  prior  call  to  ungetc()  or
       ungetwc().

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().

       The following sections are informative.

EXAMPLES
   Reading from a Stream
       The following example reads a single element 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, sizeof(buf), 1, fp);
              ...

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-depen-
       dent, and possibly cannot be read using fread() by a different application or by the same application on a different pro-
       cessor.

RATIONALE
       None.

FUTURE DIRECTIONS
       None.

SEE ALSO
       feof(), ferror(), fgetc(), fopen(), getc(),  gets(),  scanf(),  the  Base  Definitions  volume  of  IEEE Std 1003.1-2001,
       <stdio.h>

COPYRIGHT
       Portions  of  this  text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Standard for
       Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6,  Copy-
       right (C) 2001-2003 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any
       discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open  Group
       Standard   is   the   referee   document.   The   original   Standard   can   be   obtained  online  at  http://www.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                                     FREAD(3P)