std::filesystem::copy_file(3)

🌸 NAME 🌸

okay bestie, welcome to std::filesystem::copy_file(3) — the C++ Standard Libary page for std::filesystem::copy_file (yes, that’s the spelling in the header, not me 😭). It’s giving “copy one file, but make it overloaded,” and we’re gonna get into every single detail 💅✨.

---

🦋 Synopsis 🦋

Defined in header <filesystem>.

bool copy_file( const std::filesystem::path& from,       (1) (since C++17)
                const std::filesystem::path& to );
bool copy_file( const std::filesystem::path& from,
                const std::filesystem::path& to,         (2) (since C++17)
                std::error_code& ec );
bool copy_file( const std::filesystem::path& from,
                const std::filesystem::path& to,         (3) (since C++17)
                std::filesystem::copy_options options );
bool copy_file( const std::filesystem::path& from,
                const std::filesystem::path& to,         (4) (since C++17)
                std::filesystem::copy_options options,
                std::error_code& ec );

• 1,2) The default, equivalent to (3,4) with copy_options::none used as options.
• 3,4) Copies a single file from from to to, using the copy options indicated by options. The behavior is undefined if there is more than one option in any of the copy_options option group present in options (even in the groups not relevant to filesystem::copy_file) 💀.
  • If !filesystem::is_regular_file(from) (either because the source file doesn't exist or because it is not a regular file), report an error.
  • Otherwise, if the destination file does not exist,
    • copies the contents and the attributes of the file to which from resolves to the file to which to resolves (symlinks are followed).
  • Otherwise, if the destination file already exists,
    • report an error if any of the following is true:
      • to and from are the same as determined by filesystem::equivalent(from, to);
      • to is not a regular file as determined by !filesystem::is_regular_file(to);
      • none of the filesystem::copy_file control options are set in options.
    • Otherwise, if copy_options::skip_existing is set in options, do nothing.
    • Otherwise, if copy_options::overwrite_existing is set in options, copy the contents and the attributes of the file to which from resolves to the file to which to resolves.
    • Otherwise, if copy_options::update_existing is set in options, only copy the file if from is newer than to, as defined by filesystem::last_write_time().

The non-throwing overloads return false if an error occurs.

---

🎀 Parameters 🎀

• from — path to the source file 💖
• to — path to the target file 🎯
• ec — out-parameter for error reporting in the non-throwing overload 🫶

---

⭐ Return value ⭐

true if the file was copied, false otherwise. simple as that, bestie ✨

---

💀 Exceptions 💀

Any overload not marked noexcept may throw std::bad_alloc if memory allocation fails.

• 1,3) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed with from as the first path argument, to as the second path argument, and the OS error code as the error code argument.
• 2,4) Sets a std::error_code& parameter to the OS API error code if an OS API call fails, and executes ec.clear() if no errors occur.

---

🌸 Notes 🌸

The functions involve at most one direct or indirect call to filesystem::status(to) (used both to determine if the file exists, and, for filesystem::copy_options::update_existing option, its last write time).

Error is reported when filesystem::copy_file is used to copy a directory: use filesystem::copy for that.

filesystem::copy_file follows symlinks: use filesystem::copy_symlink or filesystem::copy with filesystem::copy_options::copy_symlinks for that.

iykyk: this function is for one file, not a whole directory situation. The page said it, I’m just saying it with love 💜.

---

🧚 Example 🧚

// Run this code

#include <filesystem>
#include <fstream>
#include <iostream>
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");

    // now there are two files in 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';

    // fail to copy directory
    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");
}

---

🍓 Possible output 🍓

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

---

🩹 Defect reports 🩹

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• DR: LWG 3014 — Applied to: C++17 — Behavior as published: error_code overload marked noexcept but can allocate memory — Correct behavior: noexcept removed ✅

---

🌈 See also 🌈

• copy_options — specifies semantics of copy operations (C++17) (enum)
• copy_symlink — copies a symbolic link (C++17) (function)
• copy — copies files or directories (C++17) (function)

---

xoxo, bestie 💖 this page came from http://cppreference.com, dated 2024.06.10, and the manual name is std::filesystem::copy_file(3) ✨🫶