[fs.class.rec.dir.itr]

# 31 Input/output library [[input.output]](./#input.output)

## 31.12 File systems [[filesystems]](filesystems#fs.class.rec.dir.itr)

### 31.12.12 Class recursive_directory_iterator [fs.class.rec.dir.itr]

#### [31.12.12.1](#general) General [[fs.class.rec.dir.itr.general]](fs.class.rec.dir.itr.general)

[1](#general-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16779)

An object of type recursive_directory_iterator provides an iterator for
a sequence of directory_entry elements representing the files in a
directory or in an implementation-defined directory-like file
type, and its subdirectories[.](#general-1.sentence-1)

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&; // [[fs.rec.dir.itr.members]](#fs.rec.dir.itr.members "31.12.12.2 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);
 recursive_directory_iterator(const path& p, error_code& ec);
 recursive_directory_iterator(const recursive_directory_iterator& rhs);
 recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept; ~recursive_directory_iterator(); // [[fs.rec.dir.itr.members]](#fs.rec.dir.itr.members "31.12.12.2 Members"), observers directory_options options() const; int depth() const; bool recursion_pending() const; const directory_entry& operator*() const; const directory_entry* operator->() const; // [[fs.rec.dir.itr.members]](#fs.rec.dir.itr.members "31.12.12.2 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); void pop(); void pop(error_code& ec); void disable_recursion_pending(); bool operator==(default_sentinel_t) const noexcept {return *this == recursive_directory_iterator(); }// other members as required by [[input.iterators]](input.iterators "24.3.5.3 Input iterators"), input iterators};}

[2](#general-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16836)

Calling options, depth, recursion_pending,pop or disable_recursion_pending on an iterator that is not dereferenceable results in undefined behavior[.](#general-2.sentence-1)

[3](#general-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16841)

The behavior of a recursive_directory_iterator is the same
as a directory_iterator unless otherwise specified[.](#general-3.sentence-1)

[4](#general-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16845)

[*Note [1](#general-note-1)*:

If the directory structure being iterated over contains cycles
then it is possible that the end iterator is unreachable[.](#general-4.sentence-1)

â *end note*]

#### [31.12.12.2](#fs.rec.dir.itr.members) Members [[fs.rec.dir.itr.members]](fs.rec.dir.itr.members)

[ð](#lib:recursive_directory_iterator,constructor)

`recursive_directory_iterator() noexcept;
`

[1](#fs.rec.dir.itr.members-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16859)

*Effects*: Constructs the end iterator[.](#fs.rec.dir.itr.members-1.sentence-1)

[ð](#lib:recursive_directory_iterator,constructor_)

`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);
recursive_directory_iterator(const path& p, error_code& ec);
`

[2](#fs.rec.dir.itr.members-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16873)

*Effects*: Constructs an iterator representing the first
entry in the directory to which p resolves, if any; otherwise, the end iterator[.](#fs.rec.dir.itr.members-2.sentence-1)

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[.](#fs.rec.dir.itr.members-2.sentence-2)

[3](#fs.rec.dir.itr.members-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16885)

*Postconditions*: options() == options for the signatures with adirectory_options argument, otherwise options() == directory_options​::​none[.](#fs.rec.dir.itr.members-3.sentence-1)

[4](#fs.rec.dir.itr.members-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16890)

*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.rec.dir.itr.members-4.sentence-1)

[5](#fs.rec.dir.itr.members-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16894)

[*Note [1](#fs.rec.dir.itr.members-note-1)*:

Use recursive_directory_iterator(".") rather than recursive_directory_iterator("") to iterate over the current directory[.](#fs.rec.dir.itr.members-5.sentence-1)

â *end note*]

[6](#fs.rec.dir.itr.members-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16901)

[*Note [2](#fs.rec.dir.itr.members-note-2)*:

By default, recursive_directory_iterator does not
follow directory symlinks[.](#fs.rec.dir.itr.members-6.sentence-1)

To follow directory symlinks, specify options asdirectory_options​::​follow_directory_symlink[.](#fs.rec.dir.itr.members-6.sentence-2)

â *end note*]

[ð](#lib:recursive_directory_iterator,constructor__)

`recursive_directory_iterator(const recursive_directory_iterator& rhs);
`

[7](#fs.rec.dir.itr.members-7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16915)

*Postconditions*: 

- [(7.1)](#fs.rec.dir.itr.members-7.1)

options() == rhs.options()

- [(7.2)](#fs.rec.dir.itr.members-7.2)

depth() == rhs.depth()

- [(7.3)](#fs.rec.dir.itr.members-7.3)

recursion_pending() == rhs.recursion_pending()

[ð](#lib:recursive_directory_iterator,constructor___)

`recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept;
`

[8](#fs.rec.dir.itr.members-8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16930)

*Postconditions*: options(), depth(),
 and recursion_pending() have the values that rhs.options(), rhs.depth(), and rhs.recursion_pending(), respectively, had before the function call[.](#fs.rec.dir.itr.members-8.sentence-1)

[ð](#lib:operator=,recursive_directory_iterator)

`recursive_directory_iterator& operator=(const recursive_directory_iterator& rhs);
`

[9](#fs.rec.dir.itr.members-9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16944)

*Effects*: If *this and rhs are the same
 object, the member has no effect[.](#fs.rec.dir.itr.members-9.sentence-1)

[10](#fs.rec.dir.itr.members-10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16949)

*Postconditions*: 

- [(10.1)](#fs.rec.dir.itr.members-10.1)

options() == rhs.options()

- [(10.2)](#fs.rec.dir.itr.members-10.2)

depth() == rhs.depth()

- [(10.3)](#fs.rec.dir.itr.members-10.3)

recursion_pending() == rhs.recursion_pending()

[11](#fs.rec.dir.itr.members-11)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16957)

*Returns*: *this[.](#fs.rec.dir.itr.members-11.sentence-1)

[ð](#lib:operator=,recursive_directory_iterator_)

`recursive_directory_iterator& operator=(recursive_directory_iterator&& rhs) noexcept;
`

[12](#fs.rec.dir.itr.members-12)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16968)

*Effects*: If *this and rhs are the same
object, the member has no effect[.](#fs.rec.dir.itr.members-12.sentence-1)

[13](#fs.rec.dir.itr.members-13)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16973)

*Postconditions*: options(), depth(),
and recursion_pending() have the values that rhs.options(),rhs.depth(), and rhs.recursion_pending(), respectively, had before the function call[.](#fs.rec.dir.itr.members-13.sentence-1)

[14](#fs.rec.dir.itr.members-14)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16979)

*Returns*: *this[.](#fs.rec.dir.itr.members-14.sentence-1)

[ð](#lib:options,recursive_directory_iterator)

`directory_options options() const;
`

[15](#fs.rec.dir.itr.members-15)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16990)

*Returns*: The value of the argument passed to the constructor for theoptions parameter, if present, otherwisedirectory_options​::​none[.](#fs.rec.dir.itr.members-15.sentence-1)

[16](#fs.rec.dir.itr.members-16)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16996)

*Throws*: Nothing[.](#fs.rec.dir.itr.members-16.sentence-1)

[ð](#lib:depth,recursive_directory_iterator)

`int depth() const;
`

[17](#fs.rec.dir.itr.members-17)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17007)

*Returns*: The current depth of the directory tree being traversed[.](#fs.rec.dir.itr.members-17.sentence-1)

[*Note [3](#fs.rec.dir.itr.members-note-3)*:

The initial directory is depth 0, its immediate subdirectories are depth 1,
 and so forth[.](#fs.rec.dir.itr.members-17.sentence-2)

â *end note*]

[18](#fs.rec.dir.itr.members-18)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17015)

*Throws*: Nothing[.](#fs.rec.dir.itr.members-18.sentence-1)

[ð](#lib:recursion_pending,recursive_directory_iterator)

`bool recursion_pending() const;
`

[19](#fs.rec.dir.itr.members-19)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17026)

*Returns*: true if disable_recursion_pending() has not been called subsequent to the prior construction or increment
 operation, otherwise false[.](#fs.rec.dir.itr.members-19.sentence-1)

[20](#fs.rec.dir.itr.members-20)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17032)

*Throws*: Nothing[.](#fs.rec.dir.itr.members-20.sentence-1)

[ð](#lib:increment,recursive_directory_iterator)

`recursive_directory_iterator& operator++();
recursive_directory_iterator& increment(error_code& ec);
`

[21](#fs.rec.dir.itr.members-21)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17045)

*Effects*: As specified for the prefix increment operation of[Input iterators](input.iterators "24.3.5.3 Input iterators [input.iterators]"),
except that:

- [(21.1)](#fs.rec.dir.itr.members-21.1)

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().

- [(21.2)](#fs.rec.dir.itr.members-21.2)

Otherwise ifrecursion_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.

[22](#fs.rec.dir.itr.members-22)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17070)

*Returns*: *this[.](#fs.rec.dir.itr.members-22.sentence-1)

[23](#fs.rec.dir.itr.members-23)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17074)

*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.rec.dir.itr.members-23.sentence-1)

[ð](#lib:pop,recursive_directory_iterator)

`void pop();
void pop(error_code& ec);
`

[24](#fs.rec.dir.itr.members-24)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17086)

*Effects*: If depth() == 0, set *this to recursive_directory_iterator()[.](#fs.rec.dir.itr.members-24.sentence-1)

Otherwise, cease iteration of the directory currently being
 iterated over, and continue iteration over the parent directory[.](#fs.rec.dir.itr.members-24.sentence-2)

[25](#fs.rec.dir.itr.members-25)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17092)

*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.rec.dir.itr.members-25.sentence-1)

[26](#fs.rec.dir.itr.members-26)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17097)

*Remarks*: Any copies of the previous value of *this are no longer required
to be dereferenceable nor to be in the domain of ==[.](#fs.rec.dir.itr.members-26.sentence-1)

[ð](#lib:disable_recursion_pending,recursive_directory_iterator)

`void disable_recursion_pending();
`

[27](#fs.rec.dir.itr.members-27)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17109)

*Postconditions*: recursion_pending() == false[.](#fs.rec.dir.itr.members-27.sentence-1)

[28](#fs.rec.dir.itr.members-28)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17113)

[*Note [4](#fs.rec.dir.itr.members-note-4)*:

disable_recursion_pending() is used to prevent
 unwanted recursion into a directory[.](#fs.rec.dir.itr.members-28.sentence-1)

â *end note*]

#### [31.12.12.3](#fs.rec.dir.itr.nonmembers) Non-member functions [[fs.rec.dir.itr.nonmembers]](fs.rec.dir.itr.nonmembers)

[1](#fs.rec.dir.itr.nonmembers-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17122)

These functions enable use of recursive_directory_iterator with range-based for statements[.](#fs.rec.dir.itr.nonmembers-1.sentence-1)

[ð](#lib:begin,recursive_directory_iterator)

`recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
`

[2](#fs.rec.dir.itr.nonmembers-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17132)

*Returns*: iter[.](#fs.rec.dir.itr.nonmembers-2.sentence-1)

[ð](#lib:end,recursive_directory_iterator)

`recursive_directory_iterator end(recursive_directory_iterator) noexcept;
`

[3](#fs.rec.dir.itr.nonmembers-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17143)

*Returns*: recursive_directory_iterator()[.](#fs.rec.dir.itr.nonmembers-3.sentence-1)
