fread.3s (2010 09)

f
fread(3S) fread(3S)
NAME
fread(), fwrite() - buffered binary input/output to a stream file
SYNOPSIS
#include <stdio.h>
size_t fread(void *__restrict ptr, size_t size, size_t nitems, FILE
*__restrict stream);
size_t fwrite(const void *__restrict ptr, size_t size, size_t nitems, FILE
*__restrict stream);
Obsolescent Interfaces
size_t fread_unlocked(
void *ptr, size_t size, size_t nitems, FILE *stream);
size_t fwrite_unlocked(
const void *ptr, size_t size, size_t nitems, FILE *stream);
DESCRIPTION
fread() copies, into an array pointed to by ptr ,uptonitems items of data from the named input
stream , where 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 ,orifnitems items have been read. fread() leaves the file pointer in stream , if defined, point-
ing to the byte following the last byte read if there is one.
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 .
Obsolescent Interfaces
fread_unlocked()
and fwrite_unlocked() buffered binary input/output to a stream file.
APPLICATION USAGE
After
fread() or fwrite() is applied to a stream, the stream becomes byte-oriented (see orienta-
tion (5)).
RETURN VALUE
fread(), fwrite(), fread_unlocked()
, and fwrite_unlocked() return the number of items
read or written. If size or nitems is 0, no characters are read or written and 0 is returned.
The value returned will be less than nitems only if a read error or end-of-file is encountered.
When the file corresponding to an open stream gets extended after the end-of-file is reached, any subse-
quent calls to
fread() will succeed and the end-of-file indicator will remain set. However, in the
UNIX2003 standards environment (see standards (5)), this function will return zero and the end-of-file
indicator will remain set.
The
ferror() or feof() functions must be used to distinguish between an error condition and an
end-of-file condition.
ERRORS
Refer to getc (3S) for a description of errors returned by
fread().
Refer to putc (3S) for a description of errors returned by
fwrite().
WARNINGS
fread_unlocked() and fwrite_unlocked() are obsolescent interfaces supported only for compa-
tibility with existing DCE applications. New multithreaded applications should use fread() and
fwrite().
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1