DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

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