Skip to content
Tutorials Center
My learning

Topics

Lesson 124 of 171 ยท Input/Output and Files

Binary Files

Work with binary files in C++ - write and read raw bytes, fixed-size records, seekg/tellg random access, padding pitfalls, endianness and std::byteswap (C++23).

A text file stores numbers as characters: the value 1000000 takes seven bytes, '1' followed by six '0's, and has to be parsed back. A binary file stores the bytes of the value itself: an std::int32_t always takes exactly four bytes, no matter how big the number is. Binary files are smaller, much faster to read and write, and allow random access: if every record is 32 bytes, record number 1,000 starts at byte 32,000, and you can jump straight there. Images, audio, game saves, databases and network protocols are all binary formats.

The price is that binary files aren't human-readable, and you have to think about the exact byte layout: how big each type is, where the compiler inserts padding, and in which order the bytes of a number are stored. This lesson shows the stream functions for raw bytes (write, read, gcount), random access with seekg/seekp and tellg/tellp, the rules for which objects you may copy as bytes, and how to make files portable across machines with different endianness.

As in Reading and Writing Text Files, every example creates its files during the run.

Writing and reading raw bytes

Open the stream with std::ios::binary so that no newline translation happens on Windows. Then use the unformatted functions:

  • out.write(const char* data, std::streamsize count) writes count bytes starting at data.
  • in.read(char* data, std::streamsize count) reads up to count bytes into data.
  • in.gcount() tells you how many bytes the last read actually got.

Both functions work with char pointers, so to write an int you view its memory as bytes with reinterpret_cast. This is one of the few places where reinterpret_cast is normal and well-defined: any object's bytes may be accessed through char pointers.

C++ Write numbers as bytes and read them back

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 std::cin or std::getline), it gets the next line from this box.

The file is exactly 12 bytes: 4 for the int32_t and 8 for the double. As text, 1000000 plus 0.75 plus a separator would have taken 12 characters too, but a text file grows with the number of digits while the binary file never does, and reading it back needs no parsing at all.

The byte dump shows 40 42 0f 00. The value 1,000,000 is 0x000F4240 in hexadecimal, and our server's x86-64 CPU stores the least significant byte first. That's called little-endian, and it matters as soon as another machine reads the file; you'll deal with it below.

Use the fixed-width types from <cstdint> (std::int32_t, std::uint16_t, std::uint64_t) in binary formats. int and long have different sizes on different platforms (long is 8 bytes on Linux but 4 on Windows), and a file format must not depend on that.

Which objects can you write as bytes?

Copying an object's bytes to a file and back only works for trivially copyable types: types whose value lives entirely in their own bytes. Integers, floating-point numbers, enums, std::array of those, and plain structs made of them qualify. Check with std::is_trivially_copyable_v<T>.

Types that own memory elsewhere don't. A std::string or std::vector holds a pointer to its characters. Writing its bytes saves an address that will be meaningless when the file is read in another run, and reading those bytes back into a string object is undefined behavior. Pointers, references and classes with virtual functions have the same problem. To store such data, write it field by field: the length first, then the characters.

C++
void write_string(std::ostream& out, const std::string& s) {
    auto length = static_cast<std::uint32_t>(s.size());
    out.write(reinterpret_cast<const char*>(&length), sizeof length);
    out.write(s.data(), length);              // the characters themselves, not the string object
}

Fixed-size records and padding

The classic binary file is an array of fixed-size records. Since every record has the same size, record i starts at byte i * sizeof(Record). Before you rely on sizeof, though, look at what the compiler does to your struct: it inserts padding so that each member is properly aligned (see Memory Layout).

C++ A file of fixed-size records

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 std::cin or std::getline), it gets the next line from this box.

The fields add up to 26 bytes, but sizeof(Product) is 32. Here's where the extra bytes go: id (4) and name (12) fill bytes 0 to 15, stock takes bytes 16 and 17, and then six padding bytes push price to offset 24, because a double must start at a multiple of 8. Those padding bytes are written to the file too. Padding is implementation-defined: another compiler or platform may choose differently, which is one more reason to treat a struct dump as a format only for the same program on the same platform.

To shrink records and make the layout explicit, order members from largest to smallest alignment (double, then uint32_t, then uint16_t, then char arrays), or write each field separately. Compiler-specific "packed" attributes exist but cause slow or crashing misaligned accesses on some CPUs; avoid them unless you know you need them.

Moving around: seekg, seekp, tellg and tellp

Every file stream has a position: the byte offset where the next read or write happens. Input streams use the "get" position (tellg to ask, seekg to move); output streams use the "put" position (tellp, seekp). With an std::fstream, use the one that matches the next operation.

seekg comes in two forms:

C++
in.seekg(100);                      // absolute: byte 100 from the start
in.seekg(-8, std::ios::end);        // relative to the end: 8 bytes before it
in.seekg(4, std::ios::cur);         // relative to the current position

A common use is finding a file's size: seek to the end and ask for the position. (std::filesystem::file_size does the same without opening the file.) Combined with std::fstream, seeking also lets you update a record in place without rewriting the whole file:

C++ Update one record in place with fstream

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 std::cin or std::getline), it gets the next line from this box.

Two details in this program trip up many people:

  • After a read hits the end, the stream is in the eof/fail state, and seeking doesn't work until you clear() it. The dump function clears the flags before returning.
  • A read that gets fewer bytes than requested sets failbit, but the bytes it did get are still in the buffer. gcount() tells you how many: here 8 of 16. Always check it when a file might be truncated.

In an std::fstream, switching between reading and writing also requires a seek (or a flush) in between. The example always seeks before changing direction, which is the safe habit.

Endianness and portable formats

Multi-byte numbers can be stored in two byte orders:

  • Little-endian: least significant byte first. x86, x86-64 and, in practice, ARM (Android, iOS, Apple silicon) use it.
  • Big-endian: most significant byte first. It's the traditional "network byte order" used by many internet protocols and older file formats, and some embedded and mainframe CPUs use it natively.

If you dump an std::uint32_t on a little-endian machine and read it on a big-endian one, 0x000F4240 comes back as 0x40420F00. A portable file format therefore defines its byte order, and the code converts. C++20 lets you ask which order the machine uses with std::endian from <bit>, and C++23 adds std::byteswap, which reverses the bytes of an integer.

C++ Writing a fixed byte order with std::byteswap

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 std::cin or std::getline), it gets the next line from this box.

The bytes on disk are 12 34 56 78 | 07 ea, most significant first, regardless of the machine that wrote them. if constexpr means the swap only exists in the compiled code on little-endian machines. std::byteswap is available in GCC 12+, Clang 14+ and MSVC 19.31+.

Another fully portable technique, which also works on compilers without C++23, builds the bytes with shifts: bytes[0] = (v >> 24) & 0xFF; bytes[1] = (v >> 16) & 0xFF; ... and reassembles them the same way. Shifts operate on values, not memory, so the result never depends on the CPU's byte order.

Floating-point values can be converted the same way by first turning them into same-sized integers with C++20's std::bit_cast<std::uint64_t>(x). Nearly every platform today uses IEEE 754 for float and double, so that's portable in practice.

Designing a small file format

Robust binary formats start with a header: a "magic number" that identifies the file type, a version number, and counts or sizes of what follows. A reader checks the header first and rejects files that don't match, instead of misinterpreting random bytes. PNG files, for example, start with the bytes 89 50 4E 47.

C++ A header with magic number, version and count

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 std::cin or std::getline), it gets the next line from this box.

Notice the sanity check on count. Data read from a file is untrusted input: a corrupted or malicious file could claim four billion entries and make resize allocate gigabytes. Validate every size before using it. The truncated file is caught by comparing gcount() with the expected byte count. This format writes integers in native byte order to keep the example short; a real format would use write_be/read_be from the previous example (or little-endian helpers) for every field.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does sizeof report for struct R { std::uint32_t a; double b; }; on a typical 64-bit platform?

    The double needs 8-byte alignment, so the compiler inserts padding after a. Padding is implementation-defined, which is why struct dumps aren't portable.
  2. 2. Why can't you save a std::string by writing its object bytes with write(reinterpret_cast<const char*>(&s), sizeof s)?

    Only trivially copyable types can be copied as bytes. Write the length and then s.data() instead.
  3. 3. A file has 8 bytes left and you call in.read(buf, 16). What is the result?

    A short read stores what it could, sets failbit (and eofbit), and reports the number of bytes through gcount().
  4. 4. Your program reads until the end of a binary file and then calls seekg(0) to read it again, but nothing is read. Why?

    A failed stream ignores operations, including seeks. clear() resets the flags.
  5. 5. On a little-endian machine, which bytes does writing std::byteswap(std::uint16_t{0x0102}) with write() put on disk?

    byteswap turns 0x0102 into 0x0201. A little-endian machine stores the low byte (01) first, so the disk holds 01 02, which is the original value in big-endian order.

Summary

  • Open binary files with std::ios::binary and use write, read and gcount with reinterpret_cast<char*> to the object's bytes.
  • Only trivially copyable types (numbers, enums, plain structs, std::array) may be copied as bytes; write strings and vectors as length plus data.
  • Use <cstdint> fixed-width types; sizeof of a struct includes implementation-defined padding.
  • seekg/seekp move the read and write positions, tellg/tellp report them; clear() a failed stream before seeking.
  • Byte order differs between machines: define it in your format and convert with std::endian and std::byteswap (C++23) or with shifts.
  • Start formats with a magic number and version, and validate every size read from a file.

Next: String Streams, where you'll parse and build text in memory with the stream interface.