Filesystem

Curated hub for paths, traversal, file status, operations, permissions, space, timestamps, and filesystem error handling.

The filesystem library combines several different jobs: representing paths, traversing directory trees, querying file status, mutating the filesystem, handling permissions and timestamps, and reporting failures. This page is the task-first entry point for choosing the right filesystem area before you drop into individual functions or member APIs.

Filesystem is a C++17 library, but early toolchains sometimes required extra linker flags. If you are working with older compilers or historical build setups, check the implementation support note on the canonical pages before assuming the library is available by default.

# Start Here

Build and normalize paths

Use std::filesystem::path when the problem is pathname composition, decomposition, normalization, or conversion to and from native/generic string forms.

path · absolute · canonical · relative

Traverse directories

Start here when you need to enumerate entries in a directory or recursively walk a tree.

directory_iterator · recursive_directory_iterator · directory_entry

Inspect file status

Use the status/query route when you need to know whether something exists, what kind of file it is, or which permissions/status bits it has.

status · exists · is_regular_file · file_status

Create, copy, move, and remove

Choose the mutating operations route when you are changing the filesystem rather than just describing or traversing it.

create_directory · copy · rename · remove

Permissions, timestamps, and space

Use this route for metadata and resource questions such as permissions, free space, current path, temp directories, and last-write timestamps.

permissions · space · last_write_time · current_path

Handle errors and legacy/TS paths

Start here when you need throwing-vs-`error_code` behavior, exception details, or the older experimental filesystem TS surface.

filesystem_error · error_code · filesystem TS

# Quick Map

If you need to...	Start with	Why
Represent or manipulate a path string structurally	path	`std::filesystem::path` is the core value type for joining, splitting, and converting paths.
Resolve paths against the environment or normalize them	absolute, canonical, relative	These are the main route when path meaning depends on current location, symlinks, or normalization rules.
Iterate through a directory tree	directory_iterator, recursive_directory_iterator	The iterator family is the traversal route rather than ad hoc OS-specific enumeration code.
Ask what a path points to or whether it exists	status, exists, is_regular_file	Status/query functions separate file-type inspection from mutating operations.
Create directories, copy files, move things, or delete them	create_directory, copy, rename, remove	These are the primary side-effecting operations in the library.
Inspect permissions, free space, or file modification times	permissions, space, last_write_time	This route is for metadata/resource questions rather than path structure or traversal.
Handle failures or bridge to older implementations	filesystem_error, experimental/filesystem	Use this route when exception/error-code behavior or TS compatibility is the main issue.

# Filesystem Families

Family	Representative entry points	Use it for
Path modeling	path, absolute, canonical, relative	Structural pathname manipulation, normalization, and conversion.
Traversal	directory_iterator, recursive_directory_iterator, directory_entry	Walking directory trees and reusing cached entry metadata while iterating.
Status and classification	status, exists, is_regular_file, file_status	Checking what a path refers to and what state/permissions it carries.
Mutating operations	create_directory, copy, rename, remove	Creating, moving, copying, and deleting filesystem objects.
Metadata and environment	permissions, space, last_write_time, current_path, temp_directory_path	Permissions, timestamps, free space, and environment-relative directory context.
Error handling and compatibility	filesystem_error, error_code, filesystem TS	Choosing between throwing/error-code overloads and interoperating with pre-standard surfaces.

# Path And Operation Model

Model	Choose it when	Primary destinations
Pure path value	You need to build, compare, or normalize a path without necessarily touching the filesystem.	path, absolute, relative
Path with cached entry metadata	You are iterating and want path-plus-status information packaged together.	directory_entry, directory_iterator
Status query	You need to ask what exists, what type it is, or which permissions/status bits apply.	status, exists, file_status
Mutation with side effects	You are creating, deleting, copying, moving, or changing filesystem state.	create_directory, copy, rename, remove
Metadata/resource inspection	You need permissions, timestamps, space accounting, or process-relative filesystem context.	permissions, space, last_write_time, current_path

# Standard Evolution

Standard	What changed navigation-wise
Filesystem TS	The experimental TS was the precursor route; older code and toolchains may still point to experimental/filesystem.
C++17	`std::filesystem` became the standard route for paths, traversal, status queries, and file operations.
Post-C++17 toolchains	The main practical change was implementation maturity: older compilers often needed extra linker flags, while modern ones generally ship the library as part of the default standard library experience.

# Boundary Lines

This hub covers	Use a different hub for
Path values, traversal, status queries, file operations, permissions, space, timestamps, and filesystem-specific errors.	I/O for stream/file-handle APIs, Strings for text/encoding abstractions, and Diagnostics for the broader exception/error-code model beyond filesystem-specific operations.
The standard C++ filesystem surface.	filesystem TS when you are working with older pre-standard code or documentation.