标准库标头 <filesystem> (C++17)

 

C++

编译器支持

自立实现与有宿主实现

语言

标准库

标准库标头

具名要求

功能特性测试宏(C++20)

语言支持库

概念库(C++20)

诊断库

内存管理库

元编程库(C++11)

通用工具库

容器库

迭代器库

范围库(C++20)

算法库

字符串库

文本处理库

数值库

日期和时间库

输入/输出库

文件系统库(C++17)

并发支持库(C++11)

执行控制库(C++26)

技术规范

符号索引

外部库

 

标准库头

语言支持 <cfloat> <climits> <compare>(C++20) <contracts>(C++26) <coroutine>(C++20) <csetjmp> <csignal> <cstdarg> <cstddef> <cstdint>(C++11) <cstdlib> <exception> <initializer_list>(C++11)    <limits> <new> <source_location>(C++20) <stdfloat>(C++23) <typeinfo> <version>(C++20) 概念 <concepts>(C++20) 诊断 <cassert> <cerrno> <debugging>(C++26) <stacktrace>(C++23) <stdexcept> <system_error>(C++11) 内存管理 <memory> <memory_resource>(C++17) <scoped_allocator>(C++11) 元编程 <type_traits>(C++11) <ratio>(C++11)

通用工具 <any>(C++17) <bitset> <bit>(C++20) <charconv>(C++17) <expected>(C++23) <format>(C++20) <functional> <optional>(C++17) <stdbit.h>(C++26) <tuple>(C++11) <typeindex>(C++11) <utility> <variant>(C++17) 容器 <array>(C++11) <deque> <flat_map>(C++23) <flat_set>(C++23) <forward_list>(C++11) <hive>(C++26) <inplace_vector>(C++26)    <list> <map> <mdspan>(C++23) <queue> <set> <span>(C++20) <stack> <unordered_map>(C++11) <unordered_set>(C++11) <vector> 迭代器 <iterator> 范围 <generator>(C++23) <ranges>(C++20)

算法 <algorithm> <numeric> 字符串 <cctype> <cstring> <cuchar>(C++11) <cwchar> <cwctype> <string_view>(C++17) <string> 文本处理 <clocale> <codecvt>(C++11/17/26*) <locale> <regex>(C++11) <text_encoding>(C++26)    cpp/header#数值库数值 <cfenv>(C++11) <cmath> <complex> <linalg>(C++26) <numbers>(C++20) <random>(C++11) <simd>(C++26) <stdckdint.h>(C++26) <valarray> 时间 <chrono>(C++11) <ctime> C 兼容性 <ccomplex>(C++11/17/20*) <ciso646>(C++20 前) <cstdalign>(C++11/17/20*) <cstdbool>(C++11/17/20*) <ctgmath>(C++11/17/20*)

输入/输出 <cinttypes>(C++11) <cstdio> <filesystem>(C++17) <fstream> <iomanip> <iosfwd> <iostream> <ios> <istream> <ostream> <print>(C++23) <spanstream>(C++23) <sstream> <streambuf> <strstream>(C++98/26*) <syncstream>(C++20) 并发支持 <atomic>(C++11) <barrier>(C++20) <condition_variable>(C++11) <future>(C++11) <hazard_pointer>(C++26) <latch>(C++20) <mutex>(C++11) <rcu>(C++26) <semaphore>(C++20) <shared_mutex>(C++14) <stdatomic.h>(C++23) <stop_token>(C++20) <thread>(C++11) 执行支持 <execution>(C++17)

 

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

包含
<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)
在命名空间 std 定义
std::hash<std::filesystem::path> (C++17)	std::filesystem::path 的散列支持 (类模板特化)
前置声明
在标头 <functional> 定义
在命名空间 std 定义
hash (C++11)	散列函数对象 (类模板)
函数
在命名空间 std::filesystem 定义
u8path (C++17)(C++20 弃用)	从 UTF-8 编码的源创建 path (函数)
absolute (C++17)	组成一个绝对路径 (函数)
canonicalweakly_canonical (C++17)	组成一个规范路径 (函数)
relativeproximate (C++17)	组成一个相对路径 (函数)
copy (C++17)	复制文件或目录 (函数)
copy_file (C++17)	复制文件内容 (函数)
copy_symlink (C++17)	复制一个符号链接 (函数)
create_directorycreate_directories (C++17)(C++17)	创建新目录 (函数)
create_hard_link (C++17)	创建一个硬链接 (函数)
create_symlinkcreate_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)	获得符号链接的目标 (函数)
removeremove_all (C++17)(C++17)	移除一个文件或空目录 移除一个文件或递归地移除一个目录及其所有内容 (函数)
rename (C++17)	移动或重命名一个文件或目录 (函数)
resize_file (C++17)	以截断或填充零更改一个常规文件的大小 (函数)
space (C++17)	确定文件系统上的可用空闲空间 (函数)
statussymlink_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;   friendbool operator==(const space_info&, const space_info&)=default;};   // 枚举enumclass file_type;enumclass perms;enumclass perm_options;enumclass copy_options;enumclass 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 {template<class T>struct hash;template<>struct hash<filesystem::path>;}   namespace std::ranges{template<>inlineconstexprbool enable_borrowed_range<filesystem::directory_iterator>=true;template<>inlineconstexprbool enable_borrowed_range<filesystem::recursive_directory_iterator>=true;   template<>inlineconstexprbool enable_view<filesystem::directory_iterator>=true;template<>inlineconstexprbool enable_view<filesystem::recursive_directory_iterator>=true;}

类 std::filesystem::path

namespace std::filesystem{class path {public:using value_type =/* 见描述 */;using string_type = basic_string<value_type>;staticconstexpr value_type preferred_separator =/* 见描述 */;   // 枚举 formatenum 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;   // 非成员函数friendbool 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()constnoexcept;const value_type* c_str()constnoexcept; 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)constnoexcept;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;   // 查询bool empty()constnoexcept;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()constnoexcept;const path& path2()constnoexcept;constchar* what()constnoexcept 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()constnoexcept; operator const filesystem::path&()constnoexcept;bool exists()const;bool exists(error_code& ec)constnoexcept;bool is_block_file()const;bool is_block_file(error_code& ec)constnoexcept;bool is_character_file()const;bool is_character_file(error_code& ec)constnoexcept;bool is_directory()const;bool is_directory(error_code& ec)constnoexcept;bool is_fifo()const;bool is_fifo(error_code& ec)constnoexcept;bool is_other()const;bool is_other(error_code& ec)constnoexcept;bool is_regular_file()const;bool is_regular_file(error_code& ec)constnoexcept;bool is_socket()const;bool is_socket(error_code& ec)constnoexcept;bool is_symlink()const;bool is_symlink(error_code& ec)constnoexcept; uintmax_t file_size()const; uintmax_t file_size(error_code& ec)constnoexcept; uintmax_t hard_link_count()const; uintmax_t hard_link_count(error_code& ec)constnoexcept; file_time_type last_write_time()const; file_time_type last_write_time(error_code& ec)constnoexcept; file_status status()const; file_status status(error_code& ec)constnoexcept; file_status symlink_status()const; file_status symlink_status(error_code& ec)constnoexcept;   bool operator==(const directory_entry& rhs)constnoexcept; strong_ordering operator<=>(const directory_entry& rhs)constnoexcept;   // 插入器template<class charT, class traits>friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const directory_entry& d);   private: filesystem::path pathobject;// 仅用于阐释friendclass 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);   bool operator==(default_sentinel_t)constnoexcept{return*this == directory_iterator();}   // 其他按输入迭代器要求的成员};}

类 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()constnoexcept; perms permissions()constnoexcept;   friendbool operator==(const file_status& lhs, const file_status& rhs)noexcept{return lhs.type()== rhs.type()&& lhs.permissions()== rhs.permissions();}};}