fread(S)
fread, fwrite --
binary input/output
Syntax
cc . . . -lc
#include <stdio.h>
size_t fread(void *ptr, size_t size, size_t nitems, FILE *stream);
size_t fwrite(const void *ptr, size_t size, size_t nitems, FILE *stream);
Description
The fread function copies nitems items of data
from the named input stream
into an array pointed to by ptr.
An item of data is a sequence of bytes (not
necessarily terminated by a null byte) of length size.
fread stops appending bytes if an end-of-file
or error condition is encountered while reading
stream, or if nitems
items have been read.
fread leaves the file pointer in stream,
if defined, pointing to the byte following the last byte read if
there is a byte.
fread does not change the contents of stream.
fwrite appends at most nitems items of data
from the array pointed to by ptr
to the named output stream.
fwrite stops appending when it has appended
nitems items of data or if an
error condition is encountered on stream.
fwrite does not change the contents of the array pointed to by
ptr.
The argument size is typically
sizeof(
ptr) where the pseudo-function
sizeof specifies the length of an item pointed to by ptr.
If ptr points to a data type other than
char, it should be cast into a pointer to char.
The st_atime field
of the file associated with stream
is marked for update when
fread( )
returns successfully the first time,
if the input data was not pushed back to stream by a prior call to
ungetc(S).
All subsequent calls of
fread( )
may also update the st_atime field if a
read(S)
operation on stream is needed to fill the stdio buffer.
If
fwrite( )
returns successfully
and a file is associated to stream, the st_ctime and
st_mtime
fields of the file are marked for update and will
be updated when
fflush(S)
or
fclose(S)
is called the next time on stream successfully
or when
exit(S)
or
abort(S)
is called.
Diagnostics
The fread and fwrite functions
return the number of items read or written.
If
nitems is non-positive,
no characters are read or written, and 0 is returned by both
fread
and fwrite.
fread( )
will fail if data needs to be read and:
[EAGAIN]-
Cannot read the input stream immediately without blocking the process,
and the O_NONBLOCK flag is set for the file descriptor
associated with stream.
[EBADF]-
Not a valid file descriptor open for reading.
[EINTR]-
The read operation was terminated by a signal before any data was read.
[EIO]-
Cannot read from the controlling terminal.
This happens when the process is in a background process group
and the attempt by the process to read from its controlling terminal fails,
either because the process group is orphaned, or
because the process is ignoring or blocking the SIGTTIN signal.
[ENOMEM]-
Insufficient storage space is available.
[ENXIO]-
Attempt to read from a non-existent device, or from a device
whose capabilities are exceeded.
fwrite( )
will fail if either the stream is unbuffered or data in the
stream's buffer needs to be written, and:
[EAGAIN]-
Cannot write to the output stream immediately without blocking
the process, and
the O_NONBLOCK flag is set for the file descriptor associated with
stream.
[EBADF]-
Not a valid file descriptor open for writing.
[EFBIG]-
Maximum file size or the file size limit for the process is exceeded
in the attempt to write to a file.
[EINTR]-
The write operation was terminated by a signal before any data
was written.
[EIO]-
Cannot write to the controlling terminal.
This will happen when
the process is in an orphaned background process group and the
attempt by the process to write to its controlling terminal fails,
because the TOSTOP bit is set to disable the
writing and the SIGTTOU signal is not ignored or not blocked
by the process.
[ENOMEM]-
Insufficient storage space is available.
[ENOSPC]-
No free space left on the device where the file associated with
stream is stored.
[EPIPE]-
The pipe or FIFO being written to is not opened
by any process for reading.
This error will also send a SIGPIPE signal to the process.
[ENXIO]-
Attempt to write to a non-existent device, or to a
device whose capabilities are exceeded.
See also
fopen(S),
getc(S),
gets(S),
printf(S),
putc(S),
puts(S),
read(S),
scanf(S),
stdio(S)
write(S)
Standards conformance
fread and fwrite are conformant with:
X/Open CAE Specification, System Interfaces and Headers, Issue 4, 1992
;
ANSI X3.159-1989 Programming Language -- C
;
Intel386 Binary Compatibility Specification, Edition 2 (iBCSe2)
;
IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1)
;
and
NIST FIPS 151-1
.
© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003