~ubuntu-branches/ubuntu/precise/manpages-posix/precise

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 

.TH "FREAD" P 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 .