Reads and writes binary files.
Standard C Library (libc.a)
#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);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.
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, unatexit, _exit, or _Exit Subroutine) subroutine, or the next call to the abort (abort Subroutine) subroutine.
| Item | Description |
|---|---|
| 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. |
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.
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:
| Item | Description |
|---|---|
| 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. |
| Item | Description |
|---|---|
| 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:
| Item | Description |
|---|---|
| EAGAIN | Indicates that the O_NONBLOCK or O_NDELAY 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:
| Item | Description |
|---|---|
| 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. |