`<filesystem>` functions

These free functions in the C++17 <filesystem> header perform modifying and query operations on paths, files, symlinks, directories, and volumes. For more information and code examples, see File System Navigation (C++).

Note

This article documents the C++17 std::filesystem functions. For the historical prestandard functions that MSVC provided in <experimental/filesystem>, see <experimental/filesystem> functions.

Requirements

Header: <filesystem>

Namespace: std::filesystem

`absolute`

path absolute(const path& pval);
path absolute(const path& pval, error_code& ec);

The functions compose an absolute path that refers to the same file system location as pval, according to operating-system semantics. The overload that takes ec returns path() if an error occurs.

`begin`

directory_iterator begin(directory_iterator iter) noexcept;
recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;

Both functions return iter. Together with end, they enable range-based for loops over a directory_iterator or recursive_directory_iterator.

`canonical`

path canonical(const path& pval);
path canonical(const path& pval, error_code& ec);

The functions convert pval, which must exist, to an absolute path that refers to the same file system object and has no symbolic-link, dot, or dot-dot elements. The overload that takes ec returns path() if an error occurs.

`copy`

void copy(const path& from, const path& to);
void copy(const path& from, const path& to, error_code& ec) noexcept;
void copy(const path& from, const path& to, copy_options opts);
void copy(const path& from, const path& to, copy_options opts, error_code& ec) noexcept;

The functions all possibly copy or link one or more files at from to to under control of opts, which is taken as copy_options::none for the overloads with no opts parameter. opts shall contain at most one of:

skip_existing, overwrite_existing, or update_existing
copy_symlinks or skip_symlinks
directories_only, create_symlinks, or create_hard_links

The functions first determine the file_status values f for from and t for to. They use symlink_status when opts contains copy_options::create_symlinks, copy_options::skip_symlinks, or copy_options::copy_symlinks, as required for the source or destination. Otherwise, they use status.

If !exists(f) || equivalent(f, t) || is_other(f) || is_other(t) || is_directory(f)&& is_regular_file(t), they then report an error (and do nothing else).

Otherwise, if is_symlink(f) then:

If options & copy_options::skip_symlinks, then do nothing.
Otherwise, if !exists(t) && options & copy_options::copy_symlinks, then copy_symlink(from, to).
Otherwise, report an error.

Otherwise, if is_regular_file(f), then:

If opts & copy_options::directories_only, then do nothing.
Otherwise, if opts & copy_options::create_symlinks, then create_symlink(from, to).
Otherwise, if opts & copy_options::create_hard_links, then create_hard_link(from, to).
Otherwise, if is_directory(t), then copy_file(from, to / from.filename(), opts).
Otherwise, copy_file(from, to, opts).

Otherwise, if is_directory(f) && (opts & copy_options::recursive || !opts), then:

if (!exists(t))
{  // copy directory contents recursively
    create_directory(to, from, ec);

    for (directory_iterator next(from), end; ec == error_code() && next != end; ++next)
    {
        copy(next->path(), to / next->path().filename(), opts, ec);
    }
}

Otherwise, do nothing.

`copy_file`

bool copy_file(const path& from, const path& to);
bool copy_file(const path& from, const path& to, error_code& ec) noexcept;
bool copy_file(const path& from, const path& to, copy_options opts);
bool copy_file(const path& from, const path& to, copy_options opts, error_code& ec) noexcept;

The functions all possibly copy the file at from to to under control of opts, which is taken as copy_options::none for the overloads with no opts parameter. opts shall contain at most one of skip_existing, overwrite_existing, or update_existing.

If exists(to) && !(opts & (copy_options::skip_existing | copy_options::overwrite_existing | copy_options::update_existing)), then report as an error that the file already exists.

Otherwise, if !exists(to) || opts & copy_options::overwrite_existing || opts & copy_options::update_existing&& last_write_time(to) < last_write_time(from) || !(opts & (copy_options::skip_existing | copy_options::overwrite_existing | copy_options::update_existing)), then attempt to copy the contents and attributes of the file from to the file to. Report as an error if the copy attempt fails.

The functions return true if the copy is attempted and succeeds, otherwise false.

`copy_symlink`

void copy_symlink(const path& from, const path& to);
void copy_symlink(const path& from, const path& to, error_code& ec) noexcept;

If is_directory(from), the function calls create_directory_symlink(from, to). Otherwise, it calls create_symlink(from, to).

`create_directories`

bool create_directories(const path& pval);
bool create_directories(const path& pval, error_code& ec) noexcept;

For a pathname such as a\/b\/c, the function creates directories a and a\/b as needed so that it can create the directory a\/b\/c as needed. It returns true only if it actually creates the directory pval.

`create_directory`

bool create_directory(const path& pval);

bool create_directory(const path& pval, error_code& ec) noexcept;
bool create_directory(const path& pval, const path& attr);
bool create_directory(const path& pval, const path& attr, error_code& ec) noexcept;

The function creates the directory pval as needed. It returns true only if it actually creates the directory pval, in which case it copies permissions from the existing file attr, or uses perms::all for the overloads with no attr parameter.

`create_directory_symlink`

void create_directory_symlink(const path& to, const path& link);
void create_directory_symlink(const path& to, const path& link, error_code& ec) noexcept;

The function creates link as a symlink to the directory to.

`create_hard_link`

void create_hard_link(const path& to,  const path& link);
void create_hard_link(const path& to, const path& link, error_code& ec) noexcept;

The function creates link as a hard link to the directory or file to.

`create_symlink`

void create_symlink(const path& to, const path& link);

void create_symlink(const path& to, const path& link, error_code& ec) noexcept;

The function creates link as a symlink to the file to.

`current_path`

path current_path();
path current_path(error_code& ec);
void current_path(const path& pval);
void current_path(const path& pval, error_code& ec) noexcept;

The functions with no parameter pval return the pathname for the current directory. The remaining functions set the current directory to pval.

`end`

directory_iterator end(const directory_iterator&) noexcept;
recursive_directory_iterator end(const recursive_directory_iterator&) noexcept;

The first function returns directory_iterator() and the second function returns recursive_directory_iterator().

`equivalent`

bool equivalent(const path& left, const path& right);
bool equivalent(const path& left, const path& right, error_code& ec) noexcept;

The functions return true only if left and right choose the same filesystem entity.

`exists`

bool exists(file_status stat) noexcept;
bool exists(const path& pval);
bool exists(const path& pval, error_code& ec) noexcept;

The first function returns status_known(stat) && stat.type() != file_type::not_found. The second and third functions return exists(status(pval)).

`file_size`

uintmax_t file_size(const path& pval);
uintmax_t file_size(const path& pval, error_code& ec) noexcept;

The functions return the size in bytes of the file chosen by pval, if exists(pval) && is_regular_file(pval) and the file size can be determined. Otherwise they report an error and return uintmax_t(-1).

`hard_link_count`

uintmax_t hard_link_count(const path& pval);
uintmax_t hard_link_count(const path& pval, error_code& ec) noexcept;

The function returns the number of hard links for pval, or -1 if an error occurs.

`hash_value`

size_t hash_value(const path& pval) noexcept;

The function returns a hash value for pval.native().

`is_block_file`

bool is_block_file(file_status stat) noexcept;
bool is_block_file(const path& pval);
bool is_block_file(const path& pval, error_code& ec) noexcept;

The first function returns stat.type() == file_type::block. The remaining functions return is_block_file(status(pval)).

`is_character_file`

bool is_character_file(file_status stat) noexcept;
bool is_character_file(const path& pval);
bool is_character_file(const path& pval, error_code& ec) noexcept;

The first function returns stat.type() == file_type::character. The remaining functions return is_character_file(status(pval)).

`is_directory`

bool is_directory(file_status stat) noexcept;
bool is_directory(const path& pval);
bool is_directory(const path& pval, error_code& ec) noexcept;

The first function returns stat.type() == file_type::directory. The remaining functions return is_directory(status(pval)).

`is_empty`

bool is_empty(const path& pval);
bool is_empty(const path& pval, error_code& ec) noexcept;

If is_directory(pval), then the function returns directory_iterator(pval) == directory_iterator(); otherwise it returns file_size(pval) == 0.

`is_fifo`

bool is_fifo(file_status stat) noexcept;
bool is_fifo(const path& pval);
bool is_fifo(const path& pval, error_code& ec) noexcept;

The first function returns stat.type() == file_type::fifo. The remaining functions return is_fifo(status(pval)).

`is_other`

bool is_other(file_status stat) noexcept;
bool is_other(const path& pval);
bool is_other(const path& pval, error_code& ec) noexcept;

The first function returns exists(stat) && !is_regular_file(stat) && !is_directory(stat) && !is_symlink(stat). The remaining functions return is_other(status(pval)).

`is_regular_file`

bool is_regular_file(file_status stat) noexcept;
bool is_regular_file(const path& pval);
bool is_regular_file(const path& pval, error_code& ec) noexcept;

The first function returns stat.type() == file_type::regular. The remaining functions return is_regular_file(status(pval)).

`is_socket`

bool is_socket(file_status stat) noexcept;
bool is_socket(const path& pval);
bool is_socket(const path& pval, error_code& ec) noexcept;

The first function returns stat.type() == file_type::socket. The remaining functions return is_socket(status(pval)).

`is_symlink`

bool is_symlink(file_status stat) noexcept;
bool is_symlink(const path& pval);
bool is_symlink(const path& pval, error_code& ec) noexcept;

The first function returns stat.type() == file_type::symlink. The remaining functions return is_symlink(status(pval)).

`last_write_time`

file_time_type last_write_time(const path& pval);
file_time_type last_write_time(const path& pval, error_code& ec) noexcept;
void last_write_time(const path& pval, file_time_type new_time);
void last_write_time(const path& pval, file_time_type new_time, error_code& ec) noexcept;

The first two functions return the time of last data modification for pval, or file_time_type(-1) if an error occurs. The last two functions set the time of last data modification for pval to new_time.

`permissions`

void permissions(const path& pval, perms mask, perm_options opts = perm_options::replace);
void permissions(const path& pval, perms mask, error_code& ec) noexcept;
void permissions(const path& pval, perms mask, perm_options opts, error_code& ec);

The functions set the permissions for the pathname chosen by pval to mask & perms::mask under control of opts. opts must contain exactly one of perm_options::replace, perm_options::add, or perm_options::remove, and optionally perm_options::nofollow. The overloads with no opts parameter behave as if opts is perm_options::replace.

If opts & perm_options::add, the functions set the permissions to status(pval).permissions() | (mask & perms::mask). Otherwise, if opts & perm_options::remove, the functions set the permissions to status(pval).permissions() & ~(mask & perms::mask). Otherwise, the functions set the permissions to mask & perms::mask. If opts & perm_options::nofollow and pval names a symbolic link, the functions change the permissions of the symbolic link itself rather than the file it resolves to.

`proximate`

path proximate(const path& p, error_code& ec);
path proximate(const path& p, const path& base = current_path());
path proximate(const path& p, const path& base, error_code& ec);

The first overload returns proximate(p, current_path(), ec). The other overloads return the result of applying lexically_proximate to the weakly canonical forms of p and base. The overload that takes ec returns path() if an error occurs.

`read_symlink`

path read_symlink(const path& pval);
path read_symlink(const path& pval, error_code& ec);

The functions report an error and return path() if !is_symlink(pval). Otherwise, the functions return an object of type path containing the symbolic link.

`relative`

path relative(const path& p, error_code& ec);
path relative(const path& p, const path& base = current_path());
path relative(const path& p, const path& base, error_code& ec);

The first overload returns relative(p, current_path(), ec). The other overloads return the result of applying lexically_relative to the weakly canonical forms of p and base. The overload that takes ec returns path() if an error occurs.

`remove`

bool remove(const path& pval);
bool remove(const path& pval, error_code& ec) noexcept;

The functions return true only if exists(symlink_status(pval)) and the file is successfully removed. A symlink is itself removed, not the file it chooses.

`remove_all`

uintmax_t remove_all(const path& pval);
uintmax_t remove_all(const path& pval, error_code& ec) noexcept;

If pval is a directory, the functions recursively remove all directory entries, then the entry itself. Otherwise, the functions call remove. They return a count of all elements successfully removed.

`rename`

void rename(const path& from, const path& to);
void rename(const path& from, const path& to, error_code& ec) noexcept;

The functions rename from to to. A symlink is itself renamed, not the file it chooses.

`resize_file`

void resize_file(const path& pval, uintmax_t size);
void resize_file(const path& pval, uintmax_t size, error_code& ec) noexcept;

The functions alter the size of a file such that file_size(pval) == size.

`space`

space_info space(const path& pval);
space_info space(const path& pval, error_code& ec) noexcept;

The function returns information about the volume chosen by pval, in a structure of type space_info. The structure contains uintmax_t(-1) for any value that can't be determined.

`status`

file_status status(const path& pval);
file_status status(const path& pval, error_code& ec) noexcept;

The functions return the pathname status, the file type, and permissions, associated with pval. A symlink is itself not tested, but the file it chooses.

`status_known`

bool status_known(file_status stat) noexcept;

The function returns stat.type() != file_type::none

`swap`

void swap(path& left, path& right) noexcept;

The function exchanges the contents of left and right.

`symlink_status`

file_status symlink_status(const path& pval);
file_status symlink_status(const path& pval, error_code& ec) noexcept;

The functions return the pathname symlink status, the file type, and permissions, associated with pval. The functions behave the same as status(pval) except that a symlink is itself tested, not the file it chooses.

`temp_directory_path`

path temp_directory_path();
path temp_directory_path(error_code& ec);

The functions return a pathname for a directory suitable for containing temporary files.

`u8path`

template <class Source>
path u8path(const Source& source);

template <class InIt>
path u8path(InIt first, InIt last);

The first function behaves the same as path(source) and the second function behaves the same as path(first, last) except that the chosen source in each case is taken as a sequence of char elements encoded as UTF-8, whatever the filesystem.

`weakly_canonical`

path weakly_canonical(const path& p);
path weakly_canonical(const path& p, error_code& ec);

These functions return a path in canonical form, like the canonical function, but the path doesn't need to exist.

Feedback

Was this page helpful?

Last updated on 2026-08-31

<filesystem> functions

Requirements

absolute

begin

canonical

copy

copy_file

copy_symlink

create_directories

create_directory

create_directory_symlink

create_hard_link

create_symlink

current_path

end

equivalent

exists

file_size

hard_link_count

hash_value

is_block_file

is_character_file

is_directory

is_empty

is_fifo

is_other

is_regular_file

is_socket

is_symlink

last_write_time

permissions

proximate

read_symlink

relative

remove

remove_all

rename

resize_file

space

status

status_known

swap

symlink_status

temp_directory_path

u8path

weakly_canonical

See also