C Reference ยท stdio.h
C fread() and fwrite() functions
Reference for C fread() and fwrite(): read and write blocks of bytes, arrays and structs, how the item count return value works and what portability traps to avoid.
fwrite() copies a block of memory into a stream, and fread() copies a block from a stream into memory. Neither converts anything: the bytes in the file are exactly the bytes in your variables. That makes them the right tools for binary files, arrays of numbers, images, and any data that is not text.
Both functions describe the block as count items of a given size, and both return the number of items transferred, not the number of bytes. A return value smaller than the count means the end of the file or an error.
#include <stdio.h> size_t fread(void *restrict buf, size_t size, size_t count, FILE *restrict stream); size_t fwrite(const void *restrict buf, size_t size, size_t count, FILE *restrict stream);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Syntax
size_t fread(void *restrict buf, size_t size, size_t count, FILE *restrict stream); size_t fwrite(const void *restrict buf, size_t size, size_t count, FILE *restrict stream);
| Name | Description |
|---|---|
buf |
Memory to fill (fread) or to copy from (fwrite). It must hold at least size * count bytes. |
size |
Size of one item in bytes, usually sizeof an element or a struct. |
count |
Number of items to transfer. |
stream |
An open stream, preferably in binary mode ("rb", "wb"). |
Returns: the number of complete items transferred. On success it equals count. A smaller value means end of file (fread) or an error. If size or count is zero, the result is zero and nothing happens.
Errors / undefined behavior: a buf that is too small, or a closed or wrong-direction stream, is undefined behavior. After a short result, use feof() and ferror() to tell end of file from an error. If an item is only partly read, the contents of that item are indeterminate.
Usage notes
- Compare against
count, not zero.if (fwrite(a, sizeof a[0], n, f) != n)is the right error check. Forfread(), a smaller number may be perfectly fine at the end of a file. - Binary mode. On Windows, open with
"rb"and"wb"; text mode would translate bytes. On Linux thebis harmless. - The file is not portable. Integers are written in the machine's byte order and with its sizes (see endianness). Structs include padding bytes, whose values are unspecified. Files meant to be shared between systems should use fixed-width types and be written field by field.
- Pointers inside data are meaningless when read back. Never
fwrite()a struct that holds achar *and expect the string to be in the file. - Reading one big item.
fread(buf, 1, n, f)returns a byte count and is convenient for "read up to n bytes".fread(buf, n, 1, f)returns 1 or 0 and cannot tell you how much of a partial block arrived. - Switching direction on a read/write stream needs an
fflush()or a positioning call such asfseek()between the reads and writes. - Speed. One call per block is much faster than a loop of
fgetc()orfputc()calls. Buffers of 4 KB or more are a good default. - Not for text. Strings with
'\0'or line endings are better handled byfgets()andfprintf().