Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
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
| Constructor | Description |
|---|---|
directory_entry |
Constructs a directory_entry. |
Member functions
| Member function | Description |
|---|---|
assign |
Replaces the stored path and refreshes the cached attributes. |
exists |
Checks whether the entry refers to an existing file. |
file_size |
Gets the size, in bytes, of the referenced file. |
hard_link_count |
Gets the number of hard links to the referenced file. |
is_block_file |
Checks whether the referenced file is a block special file. |
is_character_file |
Checks whether the referenced file is a character special file. |
is_directory |
Checks whether the referenced file is a directory. |
is_fifo |
Checks whether the referenced file is a named pipe (FIFO). |
is_other |
Checks whether the referenced file is an other file. |
is_regular_file |
Checks whether the referenced file is a regular file. |
is_socket |
Checks whether the referenced file is a socket. |
is_symlink |
Checks whether the referenced file is a symbolic link. |
last_write_time |
Gets the time of the last data modification of the referenced file. |
path |
Returns the stored path. |
refresh |
Refreshes the cached file attributes. |
replace_filename |
Replaces the filename of the stored path and refreshes the cached attributes. |
status |
Gets the status of the referenced file, following symbolic links. |
symlink_status |
Gets the status of the referenced file, without following symbolic links. |
Operators
| Operator | Description |
|---|---|
operator= |
Assigns to the directory_entry. |
operator const path& |
Returns the stored path. |
operator== |
Checks whether two directory_entry objects are equal. |
operator<=> |
Performs a three-way comparison of two directory_entry objects. (C++20) |
operator!= |
Checks whether two directory_entry objects are unequal. An explicit member in C++17; supported through rewritten comparisons in C++20 and later. |
operator< |
Checks whether the directory_entry sorts before another directory_entry. An explicit member in C++17; supported through rewritten comparisons in C++20 and later. |
operator<= |
Checks whether the directory_entry sorts before or equal to another directory_entry. An explicit member in C++17; supported through rewritten comparisons in C++20 and later. |
operator> |
Checks whether the directory_entry sorts after another directory_entry. An explicit member in C++17; supported through rewritten comparisons in C++20 and later. |
operator>= |
Checks whether the directory_entry sorts after or equal to another directory_entry. An explicit member in C++17; supported through rewritten comparisons in C++20 and later. |
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++)