31 Input/output library [input.output]

31.12 File systems [filesystems]

31.12.10 Class directory_entry [fs.class.directory.entry]

31.12.10.1 General [fs.class.directory.entry.general]

namespace std::filesystem { class directory_entry { public: // [fs.dir.entry.cons], constructors and destructor directory_entry() noexcept = default; directory_entry(const directory_entry&) = default; directory_entry(directory_entry&&) noexcept = default; explicit directory_entry(const filesystem::path& p); directory_entry(const filesystem::path& p, error_code& ec); ~directory_entry(); // assignments directory_entry& operator=(const directory_entry&) = default; directory_entry& operator=(directory_entry&&) noexcept = default; // [fs.dir.entry.mods], modifiers void assign(const filesystem::path& p); void assign(const filesystem::path& p, error_code& ec); void replace_filename(const filesystem::path& p); void replace_filename(const filesystem::path& p, error_code& ec); void refresh(); void refresh(error_code& ec) noexcept; // [fs.dir.entry.obs], observers const filesystem::path& path() const noexcept; operator const filesystem::path&() const noexcept; bool exists() const; bool exists(error_code& ec) const noexcept; bool is_block_file() const; bool is_block_file(error_code& ec) const noexcept; bool is_character_file() const; bool is_character_file(error_code& ec) const noexcept; bool is_directory() const; bool is_directory(error_code& ec) const noexcept; bool is_fifo() const; bool is_fifo(error_code& ec) const noexcept; bool is_other() const; bool is_other(error_code& ec) const noexcept; bool is_regular_file() const; bool is_regular_file(error_code& ec) const noexcept; bool is_socket() const; bool is_socket(error_code& ec) const noexcept; bool is_symlink() const; bool is_symlink(error_code& ec) const noexcept; uintmax_t file_size() const; uintmax_t file_size(error_code& ec) const noexcept; uintmax_t hard_link_count() const; uintmax_t hard_link_count(error_code& ec) const noexcept; file_time_type last_write_time() const; file_time_type last_write_time(error_code& ec) 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& rhs) const noexcept; strong_ordering operator<=>(const directory_entry& rhs) const noexcept; // [fs.dir.entry.io], inserter template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const directory_entry& d); private: filesystem::path path-object; // exposition only }; }
A directory_entry object stores a path object and may store additional objects for file attributes such as hard link count, status, symlink status, file size, and last write time.
Implementations should store such additional file attributes during directory iteration if their values are available and storing the values would allow the implementation to eliminate file system accesses by directory_entry observer functions ([fs.op.funcs]).
Such stored file attribute values are said to be cached.
[Note 1: 
directory_iterator can cache already available attribute values directly into a directory_entry object without the cost of a call to refresh().
— end note]
[Example 1: using namespace std::filesystem; // use possibly cached last write time to minimize disk accesses for (auto&& x : directory_iterator(".")) { std::cout << x.path() << " " << x.last_write_time() << std::endl; } // call refresh() to refresh a stale cache for (auto&& x : directory_iterator(".")) { lengthy_function(x.path()); // cache becomes stale x.refresh(); std::cout << x.path() << " " << x.last_write_time() << std::endl; }
On implementations that do not cache the last write time, both loops will result in a potentially expensive call to the std​::​filesystem​::​last_write_time function.
On implementations that do cache the last write time, the first loop will use the cached value and so will not result in a potentially expensive call to the std​::​filesystem​::​last_write_time function.
The code is portable to any implementation, regardless of whether or not it employs caching.
— end example]

31.12.10.2 Constructors [fs.dir.entry.cons]

explicit directory_entry(const filesystem::path& p); directory_entry(const filesystem::path& p, error_code& ec);
Effects: Calls refresh() or refresh(ec), respectively.
Postconditions: path() == p if no error occurs, otherwise path() == filesystem​::​path().
Throws: As specified in [fs.err.report].

31.12.10.3 Modifiers [fs.dir.entry.mods]

void assign(const filesystem::path& p); void assign(const filesystem::path& p, error_code& ec);
Effects: Equivalent to path-object = p, then refresh() or refresh(ec), respectively.
If an error occurs, the values of any cached attributes are unspecified.
Throws: As specified in [fs.err.report].
void replace_filename(const filesystem::path& p); void replace_filename(const filesystem::path& p, error_code& ec);
Effects: Equivalent to path-object.replace_filename(p), then refresh() or refresh(ec), respectively.
If an error occurs, the values of any cached attributes are unspecified.
Throws: As specified in [fs.err.report].
void refresh(); void refresh(error_code& ec) noexcept;
Effects: Stores the current values of any cached attributes of the file p resolves to.
If an error occurs, an error is reported ([fs.err.report]) and the values of any cached attributes are unspecified.
Throws: As specified in [fs.err.report].
[Note 1: 
Implementations of directory_iterator ([fs.class.directory.iterator]) are prohibited from directly or indirectly calling the refresh function as described in [fs.class.directory.iterator.general].
— end note]

31.12.10.4 Observers [fs.dir.entry.obs]

Unqualified function names in the Returns: elements of the directory_entry observers described below refer to members of the std​::​filesystem namespace.
const filesystem::path& path() const noexcept; operator const filesystem::path&() const noexcept;
Returns: path-object.
bool exists() const; bool exists(error_code& ec) const noexcept;
Returns: exists(this->status()) or exists(this->status(ec)), respectively.
Throws: As specified in [fs.err.report].
bool is_block_file() const; bool is_block_file(error_code& ec) const noexcept;
Returns: is_block_file(this->status()) or is_block_file(this->status(ec)), respectively.
Throws: As specified in [fs.err.report].
bool is_character_file() const; bool is_character_file(error_code& ec) const noexcept;
Returns: is_character_file(this->status()) or is_character_file(this->status(ec)), respectively.
Throws: As specified in [fs.err.report].
bool is_directory() const; bool is_directory(error_code& ec) const noexcept;
Returns: is_directory(this->status()) or is_directory(this->status(ec)), respectively.
Throws: As specified in [fs.err.report].
bool is_fifo() const; bool is_fifo(error_code& ec) const noexcept;
Returns: is_fifo(this->status()) or is_fifo(this->status(ec)), respectively.
Throws: As specified in [fs.err.report].
bool is_other() const; bool is_other(error_code& ec) const noexcept;
Returns: is_other(this->status()) or is_other(this->status(ec)), respectively.
Throws: As specified in [fs.err.report].
bool is_regular_file() const; bool is_regular_file(error_code& ec) const noexcept;
Returns: is_regular_file(this->status()) or is_regular_file(this->status(ec)), respectively.
Throws: As specified in [fs.err.report].
bool is_socket() const; bool is_socket(error_code& ec) const noexcept;
Returns: is_socket(this->status()) or is_socket(this->status(ec)), respectively.
Throws: As specified in [fs.err.report].
Returns: is_symlink(this->symlink_status()) or is_symlink(this->symlink_status(ec)), respectively.
Throws: As specified in [fs.err.report].
uintmax_t file_size() const; uintmax_t file_size(error_code& ec) const noexcept;
Returns: If cached, the file size attribute value.
Otherwise, file_size(path()) or file_size(path(), ec), respectively.
Throws: As specified in [fs.err.report].
Returns: If cached, the hard link count attribute value.
Otherwise, hard_link_count(path()) or hard_link_count(path(), ec), respectively.
Throws: As specified in [fs.err.report].
file_time_type last_write_time() const; file_time_type last_write_time(error_code& ec) const noexcept;
Returns: If cached, the last write time attribute value.
Otherwise, last_write_time(path()) or last_write_time(path(), ec), respectively.
Throws: As specified in [fs.err.report].
file_status status() const; file_status status(error_code& ec) const noexcept;
Returns: If cached, the status attribute value.
Otherwise, status(path()) or status(path(), ec), respectively.
Throws: As specified in [fs.err.report].
Returns: If cached, the symlink status attribute value.
Otherwise, symlink_status(path()) or symlink_status(path(), ec), respectively.
Throws: As specified in [fs.err.report].
bool operator==(const directory_entry& rhs) const noexcept;
Returns: path-object == rhs.path-object.
strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
Returns: path-object <=> rhs.path-object.

31.12.10.5 Inserter [fs.dir.entry.io]

template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const directory_entry& d);
Effects: Equivalent to: return os << d.path();