[fs.class.directory.iterator]

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

## 31.12 File systems [[filesystems]](filesystems#fs.class.directory.iterator)

### 31.12.11 Class directory_iterator [fs.class.directory.iterator]

#### [31.12.11.1](#general) General [[fs.class.directory.iterator.general]](fs.class.directory.iterator.general)

[1](#general-1)

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

An object of type directory_iterator provides an iterator for a
sequence of directory_entry elements representing the
path and any cached attribute values ([[fs.class.directory.entry]](fs.class.directory.entry "31.12.10 Class directory_­entry"))
for each file in a directory
or in an implementation-defined directory-like file type[.](#general-1.sentence-1)

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

For iteration into subdirectories, see class recursive_directory_iterator ([[fs.class.rec.dir.itr]](fs.class.rec.dir.itr "31.12.12 Class recursive_­directory_­iterator"))[.](#general-1.sentence-2)

â *end note*]

namespace std::filesystem {class 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.dir.itr.members]](#fs.dir.itr.members "31.12.11.2 Members"), member functions directory_iterator() noexcept; explicit directory_iterator(const path& p);
 directory_iterator(const path& p, directory_options options);
 directory_iterator(const path& p, error_code& ec);
 directory_iterator(const path& p, directory_options options,
 error_code& ec);
 directory_iterator(const directory_iterator& rhs);
 directory_iterator(directory_iterator&& rhs) noexcept; ~directory_iterator();

 directory_iterator& operator=(const directory_iterator& rhs);
 directory_iterator& operator=(directory_iterator&& rhs) noexcept; const directory_entry& operator*() const; const directory_entry* operator->() const;
 directory_iterator& operator++();
 directory_iterator& increment(error_code& ec); bool operator==(default_sentinel_t) const noexcept {return *this == 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#L16588)

directory_iterator meets the[*Cpp17InputIterator*](input.iterators#:Cpp17InputIterator "24.3.5.3 Input iterators [input.iterators]") requirements ([[input.iterators]](input.iterators "24.3.5.3 Input iterators"))[.](#general-2.sentence-1)

[3](#general-3)

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

If an iterator of type directory_iterator reports an error or
is advanced past the last directory element,
that iterator shall become equal to the end iterator
value[.](#general-3.sentence-1)

The directory_iterator default constructor shall
create an iterator equal to the end iterator value, and this shall be the only
valid iterator for the end condition[.](#general-3.sentence-2)

[4](#general-4)

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

The end iterator is not dereferenceable[.](#general-4.sentence-1)

[5](#general-5)

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

Two end iterators are always equal[.](#general-5.sentence-1)

An end iterator shall not be equal to a non-end
iterator[.](#general-5.sentence-2)

[6](#general-6)

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

The result of calling the path() member of the directory_entry object obtained by dereferencing a directory_iterator is a reference to a path object composed of the directory argument from which the iterator was
constructed with the filename of the directory entry appended as if by operator/=[.](#general-6.sentence-1)

[7](#general-7)

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

Directory iteration shall not yield directory entries for the current (dot)
and parent (dot-dot) directories[.](#general-7.sentence-1)

[8](#general-8)

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

The order of directory entries obtained by dereferencing successive
increments of a directory_iterator is unspecified[.](#general-8.sentence-1)

[9](#general-9)

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

Constructors and non-const directory_iterator member functions
store the values of any cached attributes ([[fs.class.directory.entry]](fs.class.directory.entry "31.12.10 Class directory_­entry"))
in the directory_entry element returned by operator*()[.](#general-9.sentence-1)

directory_iterator member functions shall not directly or indirectly call
any directory_entry refresh function[.](#general-9.sentence-2)

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

The exact mechanism for storing cached attribute values is not exposed to users[.](#general-9.sentence-3)

â *end note*]

[10](#general-10)

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

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

A path obtained by dereferencing a directory iterator might not actually exist;
it could be a symbolic link to a non-existent file[.](#general-10.sentence-1)

Recursively walking directory trees
for purposes of removing and renaming entries
might invalidate symbolic links that are being followed[.](#general-10.sentence-2)

â *end note*]

[11](#general-11)

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

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

If a file is removed from or added to a directory after the
construction of a directory_iterator for the directory, it is
unspecified whether or not subsequently incrementing the iterator will ever
result in an iterator referencing the removed or added directory entry[.](#general-11.sentence-1)

See
POSIX [readdir](http://pubs.opengroup.org/onlinepubs/9699919799/functions/readdir.html)[.](#general-11.sentence-2)

â *end note*]

#### [31.12.11.2](#fs.dir.itr.members) Members [[fs.dir.itr.members]](fs.dir.itr.members)

[ð](#lib:directory_iterator,constructor)

`directory_iterator() noexcept;
`

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

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

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

[ð](#lib:directory_iterator,constructor_)

`explicit directory_iterator(const path& p);
directory_iterator(const path& p, directory_options options);
directory_iterator(const path& p, error_code& ec);
directory_iterator(const path& p, directory_options options, error_code& ec);
`

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

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

*Effects*: For the directory that p resolves to, constructs an
iterator for the first element in a sequence of directory_entry elements representing the files in the directory, if any; otherwise the end
iterator[.](#fs.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.dir.itr.members-2.sentence-2)

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

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

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

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

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

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

To iterate over the current directory, use directory_iterator(".") rather than directory_iterator("")[.](#fs.dir.itr.members-4.sentence-1)

â *end note*]

[ð](#lib:directory_iterator,constructor__)

`directory_iterator(const directory_iterator& rhs);
directory_iterator(directory_iterator&& rhs) noexcept;
`

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

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

*Postconditions*: *this has the original value of rhs[.](#fs.dir.itr.members-5.sentence-1)

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

`directory_iterator& operator=(const directory_iterator& rhs);
directory_iterator& operator=(directory_iterator&& rhs) noexcept;
`

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

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

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

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

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

*Postconditions*: *this has the original value of rhs[.](#fs.dir.itr.members-7.sentence-1)

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

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

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

[ð](#lib:increment,directory_iterator)

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

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

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

*Effects*: As specified for the prefix increment operation of[Input iterators](input.iterators "24.3.5.3 Input iterators [input.iterators]")[.](#fs.dir.itr.members-9.sentence-1)

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

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

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

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

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

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

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

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

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

These functions enable range access for directory_iterator[.](#fs.dir.itr.nonmembers-1.sentence-1)

[ð](#lib:begin,directory_iterator)

`directory_iterator begin(directory_iterator iter) noexcept;
`

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

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

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

[ð](#lib:end,directory_iterator)

`directory_iterator end(directory_iterator) noexcept;
`

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

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

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