libstdc++
bits/fs_dir.h
Go to the documentation of this file.
1 // Filesystem directory utilities -*- C++ -*-
2 
3 // Copyright (C) 2014-2023 Free Software Foundation, Inc.
4 //
5 // This file is part of the GNU ISO C++ Library. This library is free
6 // software; you can redistribute it and/or modify it under the
7 // terms of the GNU General Public License as published by the
8 // Free Software Foundation; either version 3, or (at your option)
9 // any later version.
10 
11 // This library is distributed in the hope that it will be useful,
12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 // GNU General Public License for more details.
15 
16 // Under Section 7 of GPL version 3, you are granted additional
17 // permissions described in the GCC Runtime Library Exception, version
18 // 3.1, as published by the Free Software Foundation.
19 
20 // You should have received a copy of the GNU General Public License and
21 // a copy of the GCC Runtime Library Exception along with this program;
22 // see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
23 // <http://www.gnu.org/licenses/>.
24 
25 /** @file include/bits/fs_dir.h
26  * This is an internal header file, included by other library headers.
27  * Do not attempt to use it directly. @headername{filesystem}
28  */
29 
30 #ifndef _GLIBCXX_FS_DIR_H
31 #define _GLIBCXX_FS_DIR_H 1
32 
33 #if __cplusplus >= 201703L
34 # include <typeinfo>
35 # include <ext/concurrence.h>
36 # include <bits/unique_ptr.h>
37 # include <bits/shared_ptr.h>
38 
39 #if __cplusplus >= 202002L
40 # include <compare> // std::strong_ordering
41 # include <bits/iterator_concepts.h> // std::default_sentinel_t
42 #endif
43 
44 namespace std _GLIBCXX_VISIBILITY(default)
45 {
46 _GLIBCXX_BEGIN_NAMESPACE_VERSION
47 
48 namespace filesystem
49 {
50  /** @addtogroup filesystem
51  * @{
52  */
53 
54  /// Information about a file's type and permissions.
55  /**
56  * @headerfile filesystem
57  * @since C++17
58  */
60  {
61  public:
62  // constructors and destructor
63  file_status() noexcept : file_status(file_type::none) {}
64 
65  explicit
66  file_status(file_type __ft, perms __prms = perms::unknown) noexcept
67  : _M_type(__ft), _M_perms(__prms) { }
68 
69  file_status(const file_status&) noexcept = default;
70  file_status(file_status&&) noexcept = default;
71  ~file_status() = default;
72 
73  file_status& operator=(const file_status&) noexcept = default;
74  file_status& operator=(file_status&&) noexcept = default;
75 
76  // observers
77  file_type type() const noexcept { return _M_type; }
78  perms permissions() const noexcept { return _M_perms; }
79 
80  // modifiers
81  void type(file_type __ft) noexcept { _M_type = __ft; }
82  void permissions(perms __prms) noexcept { _M_perms = __prms; }
83 
84 #if __cpp_lib_three_way_comparison
85  friend bool
86  operator==(const file_status&, const file_status&) noexcept = default;
87 #endif
88 
89  private:
90  file_type _M_type;
91  perms _M_perms;
92  };
93 
94 _GLIBCXX_BEGIN_NAMESPACE_CXX11
95 
96  struct _Dir;
97  class directory_iterator;
99 
100  /// The value type used by directory iterators
101  /**
102  * @headerfile filesystem
103  * @since C++17
104  */
106  {
107  public:
108  // constructors and destructor
109  directory_entry() noexcept = default;
110  directory_entry(const directory_entry&) = default;
111  directory_entry(directory_entry&&) noexcept = default;
112 
113  explicit
115  : _M_path(__p)
116  { refresh(); }
117 
118  directory_entry(const filesystem::path& __p, error_code& __ec)
119  : _M_path(__p)
120  {
121  refresh(__ec);
122  if (__ec)
123  _M_path.clear();
124  }
125 
126  ~directory_entry() = default;
127 
128  // modifiers
129  directory_entry& operator=(const directory_entry&) = default;
130  directory_entry& operator=(directory_entry&&) noexcept = default;
131 
132  void
133  assign(const filesystem::path& __p)
134  {
135  _M_path = __p;
136  refresh();
137  }
138 
139  void
140  assign(const filesystem::path& __p, error_code& __ec)
141  {
142  _M_path = __p;
143  refresh(__ec);
144  }
145 
146  void
147  replace_filename(const filesystem::path& __p)
148  {
149  _M_path.replace_filename(__p);
150  refresh();
151  }
152 
153  void
154  replace_filename(const filesystem::path& __p, error_code& __ec)
155  {
156  _M_path.replace_filename(__p);
157  refresh(__ec);
158  }
159 
160  void
161  refresh()
162  { _M_type = symlink_status().type(); }
163 
164  void
165  refresh(error_code& __ec) noexcept
166  { _M_type = symlink_status(__ec).type(); }
167 
168  // observers
169  const filesystem::path& path() const noexcept { return _M_path; }
170  operator const filesystem::path& () const noexcept { return _M_path; }
171 
172  bool
173  exists() const
174  { return filesystem::exists(file_status{_M_file_type()}); }
175 
176  bool
177  exists(error_code& __ec) const noexcept
178  { return filesystem::exists(file_status{_M_file_type(__ec)}); }
179 
180  bool
181  is_block_file() const
182  { return _M_file_type() == file_type::block; }
183 
184  bool
185  is_block_file(error_code& __ec) const noexcept
186  { return _M_file_type(__ec) == file_type::block; }
187 
188  bool
189  is_character_file() const
190  { return _M_file_type() == file_type::character; }
191 
192  bool
193  is_character_file(error_code& __ec) const noexcept
194  { return _M_file_type(__ec) == file_type::character; }
195 
196  bool
197  is_directory() const
198  { return _M_file_type() == file_type::directory; }
199 
200  bool
201  is_directory(error_code& __ec) const noexcept
202  { return _M_file_type(__ec) == file_type::directory; }
203 
204  bool
205  is_fifo() const
206  { return _M_file_type() == file_type::fifo; }
207 
208  bool
209  is_fifo(error_code& __ec) const noexcept
210  { return _M_file_type(__ec) == file_type::fifo; }
211 
212  bool
213  is_other() const
214  { return filesystem::is_other(file_status{_M_file_type()}); }
215 
216  bool
217  is_other(error_code& __ec) const noexcept
218  { return filesystem::is_other(file_status{_M_file_type(__ec)}); }
219 
220  bool
221  is_regular_file() const
222  { return _M_file_type() == file_type::regular; }
223 
224  bool
225  is_regular_file(error_code& __ec) const noexcept
226  { return _M_file_type(__ec) == file_type::regular; }
227 
228  bool
229  is_socket() const
230  { return _M_file_type() == file_type::socket; }
231 
232  bool
233  is_socket(error_code& __ec) const noexcept
234  { return _M_file_type(__ec) == file_type::socket; }
235 
236  bool
237  is_symlink() const
238  {
239  if (_M_type != file_type::none)
240  return _M_type == file_type::symlink;
241  return symlink_status().type() == file_type::symlink;
242  }
243 
244  bool
245  is_symlink(error_code& __ec) const noexcept
246  {
247  if (_M_type != file_type::none)
248  return _M_type == file_type::symlink;
249  return symlink_status(__ec).type() == file_type::symlink;
250  }
251 
252  uintmax_t
253  file_size() const
254  { return filesystem::file_size(_M_path); }
255 
256  uintmax_t
257  file_size(error_code& __ec) const noexcept
258  { return filesystem::file_size(_M_path, __ec); }
259 
260  uintmax_t
261  hard_link_count() const
262  { return filesystem::hard_link_count(_M_path); }
263 
264  uintmax_t
265  hard_link_count(error_code& __ec) const noexcept
266  { return filesystem::hard_link_count(_M_path, __ec); }
267 
269  last_write_time() const
270  { return filesystem::last_write_time(_M_path); }
271 
272 
274  last_write_time(error_code& __ec) const noexcept
275  { return filesystem::last_write_time(_M_path, __ec); }
276 
278  status() const
279  { return filesystem::status(_M_path); }
280 
282  status(error_code& __ec) const noexcept
283  { return filesystem::status(_M_path, __ec); }
284 
286  symlink_status() const
287  { return filesystem::symlink_status(_M_path); }
288 
290  symlink_status(error_code& __ec) const noexcept
291  { return filesystem::symlink_status(_M_path, __ec); }
292 
293  bool
294  operator==(const directory_entry& __rhs) const noexcept
295  { return _M_path == __rhs._M_path; }
296 
297 #if __cpp_lib_three_way_comparison
298  strong_ordering
299  operator<=>(const directory_entry& __rhs) const noexcept
300  { return _M_path <=> __rhs._M_path; }
301 #else
302  bool
303  operator!=(const directory_entry& __rhs) const noexcept
304  { return _M_path != __rhs._M_path; }
305 
306  bool
307  operator< (const directory_entry& __rhs) const noexcept
308  { return _M_path < __rhs._M_path; }
309 
310  bool
311  operator<=(const directory_entry& __rhs) const noexcept
312  { return _M_path <= __rhs._M_path; }
313 
314  bool
315  operator> (const directory_entry& __rhs) const noexcept
316  { return _M_path > __rhs._M_path; }
317 
318  bool
319  operator>=(const directory_entry& __rhs) const noexcept
320  { return _M_path >= __rhs._M_path; }
321 #endif
322 
323  private:
324  friend struct _Dir;
325  friend class directory_iterator;
326  friend class recursive_directory_iterator;
327 
328  // _GLIBCXX_RESOLVE_LIB_DEFECTS
329  // 3171. LWG 2989 breaks directory_entry stream insertion
330  template<typename _CharT, typename _Traits>
332  operator<<(basic_ostream<_CharT, _Traits>& __os,
333  const directory_entry& __d)
334  { return __os << __d.path(); }
335 
337  : _M_path(__p), _M_type(__t)
338  { }
339 
340  // Equivalent to status().type() but uses cached value, if any.
341  file_type
342  _M_file_type() const
343  {
344  if (_M_type != file_type::none && _M_type != file_type::symlink)
345  return _M_type;
346  return status().type();
347  }
348 
349  // Equivalent to status(__ec).type() but uses cached value, if any.
350  file_type
351  _M_file_type(error_code& __ec) const noexcept
352  {
353  if (_M_type != file_type::none && _M_type != file_type::symlink)
354  {
355  __ec.clear();
356  return _M_type;
357  }
358  return status(__ec).type();
359  }
360 
361  filesystem::path _M_path;
362  file_type _M_type = file_type::none;
363  };
364 
365  /// @cond undocumented
366 
367  /// Proxy returned by post-increment on directory iterators.
368  /**
369  * @headerfile filesystem
370  * @since C++17
371  */
372  struct __directory_iterator_proxy
373  {
374  const directory_entry& operator*() const& noexcept { return _M_entry; }
375 
376  directory_entry operator*() && noexcept { return std::move(_M_entry); }
377 
378  private:
379  friend class directory_iterator;
380  friend class recursive_directory_iterator;
381 
382  explicit
383  __directory_iterator_proxy(const directory_entry& __e) : _M_entry(__e) { }
384 
385  directory_entry _M_entry;
386  };
387  /// @endcond
388 
389  /// Iterator type for traversing the entries in a single directory.
390  /**
391  * @headerfile filesystem
392  * @since C++17
393  */
395  {
396  public:
397  typedef directory_entry value_type;
398  typedef ptrdiff_t difference_type;
399  typedef const directory_entry* pointer;
400  typedef const directory_entry& reference;
402 
403  directory_iterator() = default;
404 
405  explicit
406  directory_iterator(const path& __p)
407  : directory_iterator(__p, directory_options::none, nullptr) { }
408 
409  directory_iterator(const path& __p, directory_options __options)
410  : directory_iterator(__p, __options, nullptr) { }
411 
412  directory_iterator(const path& __p, error_code& __ec)
413  : directory_iterator(__p, directory_options::none, __ec) { }
414 
415  directory_iterator(const path& __p, directory_options __options,
416  error_code& __ec)
417  : directory_iterator(__p, __options, &__ec) { }
418 
419  directory_iterator(const directory_iterator& __rhs) = default;
420 
421  directory_iterator(directory_iterator&& __rhs) noexcept = default;
422 
423  ~directory_iterator() = default;
424 
426  operator=(const directory_iterator& __rhs) = default;
427 
429  operator=(directory_iterator&& __rhs) noexcept = default;
430 
431  const directory_entry& operator*() const noexcept;
432  const directory_entry* operator->() const noexcept { return &**this; }
433  directory_iterator& operator++();
434  directory_iterator& increment(error_code& __ec);
435 
436  __directory_iterator_proxy operator++(int)
437  {
438  __directory_iterator_proxy __pr{**this};
439  ++*this;
440  return __pr;
441  }
442 
443  friend bool
444  operator==(const directory_iterator& __lhs,
445  const directory_iterator& __rhs) noexcept
446  {
447  return !__rhs._M_dir.owner_before(__lhs._M_dir)
448  && !__lhs._M_dir.owner_before(__rhs._M_dir);
449  }
450 
451 #if __cplusplus >= 202002L
452  // _GLIBCXX_RESOLVE_LIB_DEFECTS
453  // 3719. Directory iterators should be usable with default sentinel
454  bool operator==(default_sentinel_t) const noexcept
455  { return !_M_dir; }
456 #endif
457 
458 #if __cpp_impl_three_way_comparison < 201907L
459  friend bool
460  operator!=(const directory_iterator& __lhs,
461  const directory_iterator& __rhs) noexcept
462  { return !(__lhs == __rhs); }
463 #endif
464 
465  private:
467 
468  friend class recursive_directory_iterator;
469 
470  std::__shared_ptr<_Dir> _M_dir;
471  };
472 
473  /** @relates std::filesystem::directory_iterator
474  * @headerfile filesystem
475  * @since C++17
476  * @{
477  */
478 
479  /** @brief Enable range-based `for` using directory_iterator.
480  *
481  * e.g. `for (auto& entry : std::filesystem::directory_iterator(".")) ...`
482  */
483  inline directory_iterator
484  begin(directory_iterator __iter) noexcept
485  { return __iter; }
486 
487  /// Return a past-the-end directory_iterator
488  inline directory_iterator
490  { return directory_iterator(); }
491  /// @}
492 
493  /// Iterator type for recursively traversing a directory hierarchy.
494  /**
495  * @headerfile filesystem
496  * @since C++17
497  */
499  {
500  public:
501  typedef directory_entry value_type;
502  typedef ptrdiff_t difference_type;
503  typedef const directory_entry* pointer;
504  typedef const directory_entry& reference;
506 
507  recursive_directory_iterator() = default;
508 
509  explicit
511  : recursive_directory_iterator(__p, directory_options::none, nullptr) { }
512 
514  : recursive_directory_iterator(__p, __options, nullptr) { }
515 
517  error_code& __ec)
518  : recursive_directory_iterator(__p, __options, &__ec) { }
519 
520  recursive_directory_iterator(const path& __p, error_code& __ec)
521  : recursive_directory_iterator(__p, directory_options::none, &__ec) { }
522 
524  const recursive_directory_iterator&) = default;
525 
527 
529 
530  // observers
531  directory_options options() const noexcept;
532  int depth() const noexcept;
533  bool recursion_pending() const noexcept;
534 
535  const directory_entry& operator*() const noexcept;
536  const directory_entry* operator->() const noexcept { return &**this; }
537 
538  // modifiers
540  operator=(const recursive_directory_iterator& __rhs) noexcept;
542  operator=(recursive_directory_iterator&& __rhs) noexcept;
543 
544  recursive_directory_iterator& operator++();
545  recursive_directory_iterator& increment(error_code& __ec);
546 
547  __directory_iterator_proxy operator++(int)
548  {
549  __directory_iterator_proxy __pr{**this};
550  ++*this;
551  return __pr;
552  }
553 
554  void pop();
555  void pop(error_code&);
556 
557  void disable_recursion_pending() noexcept;
558 
559  friend bool
560  operator==(const recursive_directory_iterator& __lhs,
561  const recursive_directory_iterator& __rhs) noexcept
562  {
563  return !__rhs._M_dirs.owner_before(__lhs._M_dirs)
564  && !__lhs._M_dirs.owner_before(__rhs._M_dirs);
565  }
566 
567 #if __cplusplus >= 202002L
568  // _GLIBCXX_RESOLVE_LIB_DEFECTS
569  // 3719. Directory iterators should be usable with default sentinel
570  bool operator==(default_sentinel_t) const noexcept
571  { return !_M_dirs; }
572 #endif
573 
574 #if __cpp_impl_three_way_comparison < 201907L
575  friend bool
576  operator!=(const recursive_directory_iterator& __lhs,
577  const recursive_directory_iterator& __rhs) noexcept
578  { return !(__lhs == __rhs); }
579 #endif
580 
581  private:
583 
584  struct _Dir_stack;
585  std::__shared_ptr<_Dir_stack> _M_dirs;
586 
588  __erase(error_code* = nullptr);
589 
590  friend uintmax_t
591  filesystem::remove_all(const path&, error_code&);
592  friend uintmax_t
593  filesystem::remove_all(const path&);
594  };
595 
596  /** @relates std::filesystem::directory_iterator
597  * @headerfile filesystem
598  * @since C++17
599  * @{
600  */
601 
602  /** @brief Enable range-based `for` using recursive_directory_iterator.
603  *
604  * e.g. `for (auto& entry : recursive_directory_iterator(".")) ...`
605  */
608  { return __iter; }
609 
610  /// Return a past-the-end recursive_directory_iterator
613  { return recursive_directory_iterator(); }
614  /// @}
615 
616 _GLIBCXX_END_NAMESPACE_CXX11
617 
618  /// @} group filesystem
619 } // namespace filesystem
620 
621  // Use explicit instantiations of these types. Any inconsistency in the
622  // value of __default_lock_policy between code including this header and
623  // the library will cause a linker error.
624  extern template class
625  __shared_ptr<filesystem::_Dir>;
626  extern template class
627  __shared_ptr<filesystem::recursive_directory_iterator::_Dir_stack>;
628 
629 _GLIBCXX_END_NAMESPACE_VERSION
630 } // namespace std
631 
632 #endif // C++17
633 
634 #endif // _GLIBCXX_FS_DIR_H
Template class basic_ostream.
Definition: iosfwd:88
Marking input iterators.
recursive_directory_iterator end(recursive_directory_iterator) noexcept
Return a past-the-end recursive_directory_iterator.
Definition: bits/fs_dir.h:612
directory_iterator end(directory_iterator) noexcept
Return a past-the-end directory_iterator.
Definition: bits/fs_dir.h:489
directory_iterator begin(directory_iterator __iter) noexcept
Enable range-based for using directory_iterator.
Definition: bits/fs_dir.h:484
constexpr complex< _Tp > operator*(const complex< _Tp > &__x, const complex< _Tp > &__y)
Return new complex value x times y.
Definition: complex:395
A filesystem path.
Definition: bits/fs_path.h:293
ISO C++ entities toplevel namespace is std.
perms
Bitmask type representing file access permissions.
Definition: bits/fs_fwd.h:140
The value type used by directory iterators.
Definition: bits/fs_dir.h:105
chrono::time_point represents a point in time as measured by a clock
Definition: chrono.h:66
recursive_directory_iterator begin(recursive_directory_iterator __iter) noexcept
Enable range-based for using recursive_directory_iterator.
Definition: bits/fs_dir.h:607
file_type
Enumerated type representing the type of a file.
Definition: bits/fs_fwd.h:78
Iterator type for recursively traversing a directory hierarchy.
Definition: bits/fs_dir.h:498
Information about a file&#39;s type and permissions.
Definition: bits/fs_dir.h:59
constexpr std::remove_reference< _Tp >::type && move(_Tp &&__t) noexcept
Convert a value to an rvalue.
Definition: move.h:97
directory_options
Bitmask type controlling directory iteration.
Definition: bits/fs_fwd.h:263
Iterator type for traversing the entries in a single directory.
Definition: bits/fs_dir.h:394