29 Input/output library [input.output]

29.11 File systems [filesystems]

29.11.10 Class directory_­entry [fs.class.directory.entry]

29.11.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; 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]

29.11.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].

29.11.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.
Throws: As specified in [fs.err.report].
🔗
void refresh(); void refresh(error_code& ec) noexcept;
4
#
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.
5
#
Throws: As specified in [fs.err.report].
6
#
[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]

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