fread(3C)




NAME

     fread - binary input


SYNOPSIS

     #include <stdio.h>

     size_t fread(void *ptr, size_t  size,  size_t  nitems,  FILE
     *stream);


DESCRIPTION

     The fread() function 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.  For  each
     object,  size  calls  are made to the fgetc(3C) 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)  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 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 will
     be marked for update by the first  successful  execution  of
     fgetc(3C),   fgets(3C),   fgetwc(3C),  fgetws(3C),  fread(),
     fscanf(3C), getc(3C), getchar(3C),  gets(3C),  or  scanf(3C)
     using  stream that returns data not supplied by a prior call
     to ungetc(3C) or ungetwc(3C).


RETURN VALUES

     Upon successful completion, fread() returns  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() returns 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 is
     set and errno is set to indicate the error.


ERRORS

     Refer to fgetc(3C).


EXAMPLES

     Example 1: 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);
     ...


USAGE

     The ferror() or feof() functions must be used to distinguish
     between  an  error  condition and end-of-file condition. See
     ferror(3C).

     Because of possible differences in element length  and  byte
     ordering,  files  written  using fwrite(3C) are application-
     dependent, and possibly cannot be read using  fread()  by  a
     different  application  or by the same application on a dif-
     ferent processor.


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|


SEE ALSO

     read(2),  fclose(3C),   ferror(3C),   fopen(3C),   getc(3C),
     gets(3C), printf(3C), putc(3C), puts(3C), attributes(5)


Man(1) output converted with man2html