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 pathobject; // exposition only friend class directory_iterator; // exposition only }; }
1
#
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.
2
#
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.
3
#
[Note 1: 
For purposes of exposition, class directory_iterator ([fs.class.directory.iterator]) is shown above as a friend of class directory_entry.
Friendship allows the directory_iterator implementation to cache already available attribute values directly into a directory_entry object without the cost of an unneeded call to refresh().
— end note]
4
#
[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);
1
#
Effects: Calls refresh() or refresh(ec), respectively.
2
#
Postconditions: path() == p if no error occurs, otherwise path() == filesystem​::​path().
3
#
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);
1
#
Effects: Equivalent to pathobject = p, then refresh() or refresh(ec), respectively.
If an error occurs, the values of any cached attributes are unspecified.
2
#
Throws: As specified in [fs.err.report].
🔗
void replace_filename(const filesystem::path& p); void replace_filename(const filesystem::path& p, error_code& ec);
3
#
Effects: Equivalent to pathobject.replace_filename(p), then refresh() or refresh(ec), respectively.
If an error occurs, the values of any cached attributes are unspecified.
4
#
Throws: As specified in [fs.err.report].
🔗
void refresh(); void refresh(error_code& ec) noexcept;
5
#
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.
6
#
Throws: As specified in [fs.err.report].
7
#
[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]

1
#
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;
2
#
Returns: pathobject.
🔗
bool exists() const; bool exists(error_code& ec) const noexcept;
3
#
Returns: exists(this->status()) or exists(this->status(ec)), respectively.
4
#
Throws: As specified in [fs.err.report].
🔗
bool is_block_file() const; bool is_block_file(error_code& ec) const noexcept;
5
#
Returns: is_block_file(this->status()) or is_block_file(this->status(ec)), respectively.
6
#
Throws: As specified in [fs.err.report].
🔗
bool is_character_file() const; bool is_character_file(error_code& ec) const noexcept;
7
#
Returns: is_character_file(this->status()) or is_character_file(this->status(ec)), respectively.
8
#
Throws: As specified in [fs.err.report].
🔗
bool is_directory() const; bool is_directory(error_code& ec) const noexcept;
9
#
Returns: is_directory(this->status()) or is_directory(this->status(ec)), respectively.
10
#
Throws: As specified in [fs.err.report].
🔗
bool is_fifo() const; bool is_fifo(error_code& ec) const noexcept;
11
#
Returns: is_fifo(this->status()) or is_fifo(this->status(ec)), respectively.
12
#
Throws: As specified in [fs.err.report].
🔗
bool is_other() const; bool is_other(error_code& ec) const noexcept;
13
#
Returns: is_other(this->status()) or is_other(this->status(ec)), respectively.
14
#
Throws: As specified in [fs.err.report].
🔗
bool is_regular_file() const; bool is_regular_file(error_code& ec) const noexcept;
15
#
Returns: is_regular_file(this->status()) or is_regular_file(this->status(ec)), respectively.
16
#
Throws: As specified in [fs.err.report].
🔗
bool is_socket() const; bool is_socket(error_code& ec) const noexcept;
17
#
Returns: is_socket(this->status()) or is_socket(this->status(ec)), respectively.
18
#
Throws: As specified in [fs.err.report].
19
#
Returns: is_symlink(this->symlink_status()) or is_symlink(this->symlink_status(ec)), respectively.
20
#
Throws: As specified in [fs.err.report].
🔗
uintmax_t file_size() const; uintmax_t file_size(error_code& ec) const noexcept;
21
#
Returns: If cached, the file size attribute value.
Otherwise, file_size(path()) or file_size(path(), ec), respectively.
22
#
Throws: As specified in [fs.err.report].
23
#
Returns: If cached, the hard link count attribute value.
Otherwise, hard_link_count(path()) or hard_link_count(path(), ec), respectively.
24
#
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;
25
#
Returns: If cached, the last write time attribute value.
Otherwise, last_write_time(path()) or last_write_time(path(), ec), respectively.
26
#
Throws: As specified in [fs.err.report].
🔗
file_status status() const; file_status status(error_code& ec) const noexcept;
27
#
Returns: If cached, the status attribute value.
Otherwise, status(path()) or status(path(), ec), respectively.
28
#
Throws: As specified in [fs.err.report].
29
#
Returns: If cached, the symlink status attribute value.
Otherwise, symlink_status(path()) or symlink_status(path(), ec), respectively.
30
#
Throws: As specified in [fs.err.report].
🔗
bool operator==(const directory_entry& rhs) const noexcept;
31
#
Returns: pathobject == rhs.pathobject.
🔗
strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
32
#
Returns: pathobject <=> rhs.pathobject.

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);
1
#
Effects: Equivalent to: return os << d.path();