File Streams

Working with files typically forms a big part of our C++ projects. We often need to read data from and write data to locations on the user's file system.

To do this, we use file streams. As the name suggests, these are streams, so we'll be leaning heavily on what we learned in our previous chapter. File streams are direct children of istream and ostream, so often we'll be using the exact same methods.

The standard library's implementation of file streams is available within the fstream header:

1#include <fstream>

We have three main options for creating file streams:

• std::ifstream - An input stream, used for reading data from a file. This inherits from std::istream.
• std::ofstream - An output stream, used for writing data to a file. This inherits from std::ostream.
• std::fstream - A bidirectional stream, which allows us to both read and write data to the same file. This inherits from std::iostream, which in turn inherits from both std::istream and std::ostream

Opening and Closing a File Stream

In this lesson, we’ll work mostly with the bidirectional fstream object. We can construct it without any arguments:

1#include <fstream>
2
3int main() {
4  std::fstream File;
5}

We do not need to provide a path to a specific file during construction. Instead, we can connect our stream to a file in the underlying file system at any time using the open() method, and we close that connection using close()

1#include <fstream>
2
3int main() {
4  std::fstream File;
5  File.open(R"(c:\test\file.txt)");
6  // Use the file, then close it
7  File.close();
8}

A file stream does not necessarily have a one-to-one mapping to a file. We can reuse the file stream for different files:

1#include <fstream>
2#include <iostream>
3
4int main() {
5  std::fstream File;
6
7  File.open(R"(c:\test\file1.txt)");
8  // Do stuff
9  File.close();
10
11  File.open(R"(c:\test\file2.txt)");
12  // Do stuff
13  File.close();
14}

Building on what we covered in the previous lesson, we can pass a std::filesystem::path object to open():

1#include <filesystem>
2#include <fstream>
3namespace fs = std::filesystem;
4
5int main() {
6  std::fstream File;
7  fs::path Path{R"(c:\test\file.txt)"};
8
9  File.open(Path);
10
11  File.close();
12}

Or, we can pass a std::filesystem::directory_entry:

1#include <filesystem>
2#include <fstream>
3namespace fs = std::filesystem;
4
5int main() {
6  std::fstream File;
7  fs::directory_entry DirectoryEntry{
8      R"(c:\test\file.txt)"};
9
10  File.open(DirectoryEntry);
11
12  File.close();
13}

We can check if a file is open using the is_open() method:

1#include <fstream>
2#include <iostream>
3
4int main() {
5  std::fstream File;
6
7  File.open(R"(c:\test\file.txt)");
8  if (File.is_open()) {
9    std::cout << "File is open";
10  }
11}

1File is open

Generally, we should not open a file until we need it. However, we do have the option to open the file at the same time we create the file stream. We can do this by passing a path to the constructor:

1#include <fstream>
2#include <iostream>
3
4int main() {
5  std::fstream File{R"(c:\test\file.txt)"};
6
7  if (File.is_open()) {
8    std::cout << "File is open";
9  }
10}

1File is open

Open Modes

In addition to passing the path to the open() function or the file stream constructor, we can pass a second argument, specifying the open mode. Open modes define what we can do with our file, and how some of our operations behave.

• std::ios::in - Allow input to be read from the file. This is enabled by default for input and bidirectional file streams
• std::ios::out - Allows output to be written to the file. This is enabled by default for output and bidirectional file streams
• std::ios::ate ("at end") - move the input and output positions to the end of the file upon opening
• std::ios::app ("append") - write operations are done at the end of the file, regardless of where the output position is
• std::ios::binary - open the file in binary mode. We cover binary streams in more detail later in the chapter
• std::ios::trunc ("truncate") - when the file is opened, its existing contents are deleted
• std::ios::noreplace - if the file we’re opening already exists, throw an exception. In other systems, this sometimes is referred to as opening the file in "exclusive mode".

The noreplace flag was added in C++23 and is not yet supported on all compilers, but can be replicated in other ways. For example, we can check whether a file exists using the fs::exists function, or the exists() method on an fs::directory_entry.

Open modes are provided as the second argument to open() or as the second argument to the file stream constructor:

1#include <filesystem>
2#include <fstream>
3namespace fs = std::filesystem;
4using std::ios;
5
6int main() {
7  std::fstream File;
8  fs::path Path{R"(c:\test\file.txt)"};
9
10  File.open(Path, ios::out);
11
12  File.close();
13}

Open modes are a bitmask, so we can combine multiple modes using the | operator:

1#include <filesystem>
2#include <fstream>
3namespace fs = std::filesystem;
4using std::ios;
5
6int main() {
7  std::fstream File;
8  fs::path Path{R"(c:\test\file.txt)"};
9
10  File.open(Path, ios::out | ios::noreplace);
11
12  File.close();
13}

Open Mode Interactions and Creating Files

We can combine open modes in dozens of different ways. Unfortunately, how these combinations interact is not always obvious. For example, if the file we’re trying to open doesn’t exist, it might get created, or it might not. It depends on the open modes we set.

The file will be created in the following scenarios:

• Output mode (std::ios::out) is set, and input mode (std::ios::in) is not set. This is the default behavior of an output file stream. Therefore, if we open() a std::ofstream without passing any flags, std::ios::out will be set in isolation, and the file will be created if it doesn’t already exist.
• Append mode (std::ios::app) or truncate mode (std::ios::trunc) is set, regardless of any other flags.

Aside from this, there are many more unintuitive behaviors and interactions between open modes. Some combinations will throw errors. Some combinations will work but behave in ways we weren't expecting. This is a common source of confusion and bugs.

In general, if your code is compiling but your file is not being written to or updated in the way we expect, the issue is almost always the combination of open modes we’ve selected.

It’s much too complex to memorize all the interactions - we can just look them up when needed. A full table of the interactions is available on a standard library reference, such as cppreference.com.

File Error Handling

File streams have the same error-handling mechanisms as any other stream. We covered those in the previous chapter, and will talk about them in more detail a little later in this lesson,

However, file streams have unique error scenarios we need to consider, caused by their interactions with the underlying filesystem.

Usually, the first error we’ll want to check for when working with files is whether the file is open when we expect it to be.

We can do that with the is_open() method. In the following examples, we’re creating an error by trying to open a file that already exists, using the noreplace open mode.

1#include <filesystem>
2#include <fstream>
3#include <iostream>
4namespace fs = std::filesystem;
5using std::ios;
6
7int main() {
8  std::fstream File;
9  fs::path Path(R"(c:\test\file.txt)");
10  File.open(Path, ios::out | ios::noreplace);
11
12  if (!File.is_open()) {
13    std::cout << "The file was not opened";
14  }
15  File.close();
16}

1The file was not opened

As we covered in our lesson on output streams, we can use the exceptions() method to cause our stream to throw exceptions when it encounters errors. The exception type will be a std::ios::failure:

1#include <filesystem>
2#include <fstream>
3#include <iostream>
4namespace fs = std::filesystem;
5using std::ios;
6
7int main() {
8  std::fstream File;
9  fs::path Path(R"(c:\test\file.txt)");
10  File.exceptions(ios::failbit | ios::badbit);
11
12  try {
13    File.open(Path, ios::out | ios::noreplace);
14  } catch (const std::ios::failure& e) {
15    std::cout << "The file was not opened";
16  }
17  File.close();
18}

1The file was not opened

This exception has a what() and code() method, but they’re not especially useful in this scenario. When we want to find out what went wrong when accessing the file system, we usually need to talk to the operating system, and each system handles and reports errors differently.

System-Specific File Errors

We generally focus on portable code (ie, things that work across as many systems as possible), but we’ll briefly introduce some ways of working with system-specific issues here. For this example, we’ll assume our code is being built for Windows.

By including the windows.h header, we get access to some additional functions.

The GetLastError() function returns the error code of the last issue that occurred on the thread that called it:

1#include <windows.h>
2#include <filesystem>
3#include <fstream>
4#include <iostream>
5namespace fs = std::filesystem;
6using std::ios;
7
8int main() {
9  std::fstream File;
10  fs::path Path(R"(c:\test\file.txt)");
11  File.open(Path, ios::out | ios::noreplace);
12
13  if (!File.is_open()) {
14    std::cout << "Error: " << GetLastError();
15  }
16}

1Error: 80

All the Windows error codes are listed on the official Microsoft site.

In this example, the 80 error code relates to a file already existing. We can use these error codes to have our code react appropriately to specific problems we anticipate might happen.

The standard library also provides access to an object that can help us with system errors. This can be accessed through the std::system_category() function from <system_error>.

This object has a few useful utilities, including the ability to generate an error message from an operator-system-specific error code:

1#include <windows.h>
2#include <filesystem>
3#include <fstream>
4#include <iostream>
5#include <system_error>
6namespace fs = std::filesystem;
7using std::ios;
8
9int main() {
10  std::fstream File;
11  fs::path Path(R"(c:\test\file.txt)");
12  File.open(Path, ios::out | ios::noreplace);
13
14  if (!File.is_open()) {
15    std::cout << std::system_category().message(
16        GetLastError());
17  }
18}

1The file exists.

Using File Streams

Once we’ve opened our file stream, we just use it like we would any other input and output stream. We covered input and output streams in detail here:

Output Streams

A detailed overview of C++ Output Streams, from basics and key functions to error handling and custom types.

Input Streams

A detailed introduction to C++ Input Streams using std::cin and istringstream. Starting from the basics and progressing up to advanced use cases including creating collections of custom objects from our streams.

The rest of this lesson covers no new topics - it just shows examples of how the concepts covered in those lessons also work as we’d expect with file streams.

Writing to a File

We write to files using the same methods we write to other output streams, such as the << operator, the put() function, and the write() function:

1#include <fstream>
2#include <iostream>
3
4int main() {
5  std::fstream File;
6  File.open(R"(c:\test\file.txt)");
7  File << "Hello World";
8  File.close();
9}

After running this code, we should have the file defined within path containing the "Hello World" content.

Reading from a File

We read from files in the same way we read from other input streams, using the >> operator, and methods such as get() and getline().

1#include <fstream>
2#include <iostream>
3
4int main() {
5  std::string Content;
6
7  std::fstream File;
8  File.open(R"(c:\test\file.txt)");
9  std::getline(File, Content);
10  File.close();
11
12  std::cout << Content;
13}

This program should print out the first line of the file we specified within our open() call:

1Hello World

File Stream Read and Write Position

Like any other stream, file streams can have input and output positions. We use tellp() and seekp() to access and change the output position, whilst tellg() and seekg() work with the input position.

1#include <fstream>
2#include <iostream>
3
4std::fstream File;
5
6void ReadFile() {
7  File.seekg(0);
8  std::cout << "File Contents:\n"
9            << File.rdbuf() << "\n\n";
10}
11
12void ReadCharacter(int Position) {
13  File.seekp(Position);
14  std::cout << "Character at Input Position "
15            << File.tellp() << ": "
16            << static_cast<char>(File.get())
17            << "\n";
18}
19
20void WriteString(std::string String,
21                 int Position) {
22  File.seekg(Position);
23  std::cout << "Writing \"" << String
24            << "\" to Output Position "
25            << File.tellg() << "\n\n";
26  File << String;
27}
28
29int main() {
30  File.open(R"(c:\test\file.txt)");
31
32  ReadFile();
33  ReadCharacter(0);
34  ReadCharacter(3);
35  ReadCharacter(6);
36  WriteString("Everyone", 6);
37  ReadFile();
38
39  File.close();
40}

1File Contents:
2Hello World
3
4Character at Input Position 0: H
5Character at Input Position 3: l
6Character at Input Position 6: W
7Writing "Everyone" to Output Position 6
8
9File Contents:
10Hello Everyone

When we call open(), the input and output positions are reset:

1#include <fstream>
2#include <iostream>
3
4int main() {
5  std::fstream File{};
6
7  File.open(R"(c:\test\file1.txt)");
8  File.seekp(5);
9  std::cout << "Output position: "
10            << File.tellp();
11  File.close();
12
13  File.open(R"(c:\test\file2.txt)");
14  std::cout << "\nOutput position: "
15            << File.tellp();
16  File.close();
17}

1Output position: 5
2Output position: 0

Stream Error Handling

As with the streams we covered in previous lessons, file streams have internal states that we can use to check for errors.

They set failbit, badbit, and eofbit in the usual way, which we can check for directly using rdstate(), or shorthand methods like good() and fail(). Below, we read characters until our stream runs out of content:

1#include <fstream>
2#include <iostream>
3
4int main() {
5  std::fstream File;
6  File.open(R"(c:\test\file.txt)");
7
8  while (File.good()) {
9    std::cout << static_cast<char>(File.get());
10  }
11
12  File.close();
13}

1Hello World

We can also use the exceptions method, to cause our streams to throw once something goes wrong. In the following example, we’re trying to read from a file that has no content:

1#include <fstream>
2#include <iostream>
3using std::ios;
4
5int main() {
6  std::fstream File;
7  File.exceptions(ios::badbit | ios::failbit);
8  File.open(R"(c:\test\no-content.txt)");
9
10  try {
11    std::cout.put(File.get());
12  } catch (const std::ios::failure& e) {
13    std::cout << e.code() << '\n';
14    std::cout << e.what();
15  }
16  File.close();
17}

Typically, the error codes and messages are not very descriptive:

1iostream:1
2ios_base::failbit set: iostream stream error

If we need to understand the error, we must rely on OS-specific methods, as described in the previous section.

For example, on Windows, this specific scenario would generate a 131 error code from GetLastError().

Passing this to the message() method of the object returned from std::system_category() yields the string: "An attempt was made to move the file pointer before the beginning of the file."

The message is a little cryptic, but it means we tried to read content from our stream (using get()) when the output position was outside the bounds of the file.

Saving and Loading State from Files

The following example shows how we can use file streams to create a rudimentary save/load feature.

The following class gives its objects the ability to save and load their state from a stream. Remember, file streams inherit from the basic stream types, so:

• an ifstream is an istream
• an ofstream is an ostream
• an fstream is an iostream, which is both an istream and an ostream.

Our functions accept references by the base type, as they do not need to be restricted to just working with file streams.

1#pragma once
2#include <iostream>
3
4class Character {
5 public:
6  void Save(std::ostream& Stream) {
7    Stream << Name << ' ' << Level;
8  }
9
10  void Load(std::istream& Stream) {
11    Stream >> Name;
12    Stream >> Level;
13  }
14
15  std::string Name;
16  int Level;
17};

Over in our main function, we check if a save file exists. If it does, we load our previous state; otherwise, we start from a clean slate.

1#include <filesystem>
2#include <fstream>
3#include <iostream>
4#include "Character.h"
5
6namespace fs = std::filesystem;
7
8int main() {
9  Character Player;
10
11  std::fstream File;
12  fs::directory_entry SaveFile{
13      R"(c:\test\savefile.txt)"};
14
15  if (SaveFile.is_regular_file()) {
16    std::cout << "Loading a saved game\n";
17    File.open(SaveFile, std::ios::in);
18    Player.Load(File);
19  } else {
20    std::cout << "Starting a new game\n";
21    File.open(SaveFile, std::ios::out);
22    Player.Name = "Conan";
23    Player.Level = 1;
24    Player.Save(File);
25  }
26
27  File.close();
28
29  std::cout << "Name: " << Player.Name;
30  std::cout << "\nLevel: " << Player.Level;
31}

The first time we run the program, we get this output:

1Starting a new game
2Name: Conan
3Level: 1

On subsequent runs, we get this:

1Loading a saved game
2Name: Conan
3Level: 1

This process of converting our objects into forms that we can store on disk, or send across the internet, is called serialization.

We expand this concept to more complex use cases in the rest of this chapter.

Summary

In this lesson, we explored the fundamental aspects of file streams in C++, covering how to open, read, write, and handle files. We also delved into understanding the various file stream open modes, error handling techniques, and practical applications, enhancing your proficiency in managing file operations.

Key Takeaways:

• Learned the basics of file streams in C++ using std::fstream, std::ifstream, and std::ofstream, and their inheritance from istream and ostream.
• Explored how to open and close file streams, and the versatility of file streams in handling multiple files.
• Understood the different open modes (std::ios::in, std::ios::out, std::ios::ate, etc.) and their implications in file operations.
• Gained insights into error handling in file streams, including the use of is_open(), std::ios::failure, and system-specific error handling methods.
• Discussed the concept of serialization and its application in saving and loading object states from files.

Next Lesson

Installing vcpkg on Windows

An introduction to C++ package managers, and a step-by-step guide to installing vcpkg on Windows and Visual Studio.

ContinueView Course