30 Input/output library [input.output]

30.10 File systems [filesystems]

30.10.12 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 path& p);
    directory_entry(const 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 path& p);
    void assign(const path& p, error_code& ec);
    void replace_filename(const path& p);
    void replace_filename(const path& p, error_code& ec);
    void refresh();
    void refresh(error_code& ec) noexcept;

    // [fs.dir.entry.obs], observers
    const path& path() const noexcept;
    operator const 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;
    bool operator==(const directory_entry& rhs) const noexcept;
    bool operator!=(const directory_entry& rhs) const noexcept;
    bool operator<=(const directory_entry& rhs) const noexcept;
    bool operator> (const directory_entry& rhs) const noexcept;
    bool operator>=(const directory_entry& rhs) const noexcept;

  private:
    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 are encouraged to 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
 ]

30.10.12.1 directory_­entry constructors [fs.dir.entry.cons]

explicit directory_entry(const path& p); directory_entry(const path& p, error_code& ec);
1
#
Effects: Constructs an object of type directory_­entry, then refresh() or refresh(ec), respectively.
2
#
Postconditions: path() == p if no error occurs, otherwise path() == std​::​filesystem​::​path().
3
#
Throws: As specified in [fs.err.report].

30.10.12.2 directory_­entry modifiers [fs.dir.entry.mods]

void assign(const path& p); void assign(const 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 path& p); void replace_filename(const 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
 ]

30.10.12.3 directory_­entry 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 path& path() const noexcept; operator const 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.
bool operator!=(const directory_entry& rhs) const noexcept;
32
#
Returns: pathobject != rhs.pathobject.
bool operator< (const directory_entry& rhs) const noexcept;
33
#
Returns: pathobject < rhs.pathobject.
bool operator<=(const directory_entry& rhs) const noexcept;
34
#
Returns: pathobject <= rhs.pathobject.
bool operator> (const directory_entry& rhs) const noexcept;
35
#
Returns: pathobject > rhs.pathobject.
bool operator>=(const directory_entry& rhs) const noexcept;
36
#
Returns: pathobject >= rhs.pathobject.