Working with the File System in C++

A detailed introduction to using the filesystem in C++. Create, delete, move, and navigate through directories and files using the std::filesystem library.

This lesson is part of the course:

Professional C++

Comprehensive course covering advanced concepts, and how to use them on large-scale projects.

Ryan McCombe

Posted 6 months ago

In this lesson, we’ll take a tour of the standard library functionality that helps us work with file systems in a platform-agnostic way.

The file system functionality is available by including <filesystem>

1#include <filesystem>
2

Most of the functions and types we’ll be using are within the std::filesystem namespace, which we’ll alias to fs to keep our code less verbose:

1namespace fs = std::filesystem;
2

Directory Entry

A directory_entry is the main type we use to refer to objects within our file system, such as files and directories. We can initialize a directory_entry by passing the path to it on our hard drive.

1#include <filesystem>
2
3int main() {
4  namespace fs = std::filesystem;
5  fs::directory_entry Directory{"c:/test"};
6}
7

Given paths often include backslashes, we typically populate them from raw strings. This means we don’t need to escape the back slashes, which keeps our paths readable:

1#include <filesystem>
2
3int main() {
4  namespace fs = std::filesystem;
5  fs::directory_entry Directory{R"(c:\test)"};
6}
7

Directory entries have a lot of useful methods we can use to investigate the nature of what our path is pointing at.

For example, we can check if an entry exists at the path by using the exists() method. We can also check if it is a directory or file by using the is_directory() and is_regular_file() methods.

In the following example, c:\test is a directory on our hard drive:

1#include <filesystem>
2#include <iostream>
3
4int main() {
5  namespace fs = std::filesystem;
6  fs::directory_entry Directory{R"(c:\test)"};
7  if (Directory.exists()) {
8    std::cout << "The location exists";
9  }
10
11  if (Directory.is_directory()) {
12    std::cout << "\nIt is a directory";
13  }
14
15  if (!Directory.is_regular_file()) {
16    std::cout << "\nIt is not a file";
17  }
18}
19

1The location exists
2It is a directory
3It is not a file
4

“Regular” Files?

Almost all of the files we’re familiar with on our hard drives - documents, images, executables, and more, are considered regular files.

Beyond directories and regular files, there are several other things that can exist within our file systems, such as block files and symbolic links. For this lesson, we’ll just focus on directories and regular files.

Creating a Directory

We can create a directory using the create_directory() function, passing a path to the directory we want to create.

1#include <filesystem>
2
3int main() {
4  namespace fs = std::filesystem;
5  fs::create_directory(R"(c:\test)");
6}
7

The function will return true if the directory was created.

1#include <filesystem>
2#include <iostream>
3
4int main() {
5  namespace fs = std::filesystem;
6  bool success{
7      fs::create_directory(R"(c:\test)")};
8
9  if (success) {
10    std::cout << "Directory created";
11  } else {
12    std::cout << "Directory not created";
13  }
14}
15

1Directory not created
2

There are two possible reasons the directory will not be created:

it already exists, as in this case, or
an error was reported from the operating system

We’ll cover errors in more detail later in this lesson.

Deeply Creating a Directory

Sometimes, we’ll want to create a directory structure that is multiple levels deep. For example, we may want to create c:\test\subdirectory, when c:\test does not yet exist.

Using the create_directories method, we can specify the exact directory we want, and if any intermediate directories are missing, they will be created too:

1#include <filesystem>
2
3int main() {
4  namespace fs = std::filesystem;
5
6  fs::create_directories(
7      R"(c:\deeply\nested\directory)");
8}
9

File System Exceptions and Errors

Many of the functions in this lesson can throw exceptions. We can catch these in the normal way, using a try-catch block. The type of exception thrown by file system errors is std::filesystem::filesystem_error.

Like any standard library exception, they have a what() method that we can use to get a description of the error.

For more programmatic error handling, we’re likely to want to use the code() method instead. This returns a numeric error code that is much easier to work with than the string output of what()

1#include <filesystem>
2#include <iostream>
3
4int main() {
5  namespace fs = std::filesystem;
6
7  try {
8    fs::create_directory(R"(k:\fake)");
9  } catch (fs::filesystem_error e) {
10    std::cout << e.code() << '\n';
11    std::cout << e.what();
12  }
13}
14

1system:3
2create_directory: The system cannot find
3the path specified.: "k:\fake"
4

The meaning of error codes depends on the operating system our program is running on. The previous example is from Windows, which uses the following error codes: https://learn.microsoft.com/en-us/windows/win32/debug/system-error-codes

Getting File Size with `file_size()`

When our directory_entry is pointing at a file, we can use the file_size method to return its size in bytes:

1#include <filesystem>
2#include <iostream>
3
4int main() {
5  namespace fs = std::filesystem;
6
7  fs::directory_entry File{
8      R"(c:\test\hello.txt)"};
9
10  std::cout << "File Size: " << File.file_size()
11            << " bytes";
12}
13

1File Size: 24 bytes
2

Getting the last modified time with `last_write_time()`

We can find the time a file or directory was last modified by using the last_write_time() method on our directory_entry:

1#include <filesystem>
2#include <iostream>
3
4int main() {
5  namespace fs = std::filesystem;
6
7  fs::directory_entry File{
8      R"(c:\test\hello.txt)"};
9
10  std::cout << "Last Write Time:\n"
11            << File.last_write_time();
12}
13

1Last Write Time:
22023-06-10 23:10:33.4202407
3

Copying Files with `copy_file`

We can copy files using the copy_file method, with two arguments. The first argument is the path to the file we want to copy. The second argument is the path we want to copy it to:

1#include <filesystem>
2
3int main() {
4  namespace fs = std::filesystem;
5
6  fs::copy_file(R"(c:\test\hello.txt)",
7                R"(c:\test\hi.txt)");
8
9

We can pass an additional third argument to copy_file, which lets us define how our code should behave if the path defined by the second argument already exists.

In such a scenario, our copy_file call risks overwriting a file.

The std::filesystem::copy_options enumeration contains our options for handling this. They are:

none - keep the existing file and throw an exception (default)
skip_existing - keep the existing file but do not throw an exception
overwrite_existing - overwrite the existing file
update_existing - overwrite the existing file if it’s older than the new file, as defined by the last_write_time

1#include <filesystem>
2
3int main() {
4  namespace fs = std::filesystem;
5
6  fs::copy_file(
7      R"(c:\test\hello.txt)",
8      R"(c:\test\hi.txt)",
9      fs::copy_options::skip_existing);
10}
11

Copying a Directory with `copy`

We can copy a directory with the copy method.

Similar to copy_file, we can pass options to define how the copy action works. When dealing with overwriting existing files, we have the same 4 options we had with copy_file.

We can also pass up to two additional options that take effect when what we’re copying is a directory:

recursive - Recursively copy subdirectories
directories_only - Only copy the directory structure - ignore files

Both options are disabled by default, but we can enable them as needed, and we can enable multiple options by combining them with the | operator:

1#include <filesystem>
2#include <iostream>
3
4int main() {
5  namespace fs = std::filesystem;
6
7  fs::copy(
8      R"(c:\test)", R"(c:\test2)",
9      fs::copy_options::skip_existing |
10          fs::copy_options::recursive |
11          fs::copy_options::directories_only);
12}
13

Additional copy options are available when we’re dealing with things like symbolic links, but that’s out of scope for now.

Note, the copy function can copy a file - it is not restricted to just copying a directory. However, if we're copying a file, the copy_file method makes our intent much clearer and has built in error-checking to ensure the target actually is a file. So, when copying a file, using the copy_file method tends to be recommended.

Removing a File or Directory using `remove()`

We can remove a file or directory using the remove function:

1#include <filesystem>
2
3int main() {
4  namespace fs = std::filesystem;
5  fs::remove(R"(c:\test)");
6}
7

When the path we provide points to a directory that is not empty, an exception is thrown

1#include <filesystem>
2#include <iostream>
3
4int main() {
5  namespace fs = std::filesystem;
6
7  try {
8    fs::remove(R"(c:\test)");
9  } catch (fs::filesystem_error e) {
10    std::cout << "Code: " << e.code()
11              << "\nError: " << e.what();
12  }
13}
14

1Code: system:145
2Error: remove: The directory is not empty.: "c:/test"
3

When we’re trying to remove a directory, and we want to get rid of everything inside it too, we can use the remove_all method.

Removing a directory and all contents using `remove_all()`

The remove_all() method removes a directory and all of its contents. It returns an integer, representing how many files and directories were removed.

1#include <filesystem>
2#include <iostream>
3
4int main() {
5  namespace fs = std::filesystem;
6
7  uintmax_t filesDeleted{
8      fs::remove_all(R"(c:\test)")};
9
10  std::cout << "Deleted " << filesDeleted
11            << " files or directories";
12}
13

1Deleted 2 files or directories
2

Moving or Renaming Files and Directories with `rename()`

We can move or rename a file or directory using the rename() function. The first argument will be a path to the thing we want to move. The second argument will be the location we want to move it to.

1#include <filesystem>
2
3int main() {
4  namespace fs = std::filesystem;
5
6  fs::rename(R"(c:\test)", R"(c:\test2)");
7}
8

Getting Disk Space using `space()`

The space function lets us get more information about the storage space associated with a path. It returns a space_info struct, which has three fields:

capacity - The total capacity available at the location
free - The amount of space free at the location
available - The amount of space that is available for our program to write to. This will be less than or equal to the free space

All three values are in bytes:

1#include <filesystem>
2#include <iostream>
3
4int main() {
5  namespace fs = std::filesystem;
6  const fs::space_info si{fs::space(R"(c:\)")};
7
8  constexpr int bytesInGB{1024 * 1024 * 1024};
9
10  std::cout << "Capacity: "
11            << si.capacity / bytesInGB << "GB";
12  std::cout << "\nFree: " << si.free / bytesInGB
13            << "GB";
14  std::cout << "\nAvailable: "
15            << si.available / bytesInGB << "GB";
16}
17

1Capacity: 437GB
2Free: 277GB
3Available: 277GB
4

`std::filesystem::path`

In the previous examples, we’re representing our paths as simple strings, but the underlying type is a std::filesystem::path. This type has some additional useful functions specific to this use case.

path objects can be created from simple strings, which is what our code has been doing so far:

1#include <filesystem>
2
3int main() {
4  namespace fs = std::filesystem;
5  fs::path Location{R"(c:\test)"};
6}
7

We can get the string representation of a path using the string() method, which is useful when we want to display it:

1#include <filesystem>
2#include <iostream>
3
4int main() {
5  namespace fs = std::filesystem;
6  fs::path Location{R"(c:\test)"};
7
8  std::cout << Location.string();
9}
10

1c:\test
2

We can also get the path associated with a directory entry using the path() method:

1#include <filesystem>
2#include <iostream>
3
4int main() {
5  namespace fs = std::filesystem;
6  fs::directory_entry Entry{R"(c:\test)"};
7
8  std::cout << Entry.path().string();
9}
10

1c:\test
2

`path` methods

A variety of methods give us access to specific parts of the path. These also return path objects, so in the following example we use the string method to display them:

1#include <filesystem>
2#include <iostream>
3
4int main() {
5  namespace fs = std::filesystem;
6  fs::path Location{R"(c:\test\hello.txt)"};
7
8  std::cout << "File Name: "
9            << Location.filename().string();
10
11  std::cout << "\nFile Stem: "
12            << Location.stem().string();
13
14  std::cout << "\nFile Extension: "
15            << Location.extension().string();
16
17  std::cout << "\nParent Path: "
18            << Location.parent_path().string();
19
20  std::cout << "\nRoot Path: "
21            << Location.root_name().string();
22}
23

1File Name: hello.txt
2File Stem: hello
3File Extension: .txt
4Parent Path: c:\test
5Root Path: c:
6

Equivalent boolean methods are available that return true or false based on the existence of any of these path parts.

We can access these by prepending has_ to the method names. For example, has_filename() and has_extension()

1#include <filesystem>
2#include <iostream>
3
4int main() {
5  namespace fs = std::filesystem;
6
7  fs::path Directory{R"(c:\test\)"};
8  if (!Directory.has_filename()) {
9    std::cout << Directory.string()
10              << " has no file name\n";
11  }
12
13  fs::path File{R"(c:\hi.txt)"};
14  if (File.has_extension()) {
15    std::cout << File.string()
16              << " has a file extension";
17  }
18}
19

Note the result of these functions is based entirely on the format of the provided string.

These methods do not check the underlying file system. For example, the has_filename method returns true if it seems like the provided path has a file name. But, to check what actually exists at that location, we will need to create a directory_entry, not just a path.

Working with `path` file names

When working with paths, a common requirement is manipulate the file name, so we have some methods to help us there:

1#include <filesystem>
2#include <iostream>
3
4int main() {
5  namespace fs = std::filesystem;
6
7  fs::path File{R"(c:\test\hello.txt)"};
8  std::cout << File.string() << '\n';
9
10  File.replace_filename("world.txt");
11  std::cout << File.string() << '\n';
12
13  File.replace_extension("doc");
14  std::cout << File.string() << '\n';
15
16  File.remove_filename();
17  std::cout << File.string();
18}
19

1c:\test\hello.txt
2c:\test\world.txt
3c:\test\world.doc
4c:\test\
5

Use cases for these methods typically come up when we're trying to rename or copy files that have paths we don't necessarily know in advance. For example, we can be creating a function that accepts a path as an argument:

1#include <filesystem>
2#include <iostream>
3namespace fs = std::filesystem;
4
5void CreateBackup(const fs::path& Path) {
6  fs::path Backup{Path};
7  Backup.replace_extension("backup");
8  fs::copy_file(Path, Backup);
9}
10
11int main() {
12  CreateBackup(R"(c:\test\hello.txt)");
13}
14

Appending to a path

The path type also overrides the /= operator, which allows us to create paths to subdirectories or files, by automatically appending separators that are appropriate to the operating system.

1#include <filesystem>
2#include <iostream>
3
4int main() {
5  namespace fs = std::filesystem;
6
7  fs::path File{R"(c:\)"};
8  std::cout << File.string() << '\n';
9
10  File /= "test";
11  std::cout << File.string() << '\n';
12
13  File /= "hello.txt";
14  std::cout << File.string() << '\n';
15}
16

1c:\
2c:\test
3c:\test\hello.txt
4

These methods return a reference to the original object, allowing them to be chained:

1#include <filesystem>
2#include <iostream>
3
4int main() {
5  namespace fs = std::filesystem;
6
7  fs::path File{R"(c:\test\hello.txt)"};
8  std::cout << File.string() << '\n';
9
10  File.remove_filename() /= "subdirectory";
11  std::cout << File.string();
12}
13

1c:\test\hello.txt
2c:\test\subdirectory
3

Relative Paths

All the paths we’ve shown so far have been absolute paths, but we can also use relative paths.

We can check if a path is relative or absolute using the is_relative and is_absolute methods.

1#include <filesystem>
2#include <iostream>
3
4int main() {
5  namespace fs = std::filesystem;
6
7  fs::path A{R"(c:\test\hello.txt)"};
8  if (A.is_absolute()) {
9    std::cout << "A is Absolute";
10  }
11
12  fs::path B{R"(hello.txt)"};
13  if (B.is_relative()) {
14    std::cout << "B is Relative";
15  }
16}
17

1A is Absolute
2B is Relative
3

Relative paths are relative to some other directory, sometimes called the “current path” or “current working directory”

We can see the current working directory using the current_path method. Its default value depends on our settings, but we can pass a new path to that function, to set what our working directory should be.

1#include <filesystem>
2#include <iostream>
3
4int main() {
5  namespace fs = std::filesystem;
6  fs::directory_entry Entry{R"(hello.txt)"};
7
8  std::cout
9      << "The default working directory is:\n"
10      << fs::current_path().string();
11
12  if (!Entry.exists()) {
13    std::cout << "\nThe file was not found\n\n";
14  }
15
16  fs::current_path(R"(c:\test)");
17
18  std::cout << "The current working directory "
19               "was changed to:\n"
20            << fs::current_path().string();
21
22  if (Entry.exists()) {
23    std::cout << "\nThe file was found!";
24  }
25}
26

1The default working directory is:
2C:\Users\ryanm\repos\cpp-tuts
3The file was not found
4
5The current working directory was changed to:
6c:\test
7The file was found!
8

Directory Iteration using `directory_iterator`

We can navigate through a directory using a directory_iterator pair.

By passing a path to this type, we can define the directory we want to iterate through. This will act as our starting point.

The default constructor for directory_iterator returns an end iterator. We can increment our starting iterator and, once it becomes equal to the default-constructed iterator, we know we have navigated through the entire directory.

1#include <filesystem>
2#include <iostream>
3
4int main() {
5  namespace fs = std::filesystem;
6
7  fs::directory_iterator Start{R"(c:\test)"};
8  fs::directory_iterator End{};
9
10  for (auto Iter{Start}; Iter != End; ++Iter) {
11    std::cout << Iter->path().string();
12    if (Iter->is_directory()) {
13      std::cout << " (Directory)";
14    } else if (Iter->is_regular_file()) {
15      std::cout << " (" << Iter->file_size()
16                << " Bytes)";
17    }
18    std::cout << '\n';
19  }
20}
21

1c:\test\hello.txt (24 Bytes)
2c:\test\subdirectory (Directory)
3c:\test\world.txt (62 Bytes)
4

By default, the directory_iterator only iterates through the first level of entries within our directory. If an entry is a subdirectory, we will not navigate into it.

We could build this logic ourselves, by implementing recursive behavior when is_directory returns true. However, the standard library has built this for us, in the form of the recursive_directory_iterator

Recursive Directory Iteration using `recursive_directory_iterator`

This iterator works in much the same way as the directory_iterator, except it will navigate into any subdirectories it finds along the way.

The following code is identical to the previous example. Only the highlighted lines have been changed to switch to a recursive iterator.

1#include <filesystem>
2#include <iostream>
3
4int main() {
5  namespace fs = std::filesystem;
6
7  fs::recursive_directory_iterator Start{
8      R"(c:\test)"};
9  fs::recursive_directory_iterator End{};
10
11  for (auto Iter{Start}; Iter != End; ++Iter) {
12    std::cout << Iter->path().string();
13    if (Iter->is_directory()) {
14      std::cout << " (Directory)";
15    } else if (Iter->is_regular_file()) {
16      std::cout << " (" << Iter->file_size()
17                << " Bytes)";
18    }
19    std::cout << '\n';
20  }
21}
22

We now navigate into subdirectories:

1c:\test\hello.txt (24 Bytes)
2c:\test\subdirectory (Directory)
3c:\test\subdirectory\deep.txt (10 Bytes)
4c:\test\world.txt (62 Bytes)
5

The recursive iterator has an additional method, called depth(). This will return the depth of the recursion, ie, how deeply nested the current directory entry is, relative to our starting point:

1#include <filesystem>
2#include <iostream>
3
4int main() {
5  namespace fs = std::filesystem;
6  using std::cout, std::setw;
7
8  fs::recursive_directory_iterator Start{
9      R"(c:\test)"};
10  fs::recursive_directory_iterator End{};
11
12  for (auto Iter{Start}; Iter != End; ++Iter) {
13    std::cout << "Depth " << Iter.depth()
14              << " - " << Iter->path().string()
15              << '\n';
16  }
17}
18

1Depth 0 - c:\test\hello.txt
2Depth 0 - c:\test\subdirectory
3Depth 1 - c:\test\subdirectory\deep.txt
4Depth 0 - c:\test\world.txt
5

Up next, we’ll start working with file streams. These are the mean way we create, read, and update files within our file systems.

Was this lesson useful?

Ryan McCombe

Posted 6 months ago

This lesson is part of the course:

Professional C++

Comprehensive course covering advanced concepts, and how to use them on large-scale projects.

Whirlwind Tour of C++ Basics

Memory Management

Templates

Arrays and Linked Lists

Standard Library Data Structures

Working with Functions

Iterators and Algorithms

Standard Library Algorithms

Exceptions and Error Handling

Objects, Classes and Modules

Strings and Streams

Files and Serialization

101. Working with the File System in C++

A detailed introduction to using the filesystem in C++. Create, delete, move, and navigate through directories and files using the std::filesystem library.

This lesson is part of the course:

Professional C++

Comprehensive course covering advanced concepts, and how to use them on large-scale projects.

Free, unlimited access!

This course includes:

106 Lessons
550+ Code Samples
96% Positive Reviews
Regularly Updated
Help and FAQ

Next Lesson

C++ File Streams

A detailed guide to reading and writing files in C++ using the standard library’s fstream objects.

Contact|Privacy Policy|Terms of Use

Working with the File System in C++

Professional C++

Ryan McCombe

Directory Entry

“Regular” Files?

Creating a Directory

Deeply Creating a Directory

File System Exceptions and Errors

Getting File Size with file_size()

Getting the last modified time with last_write_time()

Copying Files with copy_file

Copying a Directory with copy

Removing a File or Directory using remove()

Removing a directory and all contents using remove_all()

Moving or Renaming Files and Directories with rename()

Getting Disk Space using space()

std::filesystem::path

path methods

Working with path file names

Appending to a path

Relative Paths

Directory Iteration using directory_iterator

Recursive Directory Iteration using recursive_directory_iterator

Was this lesson useful?

Ryan McCombe

Professional C++

Whirlwind Tour of C++ Basics

Memory Management

Templates

Arrays and Linked Lists

Standard Library Data Structures

Working with Functions

Iterators and Algorithms

Standard Library Algorithms

Exceptions and Error Handling

Objects, Classes and Modules

Strings and Streams

Files and Serialization

101.

Working with the File System in C++

Professional C++

This course includes:

C++ File Streams

Getting File Size with `file_size()`

Getting the last modified time with `last_write_time()`

Copying Files with `copy_file`

Copying a Directory with `copy`

Removing a File or Directory using `remove()`

Removing a directory and all contents using `remove_all()`

Moving or Renaming Files and Directories with `rename()`

Getting Disk Space using `space()`

`std::filesystem::path`

`path` methods

Working with `path` file names

Directory Iteration using `directory_iterator`

Recursive Directory Iteration using `recursive_directory_iterator`