Technical Reference: Base Operating System and Extensions, Volume 1

fread or fwrite Subroutine

Purpose

Reads and writes binary files.

Library

Standard C Library (libc.a)

Syntax

#include <stdio.h> size_t fread ( (void *) Pointer, Size, NumberOfItems, Stream (Parameters)) size_t Size, NumberOfItems (Parameters); FILE *Stream (Parameters); size_t fwrite (Pointer, Size, NumberOfItems, Stream (Parameters)) const void *Pointer (Parameters); size_t Size, NumberOfItems (Parameters); FILE *Stream (Parameters);

Description

The fread subroutine copies the number of data items specified by the NumberOfItems parameter from the input stream into an array beginning at the location pointed to by the Pointer parameter. Each data item has the form *Pointer.

The fread subroutine stops copying bytes if an end-of-file (EOF) or error condition is encountered while reading from the input specified by the Stream parameter, or when the number of data items specified by the NumberOfItems parameter have been copied. This subroutine leaves the file pointer of the Stream parameter, if defined, pointing to the byte following the last byte read. The fread subroutine does not change the contents of the Stream parameter.

The st_atime field will be marked for update by the first successful run of the fgetc (getc, getchar, fgetc, or getw Subroutine), fgets (gets or fgets Subroutine), fgetwc (getwc, fgetwc, or getwchar Subroutine), fgetws (getws or fgetws Subroutine), fread, fscanf, getc (getc, getchar, fgetc, or getw Subroutine), getchar (getc, getchar, fgetc, or getw Subroutine), gets (gets or fgets Subroutine), or scanf subroutine using a stream that returns data not supplied by a prior call to the ungetc or ungetwc subroutine.

Note

The fread subroutine is a buffered read subroutine library call. It reads data in 4KB blocks. For tape block sizes greater than 4KB, use the open (open, openx, open64, creat, or creat64 Subroutine) subroutine and read subroutine.

The fwrite subroutine writes items from the array pointed to by the Pointer parameter to the stream pointed to by the Stream parameter. Each item's size is specified by the Size parameter. The fwrite subroutine writes the number of items specified by the NumberOfItems parameter. The file-position indicator for the stream is advanced by the number of bytes successfully written. If an error occurs, the resulting value of the file-position indicator for the stream is indeterminate.

The fwrite subroutine appends items to the output stream from the array pointed to by the Pointer parameter. The fwrite subroutine appends as many items as specified in the NumberOfItems parameter.

The fwrite subroutine stops writing bytes if an error condition is encountered on the stream, or when the number of items of data specified by the NumberOfItems parameter have been written. The fwrite subroutine does not change the contents of the array pointed to by the Pointer parameter.

The st_ctime and st_mtime fields will be marked for update between the successful run of the fwrite subroutine and the next completion of a call to the fflush (fclose or fflush Subroutine) or fclose subroutine on the same stream, the next call to the exit (exit, atexit, _exit, or _Exit Subroutine) subroutine, or the next call to the abort (abort Subroutine) subroutine.

Parameters

Pointer	Points to an array.
Size	Specifies the size of the variable type of the array pointed to by the Pointer parameter. The Size parameter can be considered the same as a call to sizeof subroutine.
NumberOfItems	Specifies the number of items of data.
Stream	Specifies the input or output stream.

Return Values

The fread and fwrite subroutines return the number of items actually transferred. If the NumberOfItems parameter contains a 0, no characters are transferred, and a value of 0 is returned. If the NumberOfItems parameter contains a negative number, it is translated to a positive number, since the NumberOfItems parameter is of the unsigned type.

Error Codes

If the fread subroutine is unsuccessful because the I/O stream is unbuffered or data needs to be read into the I/O stream's buffer, it returns one or more of the following error codes:

EAGAIN	Indicates that the O_NONBLOCK flag is set for the file descriptor specified by the Stream parameter, and the process would be delayed in the fread operation.
EBADF	Indicates that the file descriptor specified by the Stream parameter is not a valid file descriptor open for reading.
EINTR	Indicates that the read operation was terminated due to receipt of a signal, and no data was transferred.

Note

Depending upon which library routine the application binds to, this subroutine may return EINTR. Refer to the signal subroutine regarding sa_restart.

EIO	Indicates that the process is a member of a background process group attempting to perform a read from its controlling terminal, and either the process is ignoring or blocking the SIGTTIN signal or the process group has no parent process.
ENOMEM	Indicates that insufficient storage space is available.
ENXIO	Indicates that a request was made of a nonexistent device.

If the fwrite subroutine is unsuccessful because the I/O stream is unbuffered or the I/O stream's buffer needs to be flushed, it returns one or more of the following error codes:

EAGAIN	Indicates that the O_NONBLOCK flag is set for the file descriptor specified by the Stream parameter, and the process is delayed in the write operation.
EBADF	Indicates that the file descriptor specified by the Stream parameter is not a valid file descriptor open for writing.
EFBIG	Indicates that an attempt was made to write a file that exceeds the file size of the process limit or the systemwide maximum file size.
EINTR	Indicates that the write operation was terminated due to the receipt of a signal, and no data was transferred.
EIO	Indicates that the process is a member of a background process group attempting to perform a write to its controlling terminal, the TOSTOP signal is set, the process is neither ignoring nor blocking the SIGTTOU signal, and the process group of the process is orphaned.
ENOSPC	Indicates that there was no free space remaining on the device containing the file.
EPIPE	Indicates that an attempt is made to write to a pipe or first-in-first-out (FIFO) process that is not open for reading by any process. A SIGPIPE signal is sent to the process.

The fwrite subroutine is also unsuccessful due to the following error conditions:

ENOMEM	Indicates that insufficient storage space is available.
ENXIO	Indicates that a request was made of a nonexistent device, or the request was outside the capabilities of the device.

Related Information

The Input and Output Handling in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.