filesystem-functions.md

title	description	ms.date	f1_keywords	helpviewer_keywords
<filesystem> functions	Learn more about: <filesystem> functions	03/27/2019	FILESYSTEM/std::experimental::filesystem::absolute FILESYSTEM/std::experimental::filesystem::canonical FILESYSTEM/std::experimental::filesystem::copy FILESYSTEM/std::experimental::filesystem::copy_file FILESYSTEM/std::experimental::filesystem::copy_symlink FILESYSTEM/std::experimental::filesystem::create_directories FILESYSTEM/std::experimental::filesystem::create_directory FILESYSTEM/std::experimental::filesystem::create_directory_symlink FILESYSTEM/std::experimental::filesystem::create_hard_link FILESYSTEM/std::experimental::filesystem::create_symlink FILESYSTEM/std::experimental::filesystem::current_path FILESYSTEM/std::experimental::filesystem::equivalent FILESYSTEM/std::experimental::filesystem::exists FILESYSTEM/std::experimental::filesystem::file_size FILESYSTEM/std::experimental::filesystem::hard_link_count FILESYSTEM/std::experimental::filesystem::hash_value FILESYSTEM/std::experimental::filesystem::is_block_file FILESYSTEM/std::experimental::filesystem::is_character_file FILESYSTEM/std::experimental::filesystem::is_directory FILESYSTEM/std::experimental::filesystem::is_empty FILESYSTEM/std::experimental::filesystem::is_fifo FILESYSTEM/std::experimental::filesystem::is_other FILESYSTEM/std::experimental::filesystem::is_regular_file FILESYSTEM/std::experimental::filesystem::is_socket FILESYSTEM/std::experimental::filesystem::is_symlink FILESYSTEM/std::experimental::filesystem::last_write_time FILESYSTEM/std::experimental::filesystem::permissions FILESYSTEM/std::experimental::filesystem::read_symlink FILESYSTEM/std::experimental::filesystem::remove FILESYSTEM/std::experimental::filesystem::remove_all FILESYSTEM/std::experimental::filesystem::rename FILESYSTEM/std::experimental::filesystem::resize_file FILESYSTEM/std::experimental::filesystem::space FILESYSTEM/std::experimental::filesystem::status FILESYSTEM/std::experimental::filesystem::status_known FILESYSTEM/std::experimental::filesystem::swap FILESYSTEM/std::experimental::filesystem::symlink_status FILESYSTEM/std::experimental::filesystem::system_complete FILESYSTEM/std::experimental::filesystem::temp_directory_path FILESYSTEM/std::experimental::filesystem::u8path	std::experimental::filesystem::absolute std::experimental::filesystem::canonical std::experimental::filesystem::copy std::experimental::filesystem::copy_file std::experimental::filesystem::copy_symlink std::experimental::filesystem::create_directories std::experimental::filesystem::create_directory std::experimental::filesystem::create_directory_symlink std::experimental::filesystem::create_hard_link std::experimental::filesystem::create_symlink std::experimental::filesystem::current_path std::experimental::filesystem::equivalent std::experimental::filesystem::exists std::experimental::filesystem::file_size std::experimental::filesystem::hard_link_count std::experimental::filesystem::hash_value std::experimental::filesystem::is_block_file std::experimental::filesystem::is_character_file std::experimental::filesystem::is_directory std::experimental::filesystem::is_empty std::experimental::filesystem::is_fifo std::experimental::filesystem::is_other std::experimental::filesystem::is_regular_file std::experimental::filesystem::is_socket std::experimental::filesystem::is_symlink std::experimental::filesystem::last_write_time std::experimental::filesystem::permissions std::experimental::filesystem::read_symlink std::experimental::filesystem::remove std::experimental::filesystem::remove_all std::experimental::filesystem::rename std::experimental::filesystem::resize_file std::experimental::filesystem::space std::experimental::filesystem::status std::experimental::filesystem::status_known std::experimental::filesystem::swap std::experimental::filesystem::symlink_status std::experimental::filesystem::system_complete std::experimental::filesystem::temp_directory_path std::experimental::filesystem::u8path

<filesystem> functions

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

absolute

path absolute(const path& pval, const path& base = current_path());

The function returns the absolute pathname corresponding to pval relative to the pathname base:

1. If pval.has_root_name() && pval.has_root_directory() the function returns pval.

2. If pval.has_root_name() && !pval.has_root_directory() the function returns pval.root_name() / absolute(base).root_directory() / absolute(base).relative_path() / pval.relative_path().

3. If !pval.has_root_name() && pval.has_root_directory() the function returns absolute(base).root_name() / pval.

4. If !pval.has_root_name() && !pval.has_root_directory() the function returns absolute(base) / pval.

begin

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

Both functions return iter.

canonical

path canonical(const path& pval, const path& base = current_path()); path canonical(const path& pval, error_code& ec); path canonical(const path& pval, const path& base, error_code& ec);

The functions all form an absolute pathname pabs = absolute(pval, base) (or pabs = absolute(pval) for the overload with no base parameter), then reduce it to a canonical form in the following sequence of steps:

1. Every path component X for which is_symlink(X) is true is replaced by read_symlink(X).

2. Every path component . (dot is the current directory established by previous path components) is removed.

3. Every pair of path components X/.. (dot-dot is the parent directory established by previous path components) is removed.

The function then returns pabs.

copy

voidcopy(const path& from, const path& to); voidcopy(const path& from, const path& to, error_code& ec) noexcept; voidcopy(const path& from, const path& to, copy_options opts); voidcopy(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:

• if opts & (copy_options::create_symlinks | copy_options::skip_symlinks), by calling symlink_status

• otherwise, by calling status

• Otherwise report an error.

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, opts).

• 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(to, from).

• Otherwise, if opts & copy_options::create_hard_links, then create_hard_link(to, from).

• Otherwise, if is_directory(f), 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 recursivelycreate_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

boolcopy_file(const path& from, const path& to); boolcopy_file(const path& from, const path& to, error_code& ec) noexcept; boolcopy_file(const path& from, const path& to, copy_options opts); boolcopy_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

voidcopy_symlink(const path& from, const path& to); voidcopy_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

boolcreate_directories(const path& pval); boolcreate_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

boolcreate_directory(const path& pval); boolcreate_directory(const path& pval, error_code& ec) noexcept; boolcreate_directory(const path& pval, const path& attr); boolcreate_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

voidcreate_directory_symlink(const path& to, const path& link); voidcreate_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

voidcreate_hard_link(const path& to, const path& link); voidcreate_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

voidcreate_symlink(const path& to, const path& link); voidcreate_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); voidcurrent_path(const path& pval); voidcurrent_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& iter) noexcept; recursive_directory_iterator& end(const recursive_directory_iterator& iter) noexcept;

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

equivalent

boolequivalent(const path& left, const path& right); boolequivalent(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

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

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

file_size

uintmax_tfile_size(const path& pval); uintmax_tfile_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_thard_link_count(const path& pval); uintmax_thard_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_thash_value(const path& pval) noexcept;

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

is_block_file

boolis_block_file(file_status stat) noexcept; boolis_block_file(const path& pval); boolis_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

boolis_character_file(file_status stat) noexcept; boolis_character_file(const path& pval); boolis_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

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

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

is_empty

boolis_empty(file_status stat) noexcept; boolis_empty(const path& pval); boolis_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

boolis_fifo(file_status stat) noexcept; boolis_fifo(const path& pval); boolis_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

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

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

is_regular_file

boolis_regular_file(file_status stat) noexcept; boolis_regular_file(const path& pval); boolis_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

boolis_socket(file_status stat) noexcept; boolis_socket(const path& pval); boolis_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

boolis_symlink(file_status stat) noexcept; boolis_symlink(const path& pval); boolis_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; voidlast_write_time(const path& pval, file_time_type new_time); voidlast_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

voidpermissions(const path& pval, perms mask); voidpermissions(const path& pval, perms mask, error_code& ec) noexcept;

The functions set the permissions for the pathname chosen by pval to mask & perms::mask under control of perms & (perms::add_perms | perms::remove_perms). mask shall contain at most one of perms::add_perms and perms::remove_perms.

If mask & perms::add_perms, the functions set the permissions to status(pval).permissions() | mask & perms::mask. Otherwise, if mask & perms::remove_perms, the functions set the permissions to status(pval).permissions() & ~(mask & perms::mask). Otherwise, the functions set the permissions to mask & perms::mask.

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);

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);

remove

boolremove(const path& pval); boolremove(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_tremove_all(const path& pval); uintmax_tremove_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

voidrename(const path& from, const path& to); voidrename(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

voidresize(const path& pval, uintmax_t size); voidresize(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

boolstatus_known(file_status stat) noexcept;

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

swap

voidswap(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.

system_complete

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

The functions return an absolute pathname that takes into account, as necessary, the current directory associated with its root name. (For POSIX, the functions return absolute(pval)).

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 <classSource> path u8path(const Source& source); template <classInIt> 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);