mirror of https://github.com/mkerrisk/man-pages
105 lines
3.6 KiB
Plaintext
105 lines
3.6 KiB
Plaintext
.\" 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 .
|