命名空间
变体
操作

std::filesystem::copy

来自 cppreference.com
 
C++
 
文件系统库
类
函数
文件类型
 
定义在头文件 <filesystem> 中
void copy( const std::filesystem::path& from,
           const std::filesystem::path& to );
 (1) (自 C++17 起)
void copy( const std::filesystem::path& from,

           const std::filesystem::path& to,

           std::error_code& ec );
 (2) (自 C++17 起)
void copy( const std::filesystem::path& from,

           const std::filesystem::path& to,

           std::filesystem::copy_options options );
 (3) (自 C++17 起)
void copy( const std::filesystem::path& from,

           const std::filesystem::path& to,
           std::filesystem::copy_options options,

           std::error_code& ec );
 (4) (自 C++17 起)

复制文件和目录，使用多种选项。

1,2) 默认值，等效于 (3,4)，使用 copy_options::none 作为 options.
3,4) 使用 options 中指定的复制选项，将文件或目录 from 复制到文件或目录 to。如果 copy_options 选项组中的任何一个选项在 options 中存在多个（即使在 copy_file 组中），则行为未定义。

行为如下

  • 首先，在执行任何其他操作之前，通过最多一次调用获得 from 的类型和权限
  • 如果需要，通过最多一次调用获得 to 的状态
  • 如果 from 或 to 具有实现定义的 文件类型，则此函数的效果是实现定义的。
  • 如果 from 不存在，则报告错误。
  • 如果 from 和 to 是同一个文件，由 std::filesystem::equivalent 确定，则报告错误。
  • 如果 from 或 to 不是常规文件、目录或符号链接，由 std::filesystem::is_other 确定，则报告错误。
  • 如果 from 是目录，但 to 是常规文件，则报告错误。
  • 如果 from 是符号链接，则
  • 如果 copy_options::skip_symlink 出现在 options 中，则不执行任何操作。
  • 否则，如果 to 不存在并且 copy_options::copy_symlinks 出现在 options 中，则表现得好像 copy_symlink(from, to).
  • 否则，报告错误。
  • 否则，如果 from 是常规文件，则
  • 如果 copy_options::directories_only 出现在 options 中，则不执行任何操作。
  • 否则，如果 copy_options::create_symlinks 出现在 options 中，则创建指向 to 的符号链接。注意：from 必须是绝对路径，除非 to 在当前目录中。
  • 否则，如果 copy_options::create_hard_links 出现在 options 中，则创建指向 to 的硬链接。
  • 否则，如果 to 是目录，则表现得好像 copy_file(from, to/from.filename(), options)（在目录 to 中创建 from 的副本作为文件）。
  • 否则，表现得好像 copy_file(from, to, options)（复制文件）。
  • 否则，如果 from 是目录并且 copy_options::create_symlinks 在 options 中设置，则报告错误，错误代码等于 std::make_error_code(std::errc::is_a_directory).
  • 否则，如果 from 是目录并且 options 包含 copy_options::recursive 或为 copy_options::none，
  • 如果 to 不存在，则首先执行 create_directory(to, from)（创建包含旧目录属性副本的新目录）。
  • 然后，无论 to 已经存在还是刚刚创建，都迭代 from 中包含的文件，就像通过 for (const std::filesystem::directory_entry& x : std::filesystem::directory_iterator(from))，并且对于每个目录条目，递归调用 copy(x.path(), to/x.path().filename(), options | in-recursive-copy)，其中 in-recursive-copy 是一个特殊位，当在 options 中设置时没有其他效果。（设置此位的唯一目的是，如果 options 为 copy_options::none，则防止递归复制子目录。）
  • 否则不执行任何操作。

内容

[编辑] 参数

from - 源文件、目录或符号链接的路径
to - 目标文件、目录或符号链接的路径
ec - 非抛出重载中用于错误报告的输出参数

[编辑] 返回值

(无)

[编辑] 异常

任何未标记为 noexcept 的重载，如果内存分配失败，可能会抛出 std::bad_alloc。

1,3) 如果底层操作系统 API 发生错误，则抛出 std::filesystem::filesystem_error，并使用 from 作为第一个路径参数，to 作为第二个路径参数，以及操作系统错误代码作为错误代码参数构建。
2,4) 如果操作系统 API 调用失败，则将 std::error_code& 参数设置为操作系统 API 错误代码，如果未发生错误，则执行 ec.clear()。

[编辑] 注释

复制目录时的默认行为是非递归复制：文件被复制，但子目录不会被复制。

// Given
// /dir1 contains /dir1/file1, /dir1/file2, /dir1/dir2
// and /dir1/dir2 contains /dir1/dir2/file3
// After
std::filesystem::copy("/dir1", "/dir3");
// /dir3 is created (with the attributes of /dir1)
// /dir1/file1 is copied to /dir3/file1
// /dir1/file2 is copied to /dir3/file2

而使用 copy_options::recursive 时，子目录也会被复制，包括它们的内容，以递归方式。

// ...but after
std::filesystem::copy("/dir1", "/dir3", std::filesystem::copy_options::recursive);
// /dir3 is created (with the attributes of /dir1)
// /dir1/file1 is copied to /dir3/file1
// /dir1/file2 is copied to /dir3/file2
// /dir3/dir2 is created (with the attributes of /dir1/dir2)
// /dir1/dir2/file3 is copied to /dir3/dir2/file3

[编辑] 示例

运行此代码
#include <cstdlib>
#include <filesystem>
#include <fstream>
#include <iostream>
namespace fs = std::filesystem;
 
int main()
{
    fs::create_directories("sandbox/dir/subdir");
    std::ofstream("sandbox/file1.txt").put('a');
    fs::copy("sandbox/file1.txt", "sandbox/file2.txt"); // copy file
    fs::copy("sandbox/dir", "sandbox/dir2"); // copy directory (non-recursive)
    const auto copyOptions = fs::copy_options::update_existing
                           | fs::copy_options::recursive
                           | fs::copy_options::directories_only
                           ;
    fs::copy("sandbox", "sandbox_copy", copyOptions); 
    static_cast<void>(std::system("tree"));
    fs::remove_all("sandbox");
    fs::remove_all("sandbox_copy");
}

可能的输出

.
├── sandbox
│   ├── dir
│   │   └── subdir
│   ├── dir2
│   ├── file1.txt
│   └── file2.txt
└── sandbox_copy
    ├── dir
    │   └── subdir
    └── dir2
 
8 directories, 2 files

[编辑] 缺陷报告

以下行为变更缺陷报告被追溯应用于先前发布的 C++ 标准。

DR 应用于 发布的行为 正确的行为
LWG 3013 C++17 error_code 重载标记为 noexcept 但可以分配内存 noexcept 已移除
LWG 2682 C++17 尝试为目录创建符号链接成功但没有任何效果 报告错误

[编辑] 参见

(C++17)
 指定复制操作的语义
(枚举) [编辑]
(C++17)
 复制符号链接
(函数) [编辑]
(C++17)
 复制文件内容
(函数) [编辑]
取自 "https://cppreference.cn/mwiki/index.php?title=cpp/filesystem/copy&oldid=157937"