Share via

<filesystem> 函数

  • 项目

<filesystem> 标头中的这些 free 函数对路径、文件、符号链接、目录和卷执行修改和查询操作。 有关详细信息和代码示例，请参阅文件系统导航 (C++)。

absolute

path absolute(const path& pval, const path& base = current_path());

该函数返回与 pval 对应的绝对路径名（相对于路径名 base）：

  1. 如果 pval.has_root_name() && pval.has_root_directory()，该函数将返回 pval。

  2. 如果 pval.has_root_name() && !pval.has_root_directory()，该函数将返回 pval.root_name() / absolute(base).root_directory() / absolute(base).relative_path() / pval.relative_path()。

  3. 如果 !pval.has_root_name() && pval.has_root_directory()，该函数将返回 absolute(base).root_name() / pval。

  4. 如果 !pval.has_root_name() && !pval.has_root_directory()，该函数将返回 absolute(base) / pval。

begin

const directory_iterator& begin(const directory_iterator& iter) noexcept;
const recursive_directory_iterator&
    begin(const recursive_directory_iterator& iter) noexcept;

两个函数均返回 iter。

canonical

path canonical(const path& pval, const path& base = current_path());
path canonical(const path& pval, error_code& ec);
path canonical(const path& pval, const path& base, error_code& ec);

这些函数均形成绝对路径名 pabs = absolute(pval, base)（或对于不使用任何基参数的重载为 pabs = absolute(pval)），然后按顺序执行以下步骤，将其简化为规范格式：

  1. is_symlink(X) 为 true 的每个路径组件 X 都替换为 read_symlink(X)。

  2. 移除每个路径组件 .（圆点是由以前的路径组件建立的当前目录）。

  3. 移除每对路径组件 X/..（双点是由以前的路径组件建立的父目录）。

然后，该函数返回 pabs。

copy

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

这些函数都可能在 opts 参数的控制下将 from 处的一个或多个文件复制或链接到 to，对于没有 opts 参数的重载，该参数被视为 copy_options::none。 opts 应最多包含一个以下项：

  • skip_existing、overwrite_existing 或 update_existing

  • copy_symlinks 或 skip_symlinks

  • directories_only、create_symlinks 或 create_hard_links

函数首先确定 file_status 值 f（表示 from）和 t（表示 to）：

  • 如果 opts & (copy_options::create_symlinks | copy_options::skip_symlinks)，则通过调用 symlink_status

  • 否则，通过调用 status

  • 否则报告错误。

如果 !exists(f) || equivalent(f, t) || is_other(f) || is_other(t) || is_directory(f)&& is_regular_file(t)则它们随后会报告错误（不执行任何其他操作）。

否则，如果 is_symlink(f)，则：

  • 如果 options & copy_options::skip_symlinks，则不执行任何操作。

  • 否则，如果 !exists(t)&& options & copy_options::copy_symlinks，则 copy_symlink(from, to, opts)。

  • 否则报告错误。

否则，如果 is_regular_file(f)，则：

  • 如果 opts & copy_options::directories_only，则不执行任何操作。

  • 否则，如果 opts & copy_options::create_symlinks，则 create_symlink(to, from)。

  • 否则，如果 opts & copy_options::create_hard_links，则 create_hard_link(to, from)。

  • 否则，如果 is_directory(f)，则 copy_file(from, to / from.filename(), opts)。

  • 否则为 copy_file(from, to, opts)。

否则，如果 is_directory(f) && (opts & copy_options::recursive || !opts)，则：

if (!exists(t))
{  // copy directory contents recursively
    create_directory(to, from, ec);

    for (directory_iterator next(from), end; ec == error_code() && next != end; ++next)
    {
        copy(next->path(), to / next->path().filename(), opts, ec);
    }
}

否则，不执行任何操作。

copy_file

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

这些函数都可能在 opts 参数的控制下将 from 处的文件复制到 to，对于没有 opts 参数的重载，该参数被视为 copy_options::none。 opts 应最多包含 skip_existing、overwrite_existing 或 update_existing 中的一项。

如果 exists(to) && !(opts & (copy_options::skip_existing | copy_options::overwrite_existing | copy_options::update_existing))，则报告为文件已存在错误。

否则，如果 !exists(to) || opts & copy_options::overwrite_existing || opts & copy_options::update_existing&& last_write_time(to) < last_write_time(from) || !(opts & (copy_options::skip_existing | copy_options::overwrite_existing | copy_options:update_existing))，则尝试将文件 from 的内容和属性复制到文件 to。 如果复制尝试失败，则报告错误。

如果尝试复制并成功，则函数返回 true，否则返回 false。

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

如果 is_directory(from)，函数会调用 create_directory_symlink(from, to)。 否则，会调用 create_symlink(from, to)。

create_directories

bool create_directories(const path& pval);
bool create_directories(const path& pval, error_code& ec) noexcept;

对于如 a\/b\/c 这样的路径名，函数根据需要创建目录 a 和 a\/b，以便它可以根据需要创建目录 a\/b\/c。 仅当它实际创建目录 pval 时，才返回 true。

create_directory

bool create_directory(const path& pval);

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

该函数将根据需要创建目录 pval。 仅当它实际创建目录 pval 时，才返回 true，在这种情况下，它将从现有文件 attr 复制权限，或对没有 attr 参数的重载使用 perms::all。

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

该函数将链接创建为指向目录 to 的符号链接。

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

该函数将链接创建为指向目录或文件 to 的硬链接。

void create_symlink(const path& to, const path& link);

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

该函数将 link 创建为指向文件 to 的符号链接。

current_path

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

没有 pval 参数的函数将返回当前目录的路径名。 剩余的函数将当前目录设置为 pval。

end

directory_iterator& end(const directory_iterator& iter) noexcept;
recursive_directory_iterator& end(const recursive_directory_iterator& iter) noexcept;

第一个函数返回 directory_iterator()，第二个函数返回 recursive_directory_iterator()

equivalent

bool equivalent(const path& left, const path& right);
bool equivalent(const path& left, const path& right, error_code& ec) noexcept;

仅当 left 和 right 选择相同的文件系统实体时，这些函数才返回 true。

exists

bool exists(file_status stat) noexcept;
bool exists(const path& pval);
bool exists(const path& pval, error_code& ec) noexcept;

第一个函数返回 status_known && stat.type() != file_not_found。 第二个和第三个函数返回 exists(status(pval))。

file_size

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

如果可以确定 exists(pval) && is_regular_file(pval) 和文件大小，函数会返回由 pval 选择的文件的大小（以字节为单位）。 否则将报告错误，并返回 uintmax_t(-1)。

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

该函数返回 pval 的硬链接数，如果出错，则返回 -1。

hash_value

size_t hash_value(const path& pval) noexcept;

该函数返回 pval.native() 的哈希值。

is_block_file

bool is_block_file(file_status stat) noexcept;
bool is_block_file(const path& pval);
bool is_block_file(const path& pval, error_code& ec) noexcept;

第一个函数返回 stat.type() == file_type::block。 其余函数返回 is_block_file(status(pval))。

is_character_file

bool is_character_file(file_status stat) noexcept;
bool is_character_file(const path& pval);
bool is_character_file(const path& pval, error_code& ec) noexcept;

第一个函数返回 stat.type() == file_type::character。 其余函数返回 is_character_file(status(pval))。

is_directory

bool is_directory(file_status stat) noexcept;
bool is_directory(const path& pval);
bool is_directory(const path& pval, error_code& ec) noexcept;

第一个函数返回 stat.type() == file_type::directory。 其余函数返回 is_directory_file(status(pval))。

is_empty

bool is_empty(file_status stat) noexcept;
bool is_empty(const path& pval);
bool is_empty(const path& pval, error_code& ec) noexcept;

如果 is_directory(pval)，则函数返回 directory_iterator(pval) == directory_iterator()；否则返回 file_size(pval) == 0。

is_fifo

bool is_fifo(file_status stat) noexcept;
bool is_fifo(const path& pval);
bool is_fifo(const path& pval, error_code& ec) noexcept;

第一个函数返回 stat.type() == file_type::fifo。 其余函数返回 is_fifo(status(pval))。

is_other

bool is_other(file_status stat) noexcept;
bool is_other(const path& pval);
bool is_other(const path& pval, error_code& ec) noexcept;

第一个函数返回 stat.type() == file_type::other。 其余函数返回 is_other(status(pval))。

is_regular_file

bool is_regular_file(file_status stat) noexcept;
bool is_regular_file(const path& pval);
bool is_regular_file(const path& pval, error_code& ec) noexcept;

第一个函数返回 stat.type() == file_type::regular。 其余函数返回 is_regular_file(status(pval))。

is_socket

bool is_socket(file_status stat) noexcept;
bool is_socket(const path& pval);
bool is_socket(const path& pval, error_code& ec) noexcept;

第一个函数返回 stat.type() == file_type::socket。 其余函数返回 is_socket(status(pval))。

bool is_symlink(file_status stat) noexcept;
bool is_symlink(const path& pval);
bool is_symlink(const path& pval, error_code& ec) noexcept;

第一个函数返回 stat.type() == file_type::symlink。 其余函数返回 is_symlink(status(pval))。

last_write_time

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

前两个函数返回 pval 的上次数据修改时间，或如果出错，则返回 file_time_type(-1)。 最后两个函数将 pval 的上次数据修改时间设置为 new_time。

permissions

void permissions(const path& pval, perms mask);
void permissions(const path& pval, perms mask, error_code& ec) noexcept;

这些函数在 perms & (perms::add_perms | perms::remove_perms) 的控制下，将通过 pval 选择的路径名的权限设置为 mask & perms::mask。 mask 应最多包含 perms::add_perms 和 perms::remove_perms 中的一项。

如果 mask & perms::add_perms，则函数会将权限设置为 status(pval).permissions() | mask & perms::mask。 否则，如果 mask & perms::remove_perms，则函数会将权限设置为 status(pval).permissions() & ~(mask & perms::mask)。 否则，函数会将权限设置为 mask & perms::mask。

proximate

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& pval);
path read_symlink(const path& pval, error_code& ec);

如果 !is_symlink(pval)，则这些函数报告错误并返回 path()。 否则，函数返回包含符号链接的 path 类型的对象。

relative

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

remove

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

仅当 exists(symlink_status(pval)) 并成功移除文件时，这些函数才返回 true。 符号链接会自行移除，而不是它选择的文件。

remove_all

uintmax_t remove_all(const path& pval);
uintmax_t remove_all(const path& pval, error_code& ec) noexcept;

如果 pval 是一个目录，则这些函数以递归方式删除所有目录项，然后删除该项本身。 否则，这些函数调用 remove。 它们返回已成功删除的所有元素数。

rename

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

这些函数将 from 重命名为 to。 符号链接自行重命名，而不是它选择的文件。

resize_file

void resize(const path& pval, uintmax_t size);
void resize(const path& pval, uintmax_t size, error_code& ec) noexcept;

这些函数调整文件的大小，以便 file_size(pval) == size

space

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

该函数以 space_info 类型的结构返回有关 pval 选择的卷的信息。 对于无法确定的任意值，该结构包含 uintmax_t(-1)。

status

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

这些函数返回与 pval 关联的路径名状态、文件类型和权限。 符号链接不自行测试，而是对它选择的文件进行测试。

status_known

bool status_known(file_status stat) noexcept;

该函数返回 stat.type() != file_type::none

swap

void swap(path& left, path& right) noexcept;

该函数交换 left 和 right 的内容。

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

这些函数返回与 pval 关联的路径名符号链接状态、文件类型和权限。 这些函数的行为与 status(pval) 一致，只是符号链接自行测试，而不是它选择的文件。

system_complete

path system_complete(const path& pval);
path system_complete(const path& pval, error_code& ec);

这些函数返回纳入考虑的绝对路径名，并在必要时返回与其根名称关联的当前目录。 （对于 POSIX，这些函数返回 absolute(pval)）。

temp_directory_path

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

这些函数返回适合包含临时文件的目录的路径名。

u8path

template <class Source>
path u8path(const Source& source);

template <class InIt>
path u8path(InIt first, InIt last);

第一个函数的行为与 path(source) 相同，第二个函数的行为与 path(first, last) 相同，只是每种情况中的所选源被视为编码为 UTF-8 的 char 元素序列（无论是何种文件系统）。

weakly_canonical

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