C++ 参考手册

位置：首页 > C++ 参考手册 >文件系统库 > std::filesystem::copy_file

std::filesystem::copy_file

定义于头文件 <filesystem>
bool copy_file( const std::filesystem::path& from,

                const std::filesystem::path& to );
bool copy_file( const std::filesystem::path& from,
                const std::filesystem::path& to,

                std::error_code& ec );
 (1) (C++17 起)
bool copy_file( const std::filesystem::path& from,

                const std::filesystem::path& to,
                std::filesystem::copy_options options );
bool copy_file( const std::filesystem::path& from,
                const std::filesystem::path& to,
                std::filesystem::copy_options options,

                std::error_code& ec );
 (2) (C++17 起)
1) 默认，等价于以 copy_options::none 为 options 的 (2)
2) 从 from 到 to 复制单个文件，使用 options 所指示的复制选项。若 options 中存在任一 copy_options 选项组中多于一个的选项，则行为未定义（即使在无关乎 copy_file 的组中）。
  • 若 !is_regular_file(from) （因为源文件不存在或它不是常规文件），则报告错误
  • 否则，若目标文件不存在，则
  • 复制 from 所解析到的文件的内容及属性到 to 所解析到者（跟随符号链接）
  • 否则，若目标文件已存在……
  • 若下列之一为真则报告错误：
  • 否则，若 copy_options::skip_existing 设置于 options ，则不做任何事
  • 否则，若 copy_options::overwrite_existing 设置于 options ，则复制 from 所解析到的文件的内容及属性到 to 所解析到的文件
  • 否则，若 copy_options::update_existing 设置于 options ，则仅若 from 按 last_write_time() 定义新于 to 才复制

若错误发生，则不抛出重载返回 false 。

参数

from - 源文件的路径
to - 目标文件的路径
ec - 不抛出重载中报告错误的输出参数

返回值

若文件被复制则返回 true ，否则返回 false 。

异常

不接受 std::error_code& 参数的重载在底层 OS API 错误时抛出 filesystem_error ，以第一 path 参数 from，第二 path 参数 to 和作为错误码参数的 OS 错误码构造。若 OS API 调用失败，则接受 std::error_code& 参数的重载设置该参数为 OS API 错误码，而若不出现错误则执行 ec.clear() 。若内存分配失败，则任何不标记为 noexcept 的重载可能抛出 std::bad_alloc 。

注意

函数最多引入一次对 status(to) 的直接或间接调用（均用于确定文件是否存在，及对于 copy_options::update_existing 选项，确定其最后写入时间）

当 copy_file 被用于复制目录时报告错误：用 copy 复制它们。

copy_file 跟随符号链接：用 copy_symlink 或 copy 带 copy_options::copy_symlinks 复制它们。

缺陷报告

下列更改行为的缺陷报告追溯地应用于以前出版的 C++ 标准。

DR 应用于 出版时的行为 正确行为
LWG 3014 C++17 error_code 重载被标记为 noexcept 但能分配内存 移除 noexcept

示例

运行此代码
#include <fstream>
#include <iostream>
#include <filesystem>
namespace fs = std::filesystem;
 
int main()
{
    fs::create_directory("sandbox");
    std::ofstream("sandbox/file1.txt").put('a');
 
    fs::copy_file("sandbox/file1.txt", "sandbox/file2.txt");
 
    // 现在 sandbox 中有二个文件：
    std::cout << "file1.txt holds : "
              << std::ifstream("sandbox/file1.txt").rdbuf() << '\n';
    std::cout << "file2.txt holds : "
              << std::ifstream("sandbox/file2.txt").rdbuf() << '\n';
 
    // 复制目录失败
    fs::create_directory("sandbox/abc");
    try {
        fs::copy_file("sandbox/abc", "sandbox/def");
    } catch(fs::filesystem_error& e) {
        std::cout << "Could not copy sandbox/abc: " << e.what() << '\n';
    }
    fs::remove_all("sandbox");
}

可能的输出： 

file1.txt holds : a
file2.txt holds : a
Could not copy sandbox/abc: copy_file: Is a directory: "sandbox/abc", "sandbox/def"

参阅

(C++17)
 指定复制操作的语义
(枚举)
(C++17)
 复制一个符号链接
(函数)
(C++17)
 复制文件或目录
(函数)