.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "FREAD" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" fread 
.SH NAME
fread \- binary input
.SH SYNOPSIS
.LP
\fB#include <stdio.h>
.br
.sp
size_t fread(void *restrict\fP \fIptr\fP\fB, size_t\fP \fIsize\fP\fB,
size_t\fP \fInitems\fP\fB,
.br
\ \ \ \ \ \  FILE *restrict\fP \fIstream\fP\fB);
.br
\fP
.SH DESCRIPTION
.LP
The \fIfread\fP() function shall read into the array pointed to by
\fIptr\fP up to \fInitems\fP elements whose size is
specified by \fIsize\fP in bytes, from the stream pointed to by \fIstream\fP.
For each object, \fIsize\fP calls shall be made to
the \fIfgetc\fP() function and the results stored, in the order read,
in an array of
\fBunsigned char\fP 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.
.LP
The
\fIfread\fP() function may mark the \fIst_atime\fP field of the file
associated with \fIstream\fP for update. The
\fIst_atime\fP field shall be marked for update by the first successful
execution of \fIfgetc\fP(), \fIfgets\fP(), \fIfgetwc\fP(), \fIfgetws\fP(),
\fIfread\fP(), \fIfscanf\fP(), \fIgetc\fP(), \fIgetchar\fP(), \fIgets\fP(),
or \fIscanf\fP() using \fIstream\fP that returns data not supplied
by a prior call to \fIungetc\fP() or \fIungetwc\fP(). 
.SH RETURN VALUE
.LP
Upon successful completion, \fIfread\fP() shall return the number
of elements successfully read which is less than
\fInitems\fP only if a read error or end-of-file is encountered. If
\fIsize\fP or \fInitems\fP is 0, \fIfread\fP() 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 \fIerrno\fP shall be
set to indicate the error. 
.SH ERRORS
.LP
Refer to \fIfgetc\fP() .
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.SS Reading from a Stream
.LP
The following example reads a single element from the \fIfp\fP stream
into the array pointed to by \fIbuf\fP.
.sp
.RS
.nf

\fB#include <stdio.h>
\&...
size_t bytes_read;
char buf[100];
FILE *fp;
\&...
bytes_read = fread(buf, sizeof(buf), 1, fp);
\&...
\fP
.fi
.RE
.SH APPLICATION USAGE
.LP
The \fIferror\fP() or \fIfeof\fP() functions must
be used to distinguish between an error condition and an end-of-file
condition.
.LP
Because of possible differences in element length and byte ordering,
files written using \fIfwrite\fP() are application-dependent, and
possibly cannot be read using \fIfread\fP() by a
different application or by the same application on a different processor.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIfeof\fP() , \fIferror\fP() , \fIfgetc\fP() , \fIfopen\fP() , \fIgetc\fP()
, \fIgets\fP() , \fIscanf\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
\fI<stdio.h>\fP
.SH 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, Copyright (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.opengroup.org/unix/online.html .