Skip to content
Tutorials Center
My learning

Topics

C++ Reference ยท Strings and I/O

C++ filesystem operations

Reference for std::filesystem operations: create_directories, copy, rename, remove and remove_all, resize_file, and iterating directories with directory_iterator.

Besides asking questions about paths, <filesystem> can change the file system: create directories, copy and rename files, delete them, resize them, and walk the contents of a directory. These are free functions in std::filesystem that take path arguments, plus two iterator classes, directory_iterator and recursive_directory_iterator, for listing.

Each function has a throwing form and an error_code form. Operations that can partially succeed (copying a tree, removing a directory with contents) report how far they got through their return value, so check it. Because the real file system is shared with other programs, assume that any step can fail.

C++
fs::create_directories("out/logs");
fs::copy_file("a.txt", "out/a.txt", fs::copy_options::overwrite_existing);
fs::remove_all("out");

Try it

C++ Create, copy, rename and remove

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.

C++ Listing a directory (sorted) and recursing

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.

Syntax

C++
bool fs::create_directory(const path& p);
bool fs::create_directories(const path& p);
void fs::copy(const path& from, const path& to, copy_options opts = copy_options::none);
bool fs::copy_file(const path& from, const path& to, copy_options opts = copy_options::none);
void fs::rename(const path& old_p, const path& new_p);
bool fs::remove(const path& p);                   // one file or an empty directory
uintmax_t fs::remove_all(const path& p);          // recursively
void fs::resize_file(const path& p, uintmax_t new_size);

class fs::directory_iterator;
class fs::recursive_directory_iterator;
Function Description and return value
create_directory(p) Creates one directory; the parent must exist. Returns true if it created it, false if it already existed.
create_directories(p) Creates all missing parents too. Same return convention.
copy_file(from, to, opts) Copies one regular file. By default fails if to exists; overwrite_existing, skip_existing or update_existing change that. Returns true if copied.
copy(from, to, opts) Copies files or directory trees (recursive), can create symlinks or hard links (create_symlinks, create_hard_links).
rename(old, new) Moves or renames. Replaces an existing file on POSIX; behavior for existing targets differs on Windows.
remove(p) Removes a file or an empty directory. Returns false if it did not exist. Throws if a directory is not empty.
remove_all(p) Removes p and everything below it. Returns the number of entries removed.
resize_file(p, n) Truncates, or extends with zero bytes.

Errors: throwing overloads throw std::filesystem::filesystem_error; the std::error_code& overloads set the code instead.

Usage notes

  • Iteration order is unspecified. directory_iterator returns entries in whatever order the OS reports them, and it never yields . or ... Sort the names if the order matters or you print results.
  • directory_entry caches information. e.is_directory() and e.file_size() often avoid an extra system call; calling fs::is_directory(e.path()) asks the OS again.
  • recursive_directory_iterator descends automatically. Call disable_recursion_pending() to skip a subtree and depth() for the current level. It does not follow directory symlinks unless you pass directory_options::follow_directory_symlink.
  • Do not modify while iterating in ways that add or remove entries of the directory being listed; whether the iterator sees them is unspecified.
  • remove versus remove_all. remove on a non-empty directory fails. remove_all is powerful and unforgiving: double-check the path before calling it.
  • Atomicity. rename within one file system is atomic on POSIX, which is why programs write a temporary file and rename it over the target. Across file systems it fails; copy then remove instead.
  • fs::copy on a file into a directory copies it into that directory under the same name; copy_file requires the full destination file name.
  • Permissions and links are handled by permissions, create_symlink, read_symlink and hard_link_count, which follow the same two-overload scheme.