An object of type recursive_directory_iterator provides an iterator for a sequence of directory_entry elements representing the files in a directory and its sub-directories.
namespace std::filesystem {
class recursive_directory_iterator {
public:
using iterator_category = input_iterator_tag;
using value_type = directory_entry;
using difference_type = ptrdiff_t;
using pointer = const directory_entry*;
using reference = const directory_entry&;
// [rec.dir.itr.members], constructors and destructor
recursive_directory_iterator() noexcept;
explicit recursive_directory_iterator(const path& p);
recursive_directory_iterator(const path& p, directory_options options);
recursive_directory_iterator(const path& p, directory_options options,
error_code& ec) noexcept;
recursive_directory_iterator(const path& p, error_code& ec) noexcept;
recursive_directory_iterator(const recursive_directory_iterator& rhs);
recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept;
~recursive_directory_iterator();
// [rec.dir.itr.members], observers
directory_options options() const;
int depth() const;
bool recursion_pending() const;
const directory_entry& operator*() const;
const directory_entry* operator->() const;
// [rec.dir.itr.members], modifiers
recursive_directory_iterator&
operator=(const recursive_directory_iterator& rhs);
recursive_directory_iterator&
operator=(recursive_directory_iterator&& rhs) noexcept;
recursive_directory_iterator& operator++();
recursive_directory_iterator& increment(error_code& ec) noexcept;
void pop();
void pop(error_code& ec);
void disable_recursion_pending();
// other members as required by [input.iterators], input iterators
};
}
Calling options, depth, recursion_pending, pop or disable_recursion_pending on an iterator that is not dereferenceable results in undefined behavior.
The behavior of a recursive_directory_iterator is the same as a directory_iterator unless otherwise specified.
[ Note: If the directory structure being iterated over contains cycles then the end iterator may be unreachable. — end note ]
recursive_directory_iterator() noexcept;
Effects: Constructs the end iterator.
explicit recursive_directory_iterator(const path& p);
recursive_directory_iterator(const path& p, directory_options options);
recursive_directory_iterator(const path& p, directory_options options, error_code& ec) noexcept;
recursive_directory_iterator(const path& p, error_code& ec) noexcept;
Effects: Constructs a iterator representing the first entry in the directory p resolves to, if any; otherwise, the end iterator. However, if
(options & directory_options::skip_permission_denied) != directory_options::none
and construction encounters an error indicating that permission to access p is denied, constructs the end iterator and does not report an error.
Postconditions: options() == options for the signatures with a directory_options argument, otherwise options() == directory_options::none.
Throws: As specified in [fs.err.report].
[ Note: To iterate over the current directory, use recursive_directory_iterator(".") rather than recursive_directory_iterator(""). — end note ]
[ Note: By default, recursive_directory_iterator does not follow directory symlinks. To follow directory symlinks, specify options as directory_options::follow_directory_symlink — end note ]
recursive_directory_iterator(const recursive_directory_iterator& rhs);
Effects: Constructs an object of class recursive_directory_iterator.
recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept;
Effects: Constructs an object of class recursive_directory_iterator.
Postconditions: options(), depth(), and recursion_pending() return the values that rhs.options(), rhs.depth(), and rhs.recursion_pending(), respectively, had before the function call.
recursive_directory_iterator& operator=(const recursive_directory_iterator& rhs);
Effects: If *this and rhs are the same object, the member has no effect.
Returns: *this.
recursive_directory_iterator& operator=(recursive_directory_iterator&& rhs) noexcept;
Effects: If *this and rhs are the same object, the member has no effect.
Postconditions: options(), depth(), and recursion_pending() return the values that rhs.options(), rhs.depth(), and rhs.recursion_pending(), respectively, had before the function call.
Returns: *this.
directory_options options() const;
Returns: The value of the constructor options argument, if present, otherwise directory_options::none.
Throws: Nothing.
Returns: The current depth of the directory tree being traversed. [ Note: The initial directory is depth 0, its immediate subdirectories are depth 1, and so forth. — end note ]
Throws: Nothing.
bool recursion_pending() const;
Returns: true if disable_recursion_pending() has not been called subsequent to the prior construction or increment operation, otherwise false.
Throws: Nothing.
recursive_directory_iterator& operator++();
recursive_directory_iterator& increment(error_code& ec) noexcept;
Effects: As specified for the prefix increment operation of Input iterators ([input.iterators]), except that:
If there are no more entries at the current depth, then if depth()!= 0 iteration over the parent directory resumes; otherwise *this = recursive_directory_iterator().
Otherwise if
recursion_pending() && is_directory((*this)->status()) && (!is_symlink((*this)->symlink_status()) || (options() & directory_options::follow_directory_symlink) != directory_options::none)
then either directory (*this)->path() is recursively iterated into or, if
(options() & directory_options::skip_permission_denied) != directory_options::none
and an error occurs indicating that permission to access directory (*this)->path() is denied, then directory (*this)->path() is treated as an empty directory and no error is reported.
Returns: *this.
Throws: As specified in [fs.err.report].
void pop();
void pop(error_code& ec);
Effects: If depth() == 0, set *this to recursive_directory_iterator(). Otherwise, cease iteration of the directory currently being iterated over, and continue iteration over the parent directory.
Throws: As specified in [fs.err.report].
void disable_recursion_pending();
Postconditions: recursion_pending() == false.
[ Note: disable_recursion_pending() is used to prevent unwanted recursion into a directory. — end note ]
These functions enable use of recursive_directory_iterator with range-based for statements.
recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
Returns: iter.
recursive_directory_iterator end(const recursive_directory_iterator&) noexcept;
Returns: recursive_directory_iterator().