C++ Reference ยท Strings and I/O
C++ std::filesystem library
Reference for C++17 std::filesystem: the path class, splitting and joining paths, querying files, error handling with exceptions or error_code, and portability.
<filesystem> (C++17) is the standard library for working with files and directories as objects of the file system rather than streams of bytes. It has two halves. The class std::filesystem::path is a value type that represents a path and takes it apart or puts it together without touching the disk. A set of free functions (exists, file_size, create_directories, remove, copy and more) then ask the operating system to look at or change real files.
Everything lives in namespace std::filesystem, which is almost always shortened with namespace fs = std::filesystem;. This page covers paths and queries. Changing the file system (copying, renaming, deleting, listing directories) is on Filesystem operations.
#include <filesystem> namespace fs = std::filesystem; fs::path p = "reports/2025/summary.txt"; std::cout << p.filename() << " " << p.extension() << "\n";
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 std::cin or std::getline), 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 std::cin or std::getline), it gets the next line from this box.
Syntax
namespace fs = std::filesystem; class fs::path; // value type, no disk access bool fs::exists(const path& p); bool fs::exists(const path& p, std::error_code& ec) noexcept; uintmax_t fs::file_size(const path& p); path fs::temp_directory_path(); path fs::current_path(); path fs::absolute(const path& p); path fs::canonical(const path& p); // must exist; resolves . .. and links
| Path member | Description |
|---|---|
filename(), stem(), extension() |
Last component, last component without its extension, and the extension including the dot. |
parent_path(), root_path() |
Everything before the last component, and the root (/ on POSIX, C:\ on Windows). |
has_filename(), is_absolute(), is_relative() |
Simple predicates on the path text. |
operator/, /= |
Join with a directory separator. An absolute right operand replaces the left one. |
operator+=, concat |
Append text with no separator. |
replace_extension(), replace_filename(), remove_filename() |
Modify in place. |
lexically_normal(), lexically_relative(base) |
Text-only clean-up and relative-path computation. |
string(), generic_string(), u8string() |
Convert to a string in the native, portable (/) or UTF-8 form. |
Returns / errors: each query function has two overloads. The plain one throws std::filesystem::filesystem_error (derived from std::system_error) on failure. The overload with a trailing std::error_code& never throws; it sets ec and returns a failure value (for file_size, the maximum uintmax_t, as the run above shows).
Usage notes
- A
pathis just text. Creating one does not check that the file exists, and the name need not be valid.exists,statusand similar functions are what consult the disk. - Native versus generic format. On Windows the native separator is
\andpath::value_typeiswchar_t; on POSIX it is/andchar. Usegeneric_string()when you need the same text on every platform, andu8string()for UTF-8. - Streaming a path with
<<prints it quoted ("a/b.txt"). Call.string()when you want the bare text. stem()andextension()split at the last dot of the filename only:archive.tar.gzhas stemarchive.tarand extension.gz. A name like.bashrchas no extension./replaces on absolute operands.path("a") / "/b"is/b, nota/b. This surprises people who join user input to a base directory; validate user-supplied names first.- Race conditions are inherent. Between
exists(p)and the next call another process can change the file. Prefer to just attempt the operation and handle the error. - Time-of-check issues and symlinks.
canonicalandweakly_canonicalresolve links;lexically_normaldoes not and can be wrong when..follows a symlink. - Portability. The library needs C++17. On older GCC releases (before 9) you had to link
-lstdc++fs. Filesystem access can be unavailable or restricted in sandboxes, containers and some embedded targets.