<filesystem>

[added with C++14]

Host Operating Systems · Function parameter error_code ec · Template parameter Source

copy_options · directory_entry · directory_iterator · directory_options · filesystem_error · file_status · file_time_type · file_type · path · perms · recursive_directory_iterator · space_info

operator!= · operator== · operator< · operator<= · operator<< · operator> · operator>= · operator>> · operator/

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 · read_symlink · remove · remove_all · rename · resize_file · space · status · status_known · swap · symlink_status · system_complete · temp_directory_path · u8path

namespace std {
    namespace tr2 {
        namespace sys {
#define STD std::    // for ambiguous type references
#define PFX STD tr2::sys::

    // TYPES
enum class copy_options;
enum class directory_options;
enum class file_type;
enum class perms;

typedef chrono::time_point<unspecified-clock> file_time_type;

class directory_entry;
class directory_iterator;
class filesystem_error;
class file_status;
class path;
class space_info;
class recursive_directory_iterator;

    // OPERATORS
bool operator!=(const path& left, const path& right) noexcept;
bool operator==(const path& left, const path& right) noexcept;
bool operator<(const path& left, const path& right) noexcept;
bool operator<=(const path& left, const path& right) noexcept;
bool operator>(const path& left, const path& right) noexcept;
bool operator>=(const path& left, const path& right) noexcept;

path operator/(const path& left, const path& right);

template<class Elem, class Traits>
    basic_ostream<Elem, Traits>&
    operator<<(basic_ostream<Elem, Traits>& os, const path& pval);
template<class Elem, class Traits>
    basic_istream<Elem, Traits>&
    operator<<(basic_istream<Elem, Traits>& is, const path& pval);

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

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

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

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;

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;

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

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

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;

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

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

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

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;

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

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

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

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

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

size_t hash_value(const path& pval) noexcept;

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;

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;

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

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

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

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

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;

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

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

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;

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

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

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

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

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

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

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

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

bool status_known(file_status stat) noexcept;

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

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

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

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

template<class Source>
    path u8path(const Source& source);
template<class InIt>
    path u8path(InIt first, InIt last);
        }  // namespace sys
    }  // namespace tr2
}  // namespace std

Include the C++14 header <filesystem> to define several classes and functions useful for manipulating a coherent collection of named storage devices, files, and directories called a filesystem. It is based on the concept of a pathname, stored as an object of class path, which uniquely names every entity accessible within the filesystem.

Host Operating Systems

This header supports filesystems for one of two broad classes of host operating systems:

• Microsoft Windows
• Posix

While most functionality is common to both operating systems, this document identifies where differences occur. For example:

• Windows supports multiple root names, such as c: or \\network_name. So a filesystem consists of a forest of trees, each with its own root directory, such as c:\ or \\network_name\, and each with its own current directory, for completing a relative pathname (one that is not an absolute pathname).
• Posix supports a single tree, with no root name, the single root directory /, and a single current directory.

Another significant difference is the native representation of pathnames:

• Windows uses a nul-terminated sequence of wchar_t, encoded as UTF-16 (one or two elements for each character).
• Posix uses a nul-terminated sequence of char, encoded as UTF-8 (one or more elements for each character).

An object of class path stores the pathname in native form, but supports easy conversion between this stored form and several external forms:

• A nul-terminated sequence of char, encoded as favored by the operating system.
• A nul-terminated sequence of char, encoded as UTF-8.
• A nul-terminated sequence of wchar_t, encoded as favored by the operating system.
• A nul-terminated sequence of char16_t, encoded as UTF-16.
• A nul-terminated sequence of char32_t, encoded as UTF-32.

Interconversions between these representations are mediated, as needed, by the use of one or more codecvt facets. If a specific locale object is not designated, these facets are obtained from the global locale.

Another difference is the detail with which each operating system lets you specify file or directory access permissions:

• Windows records whether a file is read only or writable, an attribute that has no meaning for directories.
• Posix records whether a file can be read, written, or executed (scanned if a directory), by the owner, by the owner's group, or by everybody, plus a few other permissions.

Common to both systems is the structure imposed on a pathname once you get past the root name. For the pathname c:/abc/xyz/def.ext:

• The root name is c:.
• The root directory is /.
• The root path is c:/.
• The relative path is abc/xyz/def.ext.
• The parent path is c:/abc/xyz.
• The filename is def.ext.
• The stem is def.
• The extension is .ext.

A minor difference is the preferred separator, between the sequence of directories in a pathname. Both operating systems let you write a forward slash /, but in some contexts Windows prefers a backslash \.

Finally, an important feature of path objects is that you can use them wherever an argument called filename is required in the classes defined in the header <fstream>.

Function parameter error_code ec

In the descriptions that follow, you will find many sets of functions that include an overload with the trailing argument error_code& ec, usually labeled noexcept. These overloads unconditionally store a value in ec, which is not equal to error_code() if an error occurs. The companion version without this trailing argument reports an error by throwing an exception. Thus, the header <filesystem> supports two distinct styles of programming, both with adequate opportunities for error checking.

Template parameter Source

In the descriptions that follow, the template declaration:

template<class Source>
    return-type function(const Source& source, etc.);

is shorthand for any of:

template<class Elem,
    class _Traits,
    class Alloc>
    return-type function(const basic_string<Elem, Traits, Alloc>& str, etc.);

where the operand has the effective range [str.begin(), str.end()); or

template<class InIt>
    return-type function(InIt first, etc.);

where InIt is an input iterator and the operand has the effective range beginning at *first and ending just before the first subsequent element that compares equal to iterator_traits<InIt>::value_type() (a nul-terminated character string designated by an iterator, in other words); or

template<Elem>
    return-type function(Elem *first, etc.);

where Elem is an encoded character type and the operand has the effective range beginning at *first and ending just before the first subsequent element that compares equal to Elem(0) (a nul-terminated character string designated by a pointer, in other words).

Usually accompanying the Source shorthand declaration is the more conventional:

template<class InIt>
    return-type function(InIt first, InIt last, etc.);

where InIt is an input iterator and the operand has the effective range [first, last) (an iterator range, in other words).

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:

• If pval.has_root_name() && pval.has_root_directory() the function returns pval.
• 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().
• If !pval.has_root_name() && pval.has_root_directory() the function returns absolute(base).root_name() / pval.
• 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:

• Every path component X for which is_symlink(X) is true is replaced by read_symlink(X).
• Every path component . (dot is the current directory established by previous path components) is removed.
• 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

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:

• if opts & (copy_options::create_symlinks | copy_options::skip_symlinks), by calling symlink_status
• otherwise, by calling 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, 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 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_options

enum class copy_options {
    none = 0, skip_existing = 01,
    overwrite_existing = 02, update_existing = 04,
    recursive = 010,
    copy_symlinks = 020, skip_symlinks = 040,
    directories_only = 0100, create_symlinks = 0200,
    create_hard_links = 0400
    };

The enumeration is a bitmask type used to convey options to copy and copy_file.

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.

directory_entry

class directory_entry
    {  // describes a directory entry
public:
    directory_entry() = default;
    directory_entry(const directory_entry&) = default;
    directory_entry(directory_entry&&) noexcept = default;
    explicit directory_entry(const PFX path& pval,
        file_status stat_arg = file_status(),
        file_status symstat_arg = file_status());
    ~directory_entry() = default;

    directory_entry& operator=(const directory_entry&) = default;
    directory_entry& operator=(directory_entry&&) noexcept = default;
    void assign(const PFX path& pval,
        file_status stat_arg = file_status(),
        file_status symstat_arg = file_status());
    void replace_filename(const PFX path& pval,
        file_status stat_arg = file_status(),
        file_status symstat_arg = file_status());

    const PFX path& path() const noexcept;
    file_status status() const;
    file_status status(
        error_code& ec) const noexcept;
    file_status symlink_status() const;
    file_status symlink_status(
        error_code& ec) const noexcept;

    bool operator==(const directory_entry& right) const noexcept;
    bool operator!=(const directory_entry& right) const noexcept;
    bool operator<(const directory_entry& right) const noexcept;
    bool operator>(const directory_entry& right) const noexcept;
    bool operator<=(const directory_entry& right) const noexcept;
    bool operator>=(const directory_entry& right) const noexcept;

    operator const path&() const; // retained

private:
    PFX path mypath;    exposition only
    mutable file_status mystat;    exposition only
    mutable file_status mysymstat;    exposition only
    };

The class describes an object returned by *X, where X is an object of class directory_iterator or recursive_directory_iterator.

The template class stores an object of type path, called mypath here for the purposes of exposition, which represents a pathname in a directory. It also stores two file_type objects: mystat, which represents what is known about the status of the pathname, and mysymstat, which represents what is known about the symlink status of the pathname.

assign

void assign(const PFX path& pval,
    file_status stat_arg = file_status(),
    file_status symstat_arg = file_status());

The member function assigns pval to mypath, stat to mystat, and symstat to mysymstat.

directory_entry

directory_entry() = default;
directory_entry(const directory_entry&) = default;
directory_entry(directory_entry&&) noexcept = default;
explicit directory_entry(const PFX path& pval,
    file_status stat_arg = file_status(),
    file_status symstat_arg = file_status());

The defaulted constructors behave as expected. The fourth constructor initializes mypath to pval, mystat to stat_arg, and mysymstat to symstat_arg.

operator!=

bool operator!=(const directory_entry& right) const noexcept;

The member function returns !(*this == right).

operator=

directory_entry& operator=(const directory_entry&) = default;
directory_entry& operator=(directory_entry&&) noexcept = default;

The defaulted member assignment operators behave as expected.

operator==

bool operator==(const directory_entry& right) const noexcept;

The member function returns mypath == right.mypath.

operator<

bool operator<(const directory_entry& right) const noexcept;

The member function returns mypath < right.mypath.

operator<=

bool operator<=(const directory_entry& right) const noexcept;

The member function returns !(right < *this).

operator>

bool operator>(const directory_entry& right) const noexcept;

The member function returns right < *this.

operator>=

bool operator>=(const directory_entry& right) const noexcept;

The member function returns !(*this < right).

operator const path_type&

operator const path&() const; // retained

The member operator returns mypath.

path

const PFX path& path() const noexcept;

The member function returns mypath.

replace_filename

void replace_filename(const PFX path& pval,
    file_status stat_arg = file_status(),
    file_status symstat_arg = file_status());

The member function replaces mypath with mypath.parent_path() / pval, mystat with stat_arg, and mysymstat with symstat_arg

status

file_status status() const;
file_status status(
    error_code& ec) const noexcept;

Both member functions return mystat possibly first altered as follows:

• If status_known(mystat) then do nothing.
• Otherwise, if !status_known(mysymstat) && !is_symlink(mysymstat) then mystat = mysymstat.
• Otherwise, mystat = status(mypval).

symlink_status

file_status symlink_status() const;
file_status symlink_status(
    error_code& ec) const noexcept;

Both member functions return mysymstat possibly first altered as follows:

• If status_known(mysymstat) then do nothing.
• Otherwise, mysymstat = symlink_status(mypval).

directory_iterator

class directory_iterator
    {  // walks a directory
public:
    typedef input_iterator_tag iterator_category;
    typedef directory_entry value_type;
    typedef ptrdiff_t difference_type;
    typedef const value_type *pointer;
    typedef const value_type& reference;

    directory_iterator() noexcept;
    explicit directory_iterator(const path& pval);
    directory_iterator(const path& pval,
        error_code& ec) noexcept;
    directory_iterator(const directory_iterator&) = default;
    directory_iterator(directory_iterator&&) noexcept = default;
    ~directory_iterator() = default;

    directory_iterator& operator=(const directory_iterator&) = default;
    directory_iterator& operator=(directory_iterator&&) noexcept = default;

    const directory_entry& operator*() const;
    const directory_entry* operator->() const;
    directory_iterator& operator++();
    directory_iterator& operator++(int);
    directory_iterator& increment(
        error_code& ec) noexcept;
    bool operator==(const directory_iterator& right) const;
    bool operator!=(const directory_iterator& right) const;

private:
    path mydir;    exposition only
    directory_entry myentry;  exposition only
    };

The class describes an input iterator that sequences through the filenames in a directory. For an iterator X, the expression *X evaluates to an object of class directory_entry that wraps the filename and anything known about its status.

The template class stores an object of type path, called mydir here for the purposes of exposition, which represents the name of the directory to be sequenced, and an object of type directory_entry called myentry here, which represents the current filename in the directory sequence. A default constructed object of type directory_entry has an empty mydir pathname and represents the end-of-sequence iterator.

For example, given the directory abc with entries def and ghi, the code:

for (directory_iterator next(path("abc")), end; next != end; ++next)
    visit(next->path());

will call visit with the arguments path("abc/def") and path("abc/ghi").

directory_iterator::directory_iterator

directory_iterator() noexcept;
explicit directory_iterator(const path& pval);
directory_iterator(const path& pval,
    error_code& ec) noexcept;
directory_iterator(const directory_iterator&) = default;
directory_iterator(directory_iterator&&) noexcept = default;

The first constructor produces an end-of-sequence iterator. The second and third constructors store pval in mydir, then attempt to open and read mydir as a directory. If successful, they store the first filename in the directory in myentry; otherwise they produce an end-of-sequence iterator.

The defaulted construtors behave as expected.

directory_iterator::increment

directory_iterator& increment(
    error_code& ec) noexcept;

The function attempts to advance to the next filename in the directory. If successful, it stores that filename in myentry; otherwise it produces an end-of-sequence iterator.

directory_iterator::operator!=

bool operator!=(const directory_iterator& right) const;

The member operator returns !(*this == right).

directory_iterator::operator=

directory_iterator& operator=(const directory_iterator&) = default;
directory_iterator& operator=(directory_iterator&&) noexcept = default;

The defaulted member assignment operators behave as expected.

directory_iterator::operator==

bool operator==(const directory_iterator& right) const;

The member operator returns true only if both *this and right are end-of-sequence iterators or both are not end-of-sequence-iterators.

directory_iterator::operator*

const directory_entry& operator*() const;

The member operator returns myentry.

directory_iterator::operator->

const directory_entry *operator->() const;

The member function returns &**this.

directory_iterator::operator++

directory_iterator& operator++();
directory_iterator& operator++(int);

The first member function calls increment(), then returns *this. The second member function makes a copy of the object, calls increment(), then returns the copy.

directory_options

enum class directory_options {
    none = 0, follow_directory_symlink
    };

The enumeration is used to convey options to the constructors for recursive_directory_iterator.

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

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 designate 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.type() != file_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 designated 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).

file_status

class file_status
    { // stores file type and permissions
public:
    explicit file_status(file_type ftype = file_type::none,
        perms mask = perms::unknown) noexcept;
    file_status(const file_status&) noexcept = default;
    file_status(file_status&&) noexcept = default;
    ~file_status = default;

    file_status& operator=(const file_status&) noexcept = default;
    file_status& operator=(file_status&&) nexcept = default;

    file_type type() const noexcept;
    perms permissions() const noexcept;

private:
    file_type mytype;    exposition only
    perms mymask;    exposition only
    };

The class wraps an object of type file_type, called mytype here for the purposes of exposition, which describes the type of a file, and an object of type perms, called mymask, which describes the access permissions mask for a file.

file_status::file_status

explicit file_status(file_type ftype = file_type::none,
    perms mask = perms::unknown) noexcept;
file_status(const file_status&) noexcept = default;
file_status(file_status&&) noexcept = default;

The first constructor stores ftype in mytype and mask in mymask. The defaulted constructors behave as expected.

file_status::operator=

file_status& operator=(const file_status&) noexcept = default;
file_status& operator=(file_status&&) nexcept = default;

The defaulted member assignment operators behave as expected.

file_status::permissions

perms permissions() const noexcept;

The member function returns mymask.

file_status::type

file_type type() const noexcept;

The member function returns mytype.

file_time_type

typedef chrono::time_point<unspecified-clock> file_time_type;

The type definition defines the type of the return value for last_write_time.

file_type

enum class file_type {
    not_found = -1, none, regular,
    directory, symlink, block,
    character, fifo, socket,
    unknown
    };

The enumeration is used to describe the type of a file, as returned by the type member function in file_status.

filesystem_error

class filesystem_error
    : public system_error
    {  // describes a filesystem error
    filesystem_error(const string& what_arg, error_code ec);
    filesystem_error(const string& what_arg,
        const path& pval1, error_code ec);
    filesystem_error(const string& what_arg,
        const path& pval1, const path& pval2, error_code ec);

    const path& path1() const noexcept;
    const path& path2() const noexcept;
    const char *what() const noexcept;

private:
	string mymesg;    exposition only
    path mypval1;    exposition only
	path mypval2;    exposition only

    };

The class serves as the base class for all exceptions thrown to report an error in <filesystem> functions. It stores an object of type string, called mymesg here for the purposes of exposition. It also stores two objects of type path, called mypval1 and mypval2.

filesystem_error::filesystem_error

filesystem_error(const string& what_arg, error_code ec);
filesystem_error(const string& what_arg,
    const path& pval1, error_code ec);
filesystem_error(const string& what_arg,
    const path& pval1, const path& pval2, error_code ec);

The first constructor constructs its message from what_arg and ec. The second constructor also constructs its message from pval1, which it stores in mypval1. The third constructor also constructs its message from pval1, which it stores in mypval1, and from pval2, which it stores in mypval2.

filesystem_error::path1

const path& path1() const noexcept;

The member function returns mypval1

filesystem_error::path2

const path& path2() const noexcept;

The member function returns mypval2

filesystem_error::what

const char *what() const noexcept;

The member function returns a pointer to an NTBS, preferably composed from runtime_error::what(), system_error::what(), mymesg, mypval1.native_string(), and mypval2.native_string().

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_file(status(pval)).

is_empty

bool is_empty(file_status stat) noexcept;
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 stat.type() == file_type::other. 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.

operator!=

bool operator!=(const path& left, const path& right) noexcept;

The function returns !(left == right).

operator==

bool operator==(const path& left, const path& right) noexcept;

The function returns left.native() == right.native().

operator<

bool operator<(const path& left, const path& right) noexcept;

The function returns left.native() < right.native().

operator<=

bool operator<=(const path& left, const path& right) noexcept;

The function returns !(right < left).

operator<<

template<class Elem, class Traits>
    basic_ostream<Elem, Traits>&
    operator<<(basic_ostream<Elem, Traits>& os, const path& pval);

The function returns os << pval.string<Elem, Traits>().

operator>

bool operator>(const path& left, const path& right) noexcept;

The function returns right < left.

operator>=

bool operator>=(const path& left, const path& right) noexcept;

The function returns !(left < right).

operator>>

template<class Elem, class Traits>
    basic_istream<Elem, Traits>&
    operator<<(basic_istream<Elem, Traits>& is, const path& pval);

The function executes:

basic_string<Elem, Traits> str;
is >> str;
pval = str;
return (is);

operator/

path operator/(const path& left, const path& right);

The function executes:

basic_string<Elem, Traits> str;
path ans = left;
return (ans /= right);

path

append · assign · begin · c_str · clear · compare · concat · const_iterator · empty · end · extension · filename · generic_string · generic_u16string · generic_u32string · generic_u8string · generic_wstring · has_extension · has_filename · has_parent_path · has_relative_path · has_root_directory · has_root_name · has_root_path · has_stem · is_absolute · is_relative · iterator · make_preferred · native · operator string_type · operator+= · operator/= · operator= · parent_path · path · preferred_separator · relative_path · remove_filename · replace_extension · replace_filename · root_directory · root_name · root_path · stem · string · string_type · swap · u16string · u32string · u8string · value_type · wstring

class path
    {  // stores a path name
public:
#if _WIN32_C_LIB
    typedef wchar_t value_type;
    static constexpr value_type preferred_separator == L'\\';
#else // assume Posix
    typedef char value_type;
    static constexpr value_type preferred_separator == '/';
#endif // filesystem model now defined
    typedef basic_string<value_type> string_type;

    path();
    path(const path& right);
    path(path&& right) noexcept;
    template<class Source>
        path(const Source& source);
    template<class Source>
        path(const Source& source, const locale& loc);
    template<class InIt>
        path(InIt first, InIt last);
    template<class InIt>
        path(InIt first, InIt last, const locale& loc);
    ~path();

    path& operator=(const path& right);
    path& operator=(path&& right) noexcept;
    template<class Source>
        path& operator=(const Source& source);
    template<class Source>
        path& assign(const Source& source);
    template<class InIt>
        path& assign(InIt first, InIt last);

    path& operator/=(const path& right);
    template<class Source>
        path& operator/=(const Source& source);
    template<class Source>
        path& append(const Source& source);
    template<class InIt>
        path& append(InIt first, InIt last);

    path& operator+=(const path& right);
    path& operator+=(const string_type& str);
    path& operator+=(const value_type *ptr);
    path& operator+=(value_type elem);
    template<class Source>
        path& operator+=(const Source& source);
    template<class Elem>
        path& operator+=(Elem elem);
    template<class Source>
        path& concat(const Source& source);
    template<class InIt>
        path& concat(InIt first, InIt last);

    void clear() noexcept;
    path& make_preferred();
    path& remove_filename();
    path& replace_filename(const path& pval);
    path& replace_extension(const path& newext = path());
    void swap(path & right) noexcept;

    const string_type& native() const noexcept;
    const value_type& *c_str() const noexcept;
    operator string_type() const;

    template<class Elem,
        class Traits = char_traits<Elem>,
        class Alloc = allocator<Elem>>
        basic_string<Elem, Traits, Alloc>
            string(const Alloc& al = Alloc()) const;
    STD string string() const;
    STD wstring wstring() const;
    STD string u8string() const;
    STD u16string u16string() const;
    STD u32string u32string() const;

    template<class Elem,
        class Traits = char_traits<Elem>,
        class Alloc = allocator<Elem>>
        basic_string<Elem, Traits, Alloc>
            generic_string(const Alloc& al = Alloc()) const;
    STD string generic_string() const;
    STD wstring generic_wstring() const;
    STD string generic_u8string() const;
    STD u16string generic_u16string() const;
    STD u32string generic_u32string() const;

    int compare(const path& pval) const noexcept;
    int compare(const string_type& str) const;
    int compare(const value_type *ptr) const;

    path root_name() const;
    path root_directory() const;
    path root_path() const;
    path relative_path() const;
    path parent_path() const;
    path filename() const;
    path stem() const;
    path extension() const;

    bool empty() const noexcept;
    bool has_root_name() const;
    bool has_root_directory() const;
    bool has_root_path() const;
    bool has_relative_path() const;
    bool has_parent_path() const;
    bool has_filename() const;
    bool has_stem() const;
    bool has_extension() const;
    bool is_absolute() const;
    bool is_relative() const;

    class iterator;
    typedef iterator const_iterator;
    iterator begin() const;
    iterator end() const;

private:
    string_type myname;    exposition only
    };

The class stores an object of type string_type, called myname here for the purposes of exposition, suitable for use as a pathname. string_type is a synonym for basic_string<value_type>, where value_type is a synonym for char under Windows or wchar_t under Posix.

path::append

template<class Source>
    path& append(const Source& source);
template<class InIt>
    path& append(InIt first, InIt last);

The member functions append the specified sequence to mypath, converted and inserting a preferred_separator as needed.

path::assign

template<class Source>
    path& assign(const Source& source);
template<class InIt>
    path& assign(InIt first, InIt last);

The member functions replace mypath with the specified sequence, converted as needed.

path::begin

iterator begin() const;

The member function returns a path::iterator designating the first path element in the pathname, if present.

path::c_str

const value_type& *c_str() const noexcept;

The member function returns a pointer to the first character in mypath.

path::clear

void clear() noexcept;

The member function executes mypath.clear().

path::compare

int compare(const path& pval) const noexcept;
int compare(const string_type& str) const;
int compare(const value_type *ptr) const;

The first function returns mypath.compare(pval.native()). The second function returns mypath.compare(str). The third function returns mypath.compare(ptr).

path::concat

template<class Source>
    path& concat(const Source& source);
template<class InIt>
    path& concat(InIt first, InIt last);

The member functions append the specified sequence to mypath, converted (but not inserting a separator) as needed.

path::const_iterator

typedef iterator const_iterator;

The type is a synonym for iterator.

path::empty

bool empty() const noexcept;

The member function returns mypath.empty().

path::end

iterator end() const;

The member function returns an end-of-sequence iterator of type iterator.

path::extension

path extension() const;

The member function returns the suffix of filename() X such that:

• If X == path(".") || X == path("..") or if X contains no dot, the suffix is empty.
• Otherwise, the suffix begins with (and includes) the rightmost dot.

path::filename

path filename() const;

The member function returns the root directory component of myname, specifically empty() ? path() : *--end(). The component may be empty.

path::generic_string

template<class Elem,
    class Traits = char_traits<Elem>,
    class Alloc = allocator<Elem>>
    basic_string<Elem, Traits, Alloc>
        generic_string(const Alloc& al = Alloc()) const;
STD string generic_string() const;

The member function returns this->string<Elem, Traits, Alloc>(_Al) with (under Windows) any backslash converted to a forward slash.

path::generic_u16string

STD u16string generic_u16string() const;

The member function returns u16string() with (under Windows) any backslash converted to a forward slash.

path::generic_u32string

STD u32string generic_u32string() const;

The member function returns u32string() with (under Windows) any backslash converted to a forward slash.

path::generic_u8string

STD string generic_u8string() const;

The member function returns u8string() with (under Windows) any backslash converted to a forward slash.

path::generic_wstring

STD wstring generic_wstring() const;

The member function returns wstring() with (under Windows) any backslash converted to a forward slash.

path::has_extension

bool has_extension() const;

The member function returns !extension().empty().

path::has_filename

bool has_filename() const;

The member function returns !filename().empty().

path::has_parent_path

bool has_parent_path() const;

The member function returns !parent_path().empty().

path::has_relative_path

bool has_relative_path() const;

The member function returns !relative_path().empty().

path::has_root_directory

bool has_root_directory() const;

The member function returns !root_directory().empty().

path::has_root_name

bool has_root_name() const;

The member function returns !root_name().empty().

path::has_root_path

bool has_root_path() const;

The member function returns !root_path().empty().

path::has_stem

bool has_stem() const;

The member function returns !stem().empty().

path::is_absolute

bool is_absolute() const;

For Windows, the function returns has_root_name() && has_root_directory(). For Posix, the function returns has_root_directory().

path::is_relative

bool is_relative() const;

The member function returns !is_absolute().

path::iterator

class iterator
    {	// bidirectional iterator for path
    typedef bidirectional_iterator_tag iterator_category;
    typedef path_type value_type;
    typedef ptrdiff_t difference_type;
    typedef const value_type *pointer;
    typedef const value_type& reference;
    .....
    };

The class describes a bidirectional constant iterator that designates the path components of myname in the sequence:

• the root name, if present
• the root directory, if present
• the remaining directory elements of the parent path, if present, ending with
• the filename, if present

For pval an object of type path:

• path::iterator X = pval.begin() designates the first path element in the pathname, if present.
• X == pval.end() is true when X points just past the end of the sequence of components.
• *X returns a string that matches the current component
• ++X designates the next component in the sequence, if present.
• --X designates the preceding component in the sequence, if present.

Altering myname invalidates all iterators designating elements in myname.

path::make_preferred

path& make_preferred();

The member function converts each separator to a preferred_separator as needed.

path::native

const string_type& native() const noexcept;

The member function returns myname.

path::operator=

path& operator=(const path& right);
path& operator=(path&& right) noexcept;
template<class Source>
    path& operator=(const Source& source);

The first member operator copies right.myname to myname. The second member operator moves right.myname to myname. The third member operator behaves the same as *this = path(source).

path::operator+=

path& operator+=(const path& right);
path& operator+=(const string_type& str);
path& operator+=(const value_type *ptr);
path& operator+=(value_type elem);
template<class Source>
    path& operator+=(const Source& source);
template<class Elem>
    path& operator+=(Elem elem);

The member functions behave the same as the following corresponding expressions:

concat(right);
concat(path(str));
concat(ptr);
concat(string_type(1, elem));
concat(source);
concat(path(basic_string<Elem>(1, elem)));

path::operator/=

path& operator/=(const path& right);
template<class Source>
    path& operator/=(const Source& source);

The member functions behave the same as the following corresponding expressions:

append(right);
append(source);

path::operator string_type

operator string_type() const;

The member operator returns myname.

path::parent_path

path parent_path() const;

The member function returns the parent path component of myname, specifically the prefix of myname after removing filename().native() and any immediately preceding directory separators. (Equally, if begin() != end(), it is the combining of all elements in the range [begin(), --end()) by successively applying operator/=.) The component may be empty.

path::path

path();
path(const path& right);
path(path&& right) noexcept;
template<class Source>
    path(const Source& source);
template<class Source>
    path(const Source& source, const locale& loc);
template<class InIt>
    path(InIt first, InIt last);
template<class InIt>
    path(InIt first, InIt last, const locale& loc);

The constructors all construct myname in various ways:

• For path() it is myname().
• For path(const path& right) it is myname(right.myname).
• For path(path&& right) it is myname(right.myname).
• For template<class Source> path(const Source& source) it is myname(source).
• For template<class Source> path(const Source& source, const locale& loc) it is myname(source), obtaining any needed codecvt facets from loc.
• For template<class InIt> path(InIt first, InIt last) it is myname(first, last).
• For template<class InIt> path(InIt first, InIt last, const locale& loc) it is myname(first, last), obtaining any needed codecvt facets from loc.

path::preferred_separator

#if _WIN32_C_LIB
static constexpr value_type preferred_separator == L'\\';
#else // assume Posix
static constexpr value_type preferred_separator == '/';
#endif // filesystem model now defined

The constant object gives the preferred character for separating path components, depending on the host operating system. Note that it is equally permissible in most contexts under Windows to use L'/' in its place.

path::relative_path

path relative_path() const;

The member function returns the relative path component of myname, specifically the suffix of myname after removing root_path().native() and any immediately subsequent redundant directory separators. The component may be empty.

path::remove_filename

path& remove_filename();

The member function returns a path containing the prefix of myname after removing filename().native() and any immediately previous directory separators.

path::replace_extension

path& replace_extension(const path& newext = path());

The member function first removes the suffix extension().native() from myname. Then if !newext.empty() && newext[0] != dot (where dot is *path(".").c_str()), then dot is appended to myname. Then newext is appended to myname.

path::replace_filename

path& replace_filename(const path& pval);

The member function executes:

remove_filename();
*this /= pval;
return (*this);

path::root_directory

path root_directory() const;

The member function returns the root directory component of myname. The component may be empty.

path::root_name

path root_name() const;

The member function returns the root name component of myname. The component may be empty.

path::root_path

path root_path() const;

The member function returns the root path component of myname, specifically root_name() / root_directory. The component may be empty.

path::stem

path stem() const;

The member function returns the stem component of myname, specifically filename().native() with any trailing extension().native() removed. The component may be empty.

path::string

template<class Elem,
    class Traits = char_traits<Elem>,
    class Alloc = allocator<Elem>>
    basic_string<Elem, Traits, Alloc>
        string(const Alloc& al = Alloc()) const;
STD string string() const;

The first (template) member function converts the sequence stored in mypath the same way as:

• string() for string<char, Traits, Alloc>()
• wstring() for string<wchar_t, Traits, Alloc>()
• u16string() for string<char16_t, Traits, Alloc>()
• u32string() for string<char32_t, Traits, Alloc>()

The second member function converts the sequence stored in mypath to the encoding favored by the host system for a char sequence and returns it stored in an object of type string.

path::string_type

typedef basic_string<value_type> string_type;

The type is a synonym for basic_string<value_type>.

path::swap

void swap(path & right) noexcept;

Executes swap(mypath, right.mypath).

path::u16string

STD u16string u16string() const;

The member function converts the sequence stored in mypath to UTF-16 and returns it stored in an object of type u16string.

path::u32string

STD u32string u32string() const;

The member function converts the sequence stored in mypath to UTF-32 and returns it stored in an object of type u32string.

path::u8string

STD string u8string() const;

The member function converts the sequence stored in mypath to UTF-8 and returns it stored in an object of type u8string.

path::value_type

#if _WIN32_C_LIB
typedef wchar_t value_type;
#else // assume Posix
typedef char value_type;
#endif // filesystem model now defined

The type describes the path elements favored by the host operating system.

path::wstring

STD wstring wstring() const;

The member function converts the sequence stored in mypath to the encoding favored by the host system for a wchar_t sequence and returns it stored in an object of type wstring.

permissions

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

The functions set the permissions for the pathname designated 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.

perms

enum class perms {
    none = 0,
    owner_read = 0400, owner_write = 0200,
    owner_exec = 0100, owner_all = 0700,
    group_read = 040, group_write = 020,
    group_exec = 010, group_all = 070,
    others_read = 04, others_write = 02,
    others_exec = 01, others_all = 07,
    all = 0777,
    set_uid = 04000, set_gid = 02000,
    sticky_bit = 01000,
    mask = 07777, unknown = 0xffff,
    add_perms = 0x10000, remove_perms = 0x2000,
    resolve_symlinks = 0x40000
    };

The enumeration is a bitmask type used to convey permissions and options to permissions.

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.

recursive_directory_iterator

class recursive_directory_iterator
    {  // walks a directory tree
public:
    typedef input_iterator_tag iterator_category;
    typedef directory_entry value_type;
    typedef ptrdiff_t difference_type;
    typedef const value_type *pointer;
    typedef const value_type& reference;

    recursive_directory_iterator() noexcept;
    recursive_directory_iterator(
        const recursive_directory_iterator&) = default;
    explicit recursive_directory_iterator(const path& pval,
        directory_options opts = directory_options::none);
    recursive_directory_iterator(const path& pval,
        directory_options opts,
        error_code& ec) noexcept;
    recursive_directory_iterator(const path& pval,
        error_code& ec) noexcept;
    recursive_directory_iterator(const path& pval,
        directory_options opts);
    recursive_directory_iterator(const path& pval,
        directory_options opts,
        error_code& ec) noexcept;
    recursive_directory_iterator(
        recursive_directory_iterator&&) noexcept = default;
    ~recursive_directory_iterator() = default;

    recursive_directory_iterator& operator=(const recursive_directory_iterator&) = default;
    recursive_directory_iterator& operator=(recursive_directory_iterator&&) noexcept = default;

    directory_options options() const;
    int depth() const;
    bool recursion_pending() const;

    void pop();
    void disable_recursion_pending();

    const directory_entry& operator*() const;
    const directory_entry* operator->() const;
    recursive_directory_iterator& operator++();
    recursive_directory_iterator& operator++(int);
    recursive_directory_iterator& increment(
        error_code& ec) noexcept;
    bool operator==(const recursive_directory_iterator& right) const;
    bool operator!=(const recursive_directory_iterator& right) const;

private:
    stack<pair<directory_iterator, path>> mystack;    exposition only
	directory_entry myentry;    exposition only
	bool no_push;    exposition only
	directory_options myoptions;    exposition only
    };

The class describes an input iterator that sequences through the filenames in a directory, possibly descending into subdirectories recursively. For an iterator X, the expression *X evaluates to an object of class directory_entry that wraps the filename and anything known about its status.

The template class stores:

• an object of type stack<pair<directory_iterator, path>>, called mystack here for the purposes of exposition, which represents the nest of directories to be sequenced
• an object of type directory_entry called myentry here, which represents the current filename in the directory sequence
• an object of type bool, called no_push here, which records whether recursive descent into subdirectories is disabled
• an object of type directory_options, called myoptions here, which records the options established at construction

A default constructed object of type recursive_directory_entry has an end-of-sequence iterator at mystack.top().first and represents the end-of-sequence iterator.

For example, given the directory abc with entries def (a directory), def/ghi, and jkl, the code:

for (recursive_directory_iterator next(path("abc")), end; next != end; ++next)
    visit(next->path());

will call visit with the arguments path("abc/def/ghi") and path("abc/jkl").

You can qualify sequencing through a directory subtree in two ways:

• A directory symlink will be scanned only if you construct a recursive_directory_iterator with a directory_options argument whose value is directory_options::follow_directory_symlink.
• If you call disable_recursion_pending then a subsequent directory encountered during an increment will not be recursively scanned.

recursive_directory_iterator::depth

int depth() const;

The member function returns mystack.size() - 1, so pval is at depth zero.

recursive_directory_iterator::disable_recursion_pending

void disable_recursion_pending();

The member function stores true in no_push.

recursive_directory_iterator::operator!=

bool operator!=(const recursive_directory_iterator& right) const;

The member operator returns !(*this == right).

recursive_directory_iterator::operator=

recursive_directory_iterator& operator=(const recursive_directory_iterator&) = default;
recursive_directory_iterator& operator=(recursive_directory_iterator&&) noexcept = default;

The defaulted member assignment operators behave as expected.

recursive_directory_iterator::operator==

bool operator==(const recursive_directory_iterator& right) const;

The member operator returns true only if both *this and right are end-of-sequence iterators or both are not end-of-sequence-iterators.

recursive_directory_iterator::operator*

const directory_entry& operator*() const;

The member operator returns myentry.

recursive_directory_iterator::operator->

const directory_entry *operator->() const;

The member function returns &**this.

recursive_directory_iterator::operator++

recursive_directory_iterator& operator++();
recursive_directory_iterator& operator++(int);

The first member function calls increment(), then returns *this. The second member function makes a copy of the object, calls increment(), then returns the copy.

recursive_directory_iterator::options

directory_options options() const;

The member function returns myoptions.

recursive_directory_iterator::pop

void pop();

If depth() == 0 the object becomes an end-of-sequence iterator. Otherwise, the member function terminates scanning of the current (deepest) directory and resumes at the next lower depth.

recursive_directory_iterator::recursion_pending

bool recursion_pending() const;

The member function returns !no_push.

recursive_directory_iterator::recursive_directory_iterator

recursive_directory_iterator() noexcept;
explicit recursive_directory_iterator(const path& pval);
recursive_directory_iterator(const path& pval,
    error_code& ec) noexcept;
recursive_directory_iterator(const path& pval,
    directory_options opts);
recursive_directory_iterator(const path& pval,
    directory_options opts,
    error_code& ec) noexcept;
recursive_directory_iterator(const recursive_directory_iterator&) = default;
recursive_directory_iterator(recursive_directory_iterator&&) noexcept = default;

The first constructor produces an end-of-sequence iterator. The second and third constructors store false in no_push and directory_options::none in myoptions, then attempt to open and read pval as a directory. If successful, they initialize mystack and myentry to designate the first non-directory filename in the nested sequence; otherwise they produce an end-of-sequence iterator.

The fourth and fifth constructors behave the same as the second and third, except that they first store opts in myoptions. The defaulted construtors behave as expected.

recursive_directory_iterator::increment

recursive_directory_iterator& increment(
    error_code& ec) noexcept;

The function attempts to advance to the next filename in the nested sequence. If successful, it stores that filename in myentry; otherwise it produces an end-of-sequence iterator.

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 designates.

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 designates.

resize_file

void resize(const path& pval, uintmax_t size);
void resize(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 designated by pval, in a structure of type space_info. The structure contains uintmax_t(-1) for any value that cannot be determined.

space_info

struct space_info {
    uintmax_t capacity;
    uintmax_t free;
    uintmax_t available;

The struct stores the values returned by a call to space. The members are:

• capacity, for the total number of bytes the volume can represent.
• free, for the number of bytes not used to represent data on the volume.
• available, for the number of bytes available to represent data on the volume.

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 designates.

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,
    erroxr_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 designates.

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<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 designated source in each case is taken as a sequence of char elements encoded as UTF-8, regardless of the filesystem.

See also the Table of Contents and the Index.

Copyright (c) by P.J. Plauger. All rights reserved.