29 Input/output library [input.output]

29.11 File systems [filesystems]

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

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
:
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
: 
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.11.1 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.11.2 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
:
Implementations of directory_­iterator ([fs.class.directory.iterator]) are prohibited from directly or indirectly calling the refresh function since it must access the external file system, and the objective of caching is to avoid unnecessary file system accesses.
— end note
 ]

29.11.11.3 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].
🔗
bool is_symlink() const; bool is_symlink(error_code& ec) const noexcept;
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].
🔗
uintmax_t hard_link_count() const; uintmax_t hard_link_count(error_code& ec) const noexcept;
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].
🔗
file_status symlink_status() const; file_status symlink_status(error_code& ec) const noexcept;
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.