# 标准库头文件 <filesystem>

< cpp‎ | header

此头文件是文件系统支持库的一部分。

### 包含
<compare> (C++20) | 三路比较运算符支持
定义于命名空间 `std::filesystem`
### 类
path (C++17) | 表示路径 (类)
filesystem_error (C++17) | 文件系统错误时抛出的异常 (类)
directory_entry (C++17) | 目录条目 (类)
directory_iterator (C++17) | 指向目录内容的迭代器 (类)
recursive_directory_iterator (C++17) | 指向一个目录及其子目录的内容的迭代器 (类)
file_status (C++17) | 表示文件类型及权限 (类)
space_info (C++17) | 关于文件系统上空闲及可用空间的信息 (类)
file_type (C++17) | 文件的类型 (枚举)
perms (C++17) | 标识文件系统权限 (枚举)
perm_options (C++17) | 指定权限操作的语义 (枚举)
copy_options (C++17) | 指定复制操作的语义 (枚举)
directory_options (C++17) | 用于迭代目录内容的选项 (枚举)
file_time_type (C++17) | 表示文件时间值 (typedef)
### 函数
u8path (C++17)(C++20 中弃用) | 从 UTF-8 编码的源创建 `path` (函数)
absolute (C++17) | 组成一个绝对路径 (函数)
canonical weakly_canonical (C++17) | 组成一个规范路径 (函数)
relative proximate (C++17) | 组成一个相对路径 (函数)
copy (C++17) | 复制文件或目录 (函数)
copy_file (C++17) | 复制文件内容 (函数)
copy_symlink (C++17) | 复制一个符号链接 (函数)
create_directory create_directories (C++17)(C++17) | 创建新目录 (函数)
create_hard_link (C++17) | 创建一个硬链接 (函数)
create_symlink create_directory_symlink (C++17)(C++17) | 创建一个符号链接 (函数)
current_path (C++17) | 返回或设置当前工作目录 (函数)
exists (C++17) | 检查路径是否指代既存的文件系统对象 (函数)
equivalent (C++17) | 检查两个路径是否指代同一文件系统对象 (函数)
file_size (C++17) | 返回文件的大小 (函数)
hard_link_count (C++17) | 返回指代特定文件的硬链接数 (函数)
last_write_time (C++17) | 获取或设置最近一次数据修改的时间 (函数)
permissions (C++17) | 修改文件访问权限 (函数)
read_symlink (C++17) | 获得符号链接的目标 (函数)
remove remove_all (C++17)(C++17) | 移除一个文件或空目录 移除一个文件或递归地移除一个目录及其所有内容 (函数)
rename (C++17) | 移动或重命名一个文件或目录 (函数)
resize_file (C++17) | 以截断或填充零更改一个常规文件的大小 (函数)
space (C++17) | 确定文件系统上的可用空闲空间 (函数)
status symlink_status (C++17)(C++17) | 确定文件属性 确定文件属性，检查符号链接目标 (函数)
temp_directory_path (C++17) | 返回一个适用于临时文件的目录 (函数)
##### 文件类型
is_block_file (C++17) | 检查给定的路径是否表示块设备 (函数)
is_character_file (C++17) | 检查给定的路径是否表示字符设备 (函数)
is_directory (C++17) | 检查给定的路径是否表示一个目录 (函数)
is_empty (C++17) | 检查给定的路径是否表示一个空文件或空目录 (函数)
is_fifo (C++17) | 检查给定的路径是否表示一个命名管道 (函数)
is_other (C++17) | 检查参数是否表示一个其他文件 (函数)
is_regular_file (C++17) | 检查参数是否表示一个常规文件 (函数)
is_socket (C++17) | 检查参数是否表示一个具名 IPC 套接字 (函数)
is_symlink (C++17) | 检查参数是否表示一个符号链接 (函数)
status_known (C++17) | 检查文件状态是否已知 (函数)

### 概要

    #include <compare>

    namespace std::filesystem {
      // 路径
      class path;

      // 路径非成员函数
      void swap(path& lhs, path& rhs) noexcept;
      size_t hash_value(const path& p) noexcept;

      // 文件系统错误
      class filesystem_error;

      // 目录条目
      class directory_entry;

      // 目录迭代器
      class directory_iterator;

      // 目录迭代器的范围访问
      directory_iterator begin(directory_iterator iter) noexcept;
      directory_iterator end(directory_iterator) noexcept;

      // 递归目录迭代器
      class recursive_directory_iterator;

      // 递归目录迭代器的范围访问
      recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
      recursive_directory_iterator end(recursive_directory_iterator) noexcept;

      // 文件状况
      class file_status;

      struct space_info {
        uintmax_t capacity;
        uintmax_t free;
        uintmax_t available;

        friend bool operator==(const space_info&, const space_info&) = default;
      };

      // 枚举
      enum class file_type;
      enum class perms;
      enum class perm_options;
      enum class copy_options;
      enum class directory_options;

      using file_time_type = chrono::time_point<chrono::file_clock>;

      // 文件系统操作
      path absolute(const path& p);
      path absolute(const path& p, error_code& ec);

      path canonical(const path& p);
      path canonical(const path& p, error_code& ec);

      void copy(const path& from, const path& to);
      void copy(const path& from, const path& to, error_code& ec);
      void copy(const path& from, const path& to, copy_options options);
      void copy(const path& from, const path& to, copy_options options,
                error_code& ec);

      bool copy_file(const path& from, const path& to);
      bool copy_file(const path& from, const path& to, error_code& ec);
      bool copy_file(const path& from, const path& to, copy_options option);
      bool copy_file(const path& from, const path& to, copy_options option,
                     error_code& ec);

      void copy_symlink(const path& existing_symlink, const path& new_symlink);
      void copy_symlink(const path& existing_symlink, const path& new_symlink,
                        error_code& ec) noexcept;

      bool create_directories(const path& p);
      bool create_directories(const path& p, error_code& ec);

      bool create_directory(const path& p);
      bool create_directory(const path& p, error_code& ec) noexcept;

      bool create_directory(const path& p, const path& attributes);
      bool create_directory(const path& p, const path& attributes,
                            error_code& ec) noexcept;

      void create_directory_symlink(const path& to, const path& new_symlink);
      void create_directory_symlink(const path& to, const path& new_symlink,
                                    error_code& ec) noexcept;

      void create_hard_link(const path& to, const path& new_hard_link);
      void create_hard_link(const path& to, const path& new_hard_link,
                            error_code& ec) noexcept;

      void create_symlink(const path& to, const path& new_symlink);
      void create_symlink(const path& to, const path& new_symlink,
                          error_code& ec) noexcept;

      path current_path();
      path current_path(error_code& ec);
      void current_path(const path& p);
      void current_path(const path& p, error_code& ec) noexcept;

      bool equivalent(const path& p1, const path& p2);
      bool equivalent(const path& p1, const path& p2, error_code& ec) noexcept;

      bool exists(file_status s) noexcept;
      bool exists(const path& p);
      bool exists(const path& p, error_code& ec) noexcept;

      uintmax_t file_size(const path& p);
      uintmax_t file_size(const path& p, error_code& ec) noexcept;

      uintmax_t hard_link_count(const path& p);
      uintmax_t hard_link_count(const path& p, error_code& ec) noexcept;

      bool is_block_file(file_status s) noexcept;
      bool is_block_file(const path& p);
      bool is_block_file(const path& p, error_code& ec) noexcept;

      bool is_character_file(file_status s) noexcept;
      bool is_character_file(const path& p);
      bool is_character_file(const path& p, error_code& ec) noexcept;

      bool is_directory(file_status s) noexcept;
      bool is_directory(const path& p);
      bool is_directory(const path& p, error_code& ec) noexcept;

      bool is_empty(const path& p);
      bool is_empty(const path& p, error_code& ec);

      bool is_fifo(file_status s) noexcept;
      bool is_fifo(const path& p);
      bool is_fifo(const path& p, error_code& ec) noexcept;

      bool is_other(file_status s) noexcept;
      bool is_other(const path& p);
      bool is_other(const path& p, error_code& ec) noexcept;

      bool is_regular_file(file_status s) noexcept;
      bool is_regular_file(const path& p);
      bool is_regular_file(const path& p, error_code& ec) noexcept;

      bool is_socket(file_status s) noexcept;
      bool is_socket(const path& p);
      bool is_socket(const path& p, error_code& ec) noexcept;

      bool is_symlink(file_status s) noexcept;
      bool is_symlink(const path& p);
      bool is_symlink(const path& p, error_code& ec) noexcept;

      file_time_type last_write_time(const path& p);
      file_time_type last_write_time(const path& p, error_code& ec) noexcept;
      void last_write_time(const path& p, file_time_type new_time);
      void last_write_time(const path& p, file_time_type new_time,
                           error_code& ec) noexcept;

      void permissions(const path& p, perms prms, perm_options opts=perm_options::replace);
      void permissions(const path& p, perms prms, error_code& ec) noexcept;
      void permissions(const path& p, perms prms, perm_options opts, error_code& ec);

      path proximate(const path& p, error_code& ec);
      path proximate(const path& p, const path& base = current_path());
      path proximate(const path& p, const path& base, error_code& ec);

      path read_symlink(const path& p);
      path read_symlink(const path& p, error_code& ec);

      path relative(const path& p, error_code& ec);
      path relative(const path& p, const path& base = current_path());
      path relative(const path& p, const path& base, error_code& ec);

      bool remove(const path& p);
      bool remove(const path& p, error_code& ec) noexcept;

      uintmax_t remove_all(const path& p);
      uintmax_t remove_all(const path& p, error_code& ec);

      void rename(const path& from, const path& to);
      void rename(const path& from, const path& to, error_code& ec) noexcept;

      void resize_file(const path& p, uintmax_t size);
      void resize_file(const path& p, uintmax_t size, error_code& ec) noexcept;

      space_info space(const path& p);
      space_info space(const path& p, error_code& ec) noexcept;

      file_status status(const path& p);
      file_status status(const path& p, error_code& ec) noexcept;

      bool status_known(file_status s) noexcept;

      file_status symlink_status(const path& p);
      file_status symlink_status(const path& p, error_code& ec) noexcept;

      path temp_directory_path();
      path temp_directory_path(error_code& ec);

      path weakly_canonical(const path& p);
      path weakly_canonical(const path& p, error_code& ec);
    }

    namespace std::ranges {
      template<>
      inline constexpr bool enable_borrowed_range<filesystem::directory_iterator> = true;
      template<>
      inline constexpr bool
        enable_borrowed_range<filesystem::recursive_directory_iterator> = true;

      template<>
      inline constexpr bool enable_view<filesystem::directory_iterator> = true;
      template<>
      inline constexpr bool enable_view<filesystem::recursive_directory_iterator> = true;
    }

    // 弃用
    namespace std::filesystem {
      template<class Source>
        path u8path(const Source& source);
      template<class InputIterator>
        path u8path(InputIt first, InputIt last);
    }

#### 类 std::filesystem::path

    namespace std::filesystem {
      class path {
      public:
        using value_type  = /* 见描述 */;
        using string_type = basic_string<value_type>;
        static constexpr value_type preferred_separator = /* 见描述 */;

        // 枚举 format
        enum format;

        // 构造函数与析构函数
        path() noexcept;
        path(const path& p);
        path(path&& p) noexcept;
        path(string_type&& source, format fmt = auto_format);
        template<class Source>
          path(const Source& source, format fmt = auto_format);
        template<class InputIt>
          path(InputIt first, InputIt last, format fmt = auto_format);
        template<class Source>
          path(const Source& source, const locale& loc, format fmt = auto_format);
        template<class InputIt>
          path(InputIt first, InputIt last, const locale& loc, format fmt = auto_format);
        ~path();

        // 赋值
        path& operator=(const path& p);
        path& operator=(path&& p) noexcept;
        path& operator=(string_type&& source);
        path& assign(string_type&& source);
        template<class Source>
          path& operator=(const Source& source);
        template<class Source>
          path& assign(const Source& source);
        template<class InputIt>
          path& assign(InputIt first, InputIt last);

        // 后附
        path& operator/=(const path& p);
        template<class Source>
          path& operator/=(const Source& source);
        template<class Source>
          path& append(const Source& source);
        template<class InputIt>
          path& append(InputIt first, InputIt last);

        // 连接
        path& operator+=(const path& x);
        path& operator+=(const string_type& x);
        path& operator+=(basic_string_view<value_type> x);
        path& operator+=(const value_type* x);
        path& operator+=(value_type x);
        template<class Source>
          path& operator+=(const Source& x);
        template<class ECharT>
          path& operator+=(ECharT x);
        template<class Source>
          path& concat(const Source& x);
        template<class InputIt>
          path& concat(InputIt first, InputIt last);

        // 修改器
        void  clear() noexcept;
        path& make_preferred();
        path& remove_filename();
        path& replace_filename(const path& replacement);
        path& replace_extension(const path& replacement = path());
        void  swap(path& rhs) noexcept;

        // 非成员函数
        friend bool operator==(const path& lhs, const path& rhs) noexcept;
        friend strong_ordering operator<=>(const path& lhs, const path& rhs) noexcept;

        friend path operator/ (const path& lhs, const path& rhs);

        // 原生格式观察器
        const string_type& native() const noexcept;
        const value_type*  c_str() const noexcept;
        operator string_type() const;

        template<class ECharT, class Traits = char_traits<ECharT>,
                 class Allocator = allocator<ECharT>>
          basic_string<ECharT, Traits, Allocator>
            string(const Allocator& a = Allocator()) const;
        std::string    string() const;
        std::wstring   wstring() const;
        std::u8string  u8string() const;
        std::u16string u16string() const;
        std::u32string u32string() const;

        // 通用格式观察器
        template<class ECharT, class Traits = char_traits<ECharT>,
                 class Allocator = allocator<ECharT>>
          basic_string<ECharT, Traits, Allocator>
            generic_string(const Allocator& a = Allocator()) const;
        std::string    generic_string() const;
        std::wstring   generic_wstring() const;
        std::u8string  generic_u8string() const;
        std::u16string generic_u16string() const;
        std::u32string generic_u32string() const;

        // 比较
        int compare(const path& p) const noexcept;
        int compare(const string_type& s) const;
        int compare(basic_string_view<value_type> s) const;
        int compare(const value_type* s) const;

        // 分解
        path root_name() const;
        path root_directory() const;
        path root_path() const;
        path relative_path() const;
        path parent_path() const;
        path filename() const;
        path stem() const;
        path extension() const;

        // 查询
        [[nodiscard]] bool empty() const noexcept;
        bool has_root_name() const;
        bool has_root_directory() const;
        bool has_root_path() const;
        bool has_relative_path() const;
        bool has_parent_path() const;
        bool has_filename() const;
        bool has_stem() const;
        bool has_extension() const;
        bool is_absolute() const;
        bool is_relative() const;

        // 生成
        path lexically_normal() const;
        path lexically_relative(const path& base) const;
        path lexically_proximate(const path& base) const;

        // 迭代器
        class iterator;
        using const_iterator = iterator;

        iterator begin() const;
        iterator end() const;

        // path 插入器与提取器
        template<class CharT, class Traits>
          friend basic_ostream<CharT, Traits>&
            operator<<(basic_ostream<CharT, Traits>& os, const path& p);
        template<class CharT, class Traits>
          friend basic_istream<CharT, Traits>&
            operator>>(basic_istream<CharT, Traits>& is, path& p);
      };
    }

#### 类 std::filesystem::filesystem_error

    namespace std::filesystem {
      class filesystem_error : public system_error {
      public:
        filesystem_error(const string& what_arg, error_code ec);
        filesystem_error(const string& what_arg,
                         const path& p1, error_code ec);
        filesystem_error(const string& what_arg,
                         const path& p1, const path& p2, error_code ec);

        const path& path1() const noexcept;
        const path& path2() const noexcept;
        const char* what() const noexcept override;
      };
    }

#### 类 std::filesystem::directory_entry

    namespace std::filesystem {
      class directory_entry {
      public:
        // 构造函数与析构函数
        directory_entry() noexcept = default;
        directory_entry(const directory_entry&) = default;
        directory_entry(directory_entry&&) noexcept = default;
        explicit directory_entry(const filesystem::path& p);
        directory_entry(const filesystem::path& p, error_code& ec);
        ~directory_entry();

        // 赋值
        directory_entry& operator=(const directory_entry&) = default;
        directory_entry& operator=(directory_entry&&) noexcept = default;

        // 修改器
        void assign(const filesystem::path& p);
        void assign(const filesystem::path& p, error_code& ec);
        void replace_filename(const filesystem::path& p);
        void replace_filename(const filesystem::path& p, error_code& ec);
        void refresh();
        void refresh(error_code& ec) noexcept;

        // 观察器
        const filesystem::path& path() const noexcept;
        operator const filesystem::path&() const noexcept;
        bool exists() const;
        bool exists(error_code& ec) const noexcept;
        bool is_block_file() const;
        bool is_block_file(error_code& ec) const noexcept;
        bool is_character_file() const;
        bool is_character_file(error_code& ec) const noexcept;
        bool is_directory() const;
        bool is_directory(error_code& ec) const noexcept;
        bool is_fifo() const;
        bool is_fifo(error_code& ec) const noexcept;
        bool is_other() const;
        bool is_other(error_code& ec) const noexcept;
        bool is_regular_file() const;
        bool is_regular_file(error_code& ec) const noexcept;
        bool is_socket() const;
        bool is_socket(error_code& ec) const noexcept;
        bool is_symlink() const;
        bool is_symlink(error_code& ec) const noexcept;
        uintmax_t file_size() const;
        uintmax_t file_size(error_code& ec) const noexcept;
        uintmax_t hard_link_count() const;
        uintmax_t hard_link_count(error_code& ec) const noexcept;
        file_time_type last_write_time() const;
        file_time_type last_write_time(error_code& ec) const noexcept;
        file_status status() const;
        file_status status(error_code& ec) const noexcept;
        file_status symlink_status() const;
        file_status symlink_status(error_code& ec) const noexcept;

        bool operator==(const directory_entry& rhs) const noexcept;
        strong_ordering operator<=>(const directory_entry& rhs) const noexcept;

        // 插入器
        template<class charT, class traits>
          friend basic_ostream<charT, traits>&
            operator<<(basic_ostream<charT, traits>& os, const directory_entry& d);

      private:
        filesystem::path pathobject;        // 仅用于阐释
        friend class directory_iterator;    // 仅用于阐释
      };
    }

#### 类 std::filesystem::directory_iterator

    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&;

        // 成员函数
        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);

        // 其他按输入迭代器要求的成员
      };
    }

#### 类 std::filesystem::recursive_directory_iterator

    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&;

        // 构造函数与析构函数
        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();

        // 观察器
        directory_options  options() const;
        int                depth() const;
        bool               recursion_pending() const;

        const directory_entry& operator*() const;
        const directory_entry* operator->() const;

        // 修改器
        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();

        // 其他按输入迭代器要求的成员
      };
    }

#### 类 std::filesystem::file_status

    namespace std::filesystem {
      class file_status {
      public:
        // 构造函数与析构函数
        file_status() noexcept : file_status(file_type::none) {}
        explicit file_status(file_type ft,
                             perms prms = perms::unknown) noexcept;
        file_status(const file_status&) noexcept = default;
        file_status(file_status&&) noexcept = default;
        ~file_status();

        // 赋值
        file_status& operator=(const file_status&) noexcept = default;
        file_status& operator=(file_status&&) noexcept = default;

        // 修改器
        void       type(file_type ft) noexcept;
        void       permissions(perms prms) noexcept;

        // 观察器
        file_type  type() const noexcept;
        perms      permissions() const noexcept;

        friend bool operator==(const file_status& lhs, const file_status& rhs) noexcept
          { return lhs.type() == rhs.type() && lhs.permissions() == rhs.permissions(); }
      };
    }