Class directory

Class directory_entry

boost::filesystem::directory_entry — Directory entry.

Synopsis

// In header: <boost/filesystem/directory.hpp>


class directory_entry {
public:

  // public member functions
  directory_entry() noexcept;
  explicit directory_entry(boost::filesystem::path const &);
  directory_entry(boost::filesystem::path const &, system::error_code &);
  directory_entry(boost::filesystem::path const &, file_status, 
                  file_status = file_status());
  directory_entry(directory_entry const &);
  directory_entry & operator=(directory_entry const &);
  directory_entry(directory_entry &&) noexcept;
  directory_entry & operator=(directory_entry &&) noexcept;
  void assign(boost::filesystem::path const &);
  void assign(boost::filesystem::path &&);
  void assign(boost::filesystem::path const &, system::error_code &);
  void assign(boost::filesystem::path &&, system::error_code &);
  void assign(boost::filesystem::path const &, file_status, 
              file_status = file_status());
  void assign(boost::filesystem::path &&, file_status, 
              file_status = file_status());
  void replace_filename(boost::filesystem::path const &);
  void replace_filename(boost::filesystem::path const &, system::error_code &);
  void replace_filename(boost::filesystem::path const &, file_status, 
                        file_status = file_status());
  boost::filesystem::path const & path() const noexcept;
  operator boost::filesystem::path const &() const noexcept;
  void refresh(system::error_code &) noexcept;
  void refresh();
  file_status status(system::error_code &) const noexcept;
  file_status status() const;
  file_status symlink_status(system::error_code &) const noexcept;
  file_status symlink_status() const;
  filesystem::file_type file_type(system::error_code &) const noexcept;
  filesystem::file_type file_type() const;
  filesystem::file_type symlink_file_type(system::error_code &) const noexcept;
  filesystem::file_type symlink_file_type() const;
  bool exists(system::error_code &) const noexcept;
  bool exists() const;
  bool is_regular_file(system::error_code &) const noexcept;
  bool is_regular_file() const;
  bool is_directory(system::error_code &) const noexcept;
  bool is_directory() const;
  bool is_symlink(system::error_code &) const noexcept;
  bool is_symlink() const;
  bool is_block_file(system::error_code &) const noexcept;
  bool is_block_file() const;
  bool is_character_file(system::error_code &) const noexcept;
  bool is_character_file() const;
  bool is_fifo(system::error_code &) const noexcept;
  bool is_fifo() const;
  bool is_socket(system::error_code &) const noexcept;
  bool is_socket() const;
  bool is_reparse_file(system::error_code &) const noexcept;
  bool is_reparse_file() const;
  bool is_other(system::error_code &) const noexcept;
  bool is_other() const;
  bool operator==(directory_entry const &) const;
  bool operator!=(directory_entry const &) const;
  bool operator<(directory_entry const &) const;
  bool operator<=(directory_entry const &) const;
  bool operator>(directory_entry const &) const;
  bool operator>=(directory_entry const &) const;
};

Description

A directory_entry object stores a path object, as well as some amount of cached information about the file identified by the path. Currently, the cached information includes a file_status object for non-symbolic link status and a file_status object for symbolic link status.

Note

Because status() on a pathname may be a relatively expensive operation, some operating systems provide status information as a byproduct of directory iteration. Caching such status information can result in significant time savings. Cached and non-cached results may differ in the presence of file system races.

As an example, actual cold-boot timing of iteration over a directory with 15,047 entries was six seconds for non-cached status queries versus one second for cached status queries. Windows XP, 3.0 GHz processor, with a moderately fast hard-drive. Similar speedups are expected on Linux and BSD-derived systems that provide status as a by-product of directory iteration.

The exact set of cached information may vary from one Boost.Filesystem version to another, and also between different operating systems and underlying file systems. Users' code must not rely on whether a certain piece of information is cached or not. This means that calling most observers and modifiers of directory_entry may or may not result in a filesystem query that may potentially fail. Information caching is exclusively a performance feature aimed at reducing the amount of such queries.

`directory_entry` public member functions

```
directory_entry() noexcept;
```
Default constructor.

Postconditions:

Expression Value

path().empty() true

status() file_status()

symlink_status() file_status()
```
explicit directory_entry(boost::filesystem::path const & p);
```
Constructs a directory_entry for the given path.
v3:

Equivalent to calling directory_entry(p, file_status(), file_status()).

Note

The cached file statuses will be updated when queried by the caller or by an explicit call to refresh().

v4:

Equivalent to calling directory_entry(p, ec), where ec is an instance of system::error_code. Throws filesystem_error with ec if the constructor fails.

Parameters:

p

Path to initialize the directory entry from.

directory_entry(boost::filesystem::path const & p, system::error_code & ec);

Constructs a directory_entry for the given path.

Effects:

Initializes the stored path from p and calls refresh() or refresh(ec). If the call fails, the stored path is replaced with an empty path.

	Note
	This overload is not available in v3.

Parameters:

`p`	Path to initialize the directory entry from.
`ec`	Error code returned in case of failure.

Postconditions:

path() == p if no error occurs, otherwise path().empty() == true.

directory_entry(boost::filesystem::path const & p, file_status st, 
                file_status symlink_st = file_status());

Constructs a directory_entry for the given path and file statuses.

	Note
	This overload is not available in v4.

Parameters:

`p`	Path to initialize the directory entry from.
`st`	File status, as if acquired from `status(p)`.
`symlink_st`	File symlink status, as if acquired from `symlink_status(p)`.

Postconditions:

Expression	Value
`path()`	`p`
`status()`	`st`
`symlink_status()`	`symlink_st`

```
directory_entry(directory_entry const & rhs);
```
Copy constructor.

Parameters:

rhs

Directory entry object to copy from.
```
directory_entry & operator=(directory_entry const & rhs);
```
Copy assignment operator.

Parameters:

rhs

Directory entry object to copy from.

Returns:

*this.
```
directory_entry(directory_entry && rhs) noexcept;
```
Move constructor.

Parameters:

rhs

Directory entry object to move from.
```
directory_entry & operator=(directory_entry && rhs) noexcept;
```
Move assignment operator.

Parameters:

rhs

Directory entry object to move from.

Returns:

*this.
```
void assign(boost::filesystem::path const & p);
```
Assigns a path and file statuses to the directory entry.
v3:

Equivalent to calling assign(p, file_status(), file_status()).

Note

The cached file statuses will be updated when queried by the caller or by an explicit call to refresh().

v4:

Equivalent to calling assign(p, ec), where ec is an instance of system::error_code. Throws filesystem_error with ec if the call fails.

Parameters:

p

Path to assign from.
```
void assign(boost::filesystem::path && p);
```
Assigns a path and file statuses to the directory entry.
v3:

Equivalent to calling assign(std::move(p), file_status(), file_status()).

Note

The cached file statuses will be updated when queried by the caller or by an explicit call to refresh().

v4:

Equivalent to calling assign(std::move(p), ec), where ec is an instance of system::error_code. Throws filesystem_error with ec if the call fails.

Parameters:

p

Path to assign from.
```
void assign(boost::filesystem::path const & p, system::error_code & ec);
```
Assigns a path to the directory entry.
Effects:

Assigns p to the stored path and calls refresh(ec). If an error occurs, the value of the cached data is unspecified.

Note

This overload is not available in v3.

Parameters:

p

Path to assign from.

ec

Error code returned in case of failure.
```
void assign(boost::filesystem::path && p, system::error_code & ec);
```
Assigns a path to the directory entry.
Effects:

Assigns p to the stored path and calls refresh(ec). If an error occurs, the value of the cached data is unspecified.

Note

This overload is not available in v3.

Parameters:

p

Path to assign from.

ec

Error code returned in case of failure.

void assign(boost::filesystem::path const & p, file_status st, 
            file_status symlink_st = file_status());

Assigns a path and file statuses to the directory entry.

Effects:

Assigns p, st and symlink_st to the directory entry.

	Note
	This overload is not available in v4.

Parameters:

`p`	Path to assign from.
`st`	File status, as if acquired from `status(p)`.
`symlink_st`	File symlink status, as if acquired from `symlink_status(p)`.

Postconditions:

Expression	Value
`path()`	`p`
`status()`	`st`
`symlink_status()`	`symlink_st`

void assign(boost::filesystem::path && p, file_status st, 
            file_status symlink_st = file_status());

Assigns a path and file statuses to the directory entry.

Effects:

Assigns p, st and symlink_st to the directory entry.

	Note
	This overload is not available in v4.

Parameters:

`p`	Path to assign from.
`st`	File status, as if acquired from `status(p)`.
`symlink_st`	File symlink status, as if acquired from `symlink_status(p)`.

Postconditions:

Expression	Value
`path()`	`p`
`status()`	`st`
`symlink_status()`	`symlink_st`

```
void replace_filename(boost::filesystem::path const & p);
```
Replaces the filename component of the path.
v3:

Equivalent to calling replace_filename(p, file_status(), file_status()).

Note

The cached file statuses will be updated when queried by the caller or by an explicit call to refresh().

v4:

Equivalent to calling replace_filename(p, ec), where ec is an instance of system::error_code. Throws filesystem_error with ec if the call fails.

Parameters:

p

Path to assign from.
```
void replace_filename(boost::filesystem::path const & p, 
                      system::error_code & ec);
```
Replaces the filename component of the path.
Effects:

On the stored path m_path, calls m_path.replace_filename(p) and then refresh(ec). If an error occurs, the value of the cached data is unspecified.

Note

This overload is not available in v3.

Parameters:

p

The replacement filename.

ec

Error code returned in case of failure.

void replace_filename(boost::filesystem::path const & p, file_status st, 
                      file_status symlink_st = file_status());

Replaces the filename component of the path.

Effects:

On the stored path m_path, calls m_path.replace_filename(p) and then stores st and symlink_st as the cached file statuses.

	Note
	This overload is not available in v4.

Parameters:

`p`	The replacement filename.
`st`	File status, as if acquired from `status(p)`.
`symlink_st`	File symlink status, as if acquired from `symlink_status(p)`.

Postconditions:

Expression	Value
`path()`	`m_path.replace_filename(p)`
`status()`	`st`
`symlink_status()`	`symlink_st`

```
boost::filesystem::path const & path() const noexcept;
```
Returns the path stored in the directory entry.

Returns:

The stored path.
```
operator boost::filesystem::path const &() const noexcept;
```
Returns the path stored in the directory entry.

Returns:

The stored path.
```
void refresh(system::error_code & ec) noexcept;
```
Updates any cached data by querying the filesystem.
Effects:

Updates any cached data by querying the filesystem about the file identified by the stored path. If an error occurs, the value of the cached data is unspecified.

Parameters:

ec

Error code returned in case of failure.
```
void refresh();
```
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
```
file_status status(system::error_code & ec) const noexcept;
```
Returns the file status.
Effects:

For the cached file status m_status, if !status_known(m_status), calls refresh(ec). Then returns m_status.

Note

The implementation does not query the filesystem after the file status has been cached. Filesystem changes after the file status has been cached will not be reflected in the result.

Parameters:

ec

Error code returned in case of failure.

Returns:

The file status.
```
file_status status() const;
```
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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

Returns the symlink file status.

Effects:

For the cached symlink file status m_symlink_status, if !status_known(m_symlink_status), calls refresh(ec). Then returns m_symlink_status.

	Note
	The implementation does not query the filesystem after the symlink file status has been cached. Filesystem changes after the symlink file status has been cached will not be reflected in the result.

Parameters:

`ec`	Error code returned in case of failure.

Returns:

The symlink file status.

```
file_status symlink_status() const;
```
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
```
filesystem::file_type file_type(system::error_code & ec) const noexcept;
```
Returns the file type.
Effects: Equivalent to status(ec).type() or status().type(), respectively.

Note

The implementation may be more efficient than calling status, if the information about the file type is cached, but permissions are not.

See Also: status.

Parameters:

ec

Error code returned in case of failure.

Returns:

The file type. If an error occurs, the overload taking ec returns file_type::status_error.
```
filesystem::file_type file_type() const;
```
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
```
filesystem::file_type 
symlink_file_type(system::error_code & ec) const noexcept;
```
Returns the symlink file type.
Effects: Equivalent to symlink_status(ec).type() or symlink_status().type(), respectively.

Note

The implementation may be more efficient than calling symlink_status, if the information about the symlink file type is cached, but permissions are not.

See Also: symlink_status.

Parameters:

ec

Error code returned in case of failure.

Returns:

The symlink file type. If an error occurs, the overload taking ec returns file_type::status_error.
```
filesystem::file_type symlink_file_type() const;
```
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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

Checks if the file exists.

Effects: Equivalent to exists(status(ec)) or exists(status()), respectively.

	Note
	The implementation may be more efficient than calling `status`, if the information about the file type is cached, but permissions are not.

See Also: status.

Parameters:

`ec`	Error code returned in case of failure.

Returns:

true if the file exists, according to the cached file type, otherwise false. If an error occurs, the overload taking ec returns false.

```
bool exists() const;
```
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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

Checks if the file is a regular file.

Effects: Equivalent to is_regular_file(status(ec)) or is_regular_file(status()), respectively.

	Note
	The implementation may be more efficient than calling `status`, if the information about the file type is cached, but permissions are not.

See Also: status.

Parameters:

`ec`	Error code returned in case of failure.

Returns:

true if the file is a regular file, according to the cached file type, otherwise false. If an error occurs, the overload taking ec returns false.

```
bool is_regular_file() const;
```
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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

Checks if the file is a directory.

Effects: Equivalent to is_directory(status(ec)) or is_directory(status()), respectively.

	Note
	The implementation may be more efficient than calling `status`, if the information about the file type is cached, but permissions are not.

See Also: status.

Parameters:

`ec`	Error code returned in case of failure.

Returns:

true if the file is a directory, according to the cached file type, otherwise false. If an error occurs, the overload taking ec returns false.

```
bool is_directory() const;
```
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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

Checks if the file is a symbolic link.

Effects: Equivalent to is_symlink(symlink_status(ec)) or `is_symlink(symlink_status()), respectively.

	Note
	The implementation may be more efficient than calling `symlink_status`, if the information about the symlink file type is cached, but permissions are not.

See Also: symlink_status.

Parameters:

`ec`	Error code returned in case of failure.

Returns:

true if the file is a symbolic link, according to the cached symlink file type, otherwise false. If an error occurs, the overload taking ec returns false.

```
bool is_symlink() const;
```
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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

Checks if the file is a block special file.

Effects: Equivalent to is_block_file(status(ec)) or is_block_file(status()), respectively.

	Note
	The implementation may be more efficient than calling `status`, if the information about the file type is cached, but permissions are not.

See Also: status.

Parameters:

`ec`	Error code returned in case of failure.

Returns:

true if the file is a block special file, according to the cached file type, otherwise false. If an error occurs, the overload taking ec returns false.

```
bool is_block_file() const;
```
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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

Checks if the file is a character special file.

Effects: Equivalent to is_character_file(status(ec)) or is_character_file(status()), respectively.

	Note
	The implementation may be more efficient than calling `status`, if the information about the file type is cached, but permissions are not.

See Also: status.

Parameters:

`ec`	Error code returned in case of failure.

Returns:

true if the file is a character special file, according to the cached file type, otherwise false. If an error occurs, the overload taking ec returns false.

```
bool is_character_file() const;
```
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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

Checks if the file is a FIFO or pipe file.

Effects: Equivalent to is_fifo(status(ec)) or is_fifo(status()), respectively.

	Note
	The implementation may be more efficient than calling `status`, if the information about the file type is cached, but permissions are not.

See Also: status.

Parameters:

`ec`	Error code returned in case of failure.

Returns:

true if the file is a FIFO or pipe file, according to the cached file type, otherwise false. If an error occurs, the overload taking ec returns false.

```
bool is_fifo() const;
```
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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

Checks if the file is a socket file.

Effects: Equivalent to is_socket(status(ec)) or is_socket(status()), respectively.

	Note
	The implementation may be more efficient than calling `status`, if the information about the file type is cached, but permissions are not.

See Also: status.

Parameters:

`ec`	Error code returned in case of failure.

Returns:

true if the file is a socket file, according to the cached file type, otherwise false. If an error occurs, the overload taking ec returns false.

```
bool is_socket() const;
```
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool is_reparse_file(system::error_code & ec) const noexcept;

Checks if the file is a reparse file.

Effects: Equivalent to is_reparse_file(symlink_status(ec)) or is_reparse_file(symlink_status()), respectively.

	Note
	The implementation may be more efficient than calling `symlink_status`, if the information about the symlink file type is cached, but permissions are not.

See Also: symlink_status.

Parameters:

`ec`	Error code returned in case of failure.

Returns:

true if the file is a reparse file, according to the cached symlink file type, otherwise false. If an error occurs, the overload taking ec returns false.

```
bool is_reparse_file() const;
```
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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

Checks if the file is of an unknown or other type.

Effects: Equivalent to is_other(status(ec)) or is_other(status()), respectively.

	Note
	The implementation may be more efficient than calling `status`, if the information about the file type is cached, but permissions are not.

See Also: status.

Parameters:

`ec`	Error code returned in case of failure.

Returns:

true if the file is of an unknown or other type, according to the cached file type, otherwise false. If an error occurs, the overload taking ec returns false.

```
bool is_other() const;
```
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
```
bool operator==(directory_entry const & rhs) const;
```
Compares two directory entries for equivalence.

Parameters:

rhs

Directory entry to compare with.

Returns:

this->path() == rhs.path().
```
bool operator!=(directory_entry const & rhs) const;
```
Compares two directory entries for inequivalence.

Parameters:

rhs

Directory entry to compare with.

Returns:

this->path() != rhs.path().
```
bool operator<(directory_entry const & rhs) const;
```
Compares two directory entries for less.

Parameters:

rhs

Directory entry to compare with.

Returns:

this->path() < rhs.path().
```
bool operator<=(directory_entry const & rhs) const;
```
Compares two directory entries for less or equal.

Parameters:

rhs

Directory entry to compare with.

Returns:

this->path() <= rhs.path().
```
bool operator>(directory_entry const & rhs) const;
```
Compares two directory entries for greater.

Parameters:

rhs

Directory entry to compare with.

Returns:

this->path() > rhs.path().
```
bool operator>=(directory_entry const & rhs) const;
```
Compares two directory entries for greater or equal.

Parameters:

rhs

Directory entry to compare with.

Returns:

this->path() >= rhs.path().

	Note
	The cached file statuses will be updated when queried by the caller or by an explicit call to `refresh()`.

Class directory_entry

Synopsis

Description

directory_entry public member functions

`directory_entry` public member functions