directory_entry class

Describes an object that's returned by dereferencing a directory_iterator or a recursive_directory_iterator. A directory_entry wraps a path and, as an optimization, can cache file attributes that are obtained while iterating a directory.

Syntax

class directory_entry;

Remarks

A directory_entry object stores a path. As an optimization, it can also cache the attributes and status of the file that the path refers to. The cached data is populated when the entry is created by a directory iterator, or when you call refresh. Observers such as file_size, last_write_time, status, and the various is_* predicates return the cached data when it's available; otherwise, they query the file system.

For more information and code examples, see File System Navigation (C++).

Constructors

Member functions

Operators

Requirements

Header: <filesystem>

Namespace: std::filesystem

directory_entry

Constructs a directory_entry.

directory_entry() noexcept = default;
directory_entry(const directory_entry&) = default;
directory_entry(directory_entry&&) noexcept = default;

explicit directory_entry(const std::filesystem::path& p);
directory_entry(const std::filesystem::path& p, std::error_code& ec);

~directory_entry();

Parameters

p
The path to the file that the entry refers to.

ec
The output error code for the operation.

Remarks

The default, copy, and move constructors behave as expected. The constructors that take a path store p and then call refresh to populate the cached attributes. The overload that takes an error_code reports errors in ec instead of throwing, and clears the stored path if the refresh fails.

operator=

Assigns to the directory_entry.

directory_entry& operator=(const directory_entry&) = default;
directory_entry& operator=(directory_entry&&) noexcept = default;

Parameters

right
The directory_entry to copy or move into this directory_entry.

Remarks

The defaulted assignment operators behave as expected.

assign

Replaces the stored path and refreshes the cached attributes.

void assign(const std::filesystem::path& p);
void assign(const std::filesystem::path& p, std::error_code& ec);

Parameters

p
The new path to store.

ec
The output error code for the operation.

Remarks

Replaces the stored path with p, then calls refresh to update the cached attributes. The overload that takes an error_code reports errors in ec instead of throwing.

replace_filename

Replaces the filename of the stored path and refreshes the cached attributes.

void replace_filename(const std::filesystem::path& p);
void replace_filename(const std::filesystem::path& p, std::error_code& ec);

Parameters

p
The replacement filename.

ec
The output error code for the operation.

Remarks

Replaces the filename component of the stored path with p, as if by path().replace_filename(p), then calls refresh. The overload that takes an error_code reports errors in ec instead of throwing.

refresh

Refreshes the cached file attributes.

void refresh();
void refresh(std::error_code& ec) noexcept;

Parameters

ec
The output error code for the operation.

Remarks

Reads the attributes of the file that the stored path refers to and caches them in the directory_entry. Call refresh to update the cached data after the referenced file changes. The overload that takes an error_code reports errors in ec instead of throwing.

path

Returns the stored path.

const std::filesystem::path& path() const noexcept;

operator const path&

Returns the stored path.

operator const std::filesystem::path&() const noexcept;

exists

Checks whether the entry refers to an existing file.

bool exists() const;
bool exists(std::error_code& ec) const noexcept;

Parameters

ec
The output error code for the operation.

Return value

true if the stored path refers to an existing file; otherwise, false. Equivalent to calling filesystem::exists(status()).

is_block_file

Checks whether the referenced file is a block special file.

bool is_block_file() const;
bool is_block_file(std::error_code& ec) const noexcept;

Parameters

ec
The output error code for the operation.

Return value

true if the referenced file is a block special file; otherwise, false. This function always returns false on Windows.

is_character_file

Checks whether the referenced file is a character special file.

bool is_character_file() const;
bool is_character_file(std::error_code& ec) const noexcept;

Parameters

ec
The output error code for the operation.

Return value

true if the referenced file is a character special file; otherwise, false. This function always returns false on Windows.

is_directory

Checks whether the referenced file is a directory.

bool is_directory() const;
bool is_directory(std::error_code& ec) const noexcept;

Parameters

ec
The output error code for the operation.

Return value

true if the referenced file is a directory; otherwise, false. Equivalent to calling filesystem::is_directory(status()).

is_fifo

Checks whether the referenced file is a named pipe (FIFO).

bool is_fifo() const;
bool is_fifo(std::error_code& ec) const noexcept;

Parameters

ec
The output error code for the operation.

Return value

true if the referenced file is a FIFO; otherwise, false. This function always returns false on Windows.

is_other

Checks whether the referenced file is an other file.

bool is_other() const;
bool is_other(std::error_code& ec) const noexcept;

Parameters

ec
The output error code for the operation.

Return value

true if the referenced file exists but isn't a regular file, directory, or symbolic link; otherwise, false. Equivalent to calling filesystem::is_other(status()).

is_regular_file

Checks whether the referenced file is a regular file.

bool is_regular_file() const;
bool is_regular_file(std::error_code& ec) const noexcept;

Parameters

ec
The output error code for the operation.

Return value

true if the referenced file is a regular file; otherwise, false. Equivalent to calling filesystem::is_regular_file(status()).

is_socket

Checks whether the referenced file is a socket.

bool is_socket() const;
bool is_socket(std::error_code& ec) const noexcept;

Parameters

ec
The output error code for the operation.

Return value

true if the referenced file is a socket; otherwise, false. This function always returns false on Windows.

is_symlink

Checks whether the referenced file is a symbolic link.

bool is_symlink() const;
bool is_symlink(std::error_code& ec) const noexcept;

Parameters

ec
The output error code for the operation.

Return value

true if the referenced file is a symbolic link; otherwise, false. Equivalent to calling filesystem::is_symlink(symlink_status()).

file_size

Gets the size, in bytes, of the referenced file.

uintmax_t file_size() const;
uintmax_t file_size(std::error_code& ec) const noexcept;

Parameters

ec
The output error code for the operation.

Return value

The size, in bytes, of the referenced file, as if by filesystem::file_size(path()). Uses cached data when it's available.

hard_link_count

Gets the number of hard links to the referenced file.

uintmax_t hard_link_count() const;
uintmax_t hard_link_count(std::error_code& ec) const noexcept;

Parameters

ec
The output error code for the operation.

Return value

The number of hard links to the referenced file, as if by filesystem::hard_link_count(path()). Uses cached data when it's available.

last_write_time

Gets the time of the last data modification of the referenced file.

file_time_type last_write_time() const;
file_time_type last_write_time(std::error_code& ec) const noexcept;

Parameters

ec
The output error code for the operation.

Return value

The time of the last data modification of the referenced file, as if by filesystem::last_write_time(path()). Uses cached data when it's available.

status

Gets the status of the referenced file, following symbolic links.

file_status status() const;
file_status status(std::error_code& ec) const noexcept;

Parameters

ec
The output error code for the operation.

Return value

The status of the referenced file, as if by filesystem::status(path()). Uses cached data when it's available.

symlink_status

Gets the status of the referenced file, without following symbolic links.

file_status symlink_status() const;
file_status symlink_status(std::error_code& ec) const noexcept;

Parameters

ec
The output error code for the operation.

Return value

The symlink status of the referenced file, as if by filesystem::symlink_status(path()). Uses cached data when it's available.

operator==

Checks whether two directory_entry objects are equal.

bool operator==(const directory_entry& right) const noexcept;

Parameters

right
The directory_entry to compare against.

Return value

Returns path() == right.path().

operator<=>

Performs a three-way comparison of two directory_entry objects.

std::strong_ordering operator<=>(const directory_entry& right) const noexcept; // C++20

Parameters

right
The directory_entry to compare against.

Return value

Returns path() <=> right.path().

Remarks

Available in C++20 and later. The compiler rewrites comparisons that use operator<, operator<=, operator>, or operator>= to use this operator. It rewrites comparisons that use operator!= to use operator==.

operator!=

Checks whether two directory_entry objects are unequal.

bool operator!=(const directory_entry& right) const noexcept; // C++17

Parameters

right
The directory_entry to compare against.

Return value

Returns !(*this == right).

Remarks

In C++17, this operator is an explicitly declared member function. In C++20 and later, an expression that uses operator!= is rewritten to use operator==.

operator<

Checks whether the directory_entry sorts before another directory_entry.

bool operator<(const directory_entry& right) const noexcept; // C++17

Parameters

right
The directory_entry to compare against.

Return value

Returns path() < right.path().

Remarks

In C++17, this operator is an explicitly declared member function. In C++20 and later, an expression that uses operator< is rewritten to use operator<=>.

operator<=

Checks whether the directory_entry sorts before or equal to another directory_entry.

bool operator<=(const directory_entry& right) const noexcept; // C++17

Parameters

right
The directory_entry to compare against.

Return value

Returns !(right < *this).

Remarks

In C++17, this operator is an explicitly declared member function. In C++20 and later, an expression that uses operator<= is rewritten to use operator<=>.

operator>

Checks whether the directory_entry sorts after another directory_entry.

bool operator>(const directory_entry& right) const noexcept; // C++17

Parameters

right
The directory_entry to compare against.

Return value

Returns right < *this.

Remarks

In C++17, this operator is an explicitly declared member function. In C++20 and later, an expression that uses operator> is rewritten to use operator<=>.

operator>=

Checks whether the directory_entry sorts after or equal to another directory_entry.

bool operator>=(const directory_entry& right) const noexcept; // C++17

Parameters

right
The directory_entry to compare against.

Return value

Returns !(*this < right).

Remarks

In C++17, this operator is an explicitly declared member function. In C++20 and later, an expression that uses operator>= is rewritten to use operator<=>.

See also

Header Files Reference
<filesystem>
File System Navigation (C++)