std::experi...::copy_file(3)

🌸 NAME 🌸

std::experimental::filesystem::copy_file — bestie, it's literally the function that copies one single file, and yes the page title is the function name twice because that's just how this manpage rolls 💅

(Heads up: the manual name up top is std::experi...::copy_file(3), from the C++ Standard Libary — and yeah, that's how they spelled "Library" up in the header, we don't judge, we celebrate ✨)

---

✨ Synopsis ✨

Defined in header <experimental/filesystem>

bool copy_file( const path& from, const path& to );
bool copy_file( const path& from, const path& to, error_code& ec );                    (1) (filesystem TS)
bool copy_file( const path& from, const path& to, copy_options options );             (2) (filesystem TS)
bool copy_file( const path& from, const path& to, copy_options options, error_code& ec );

So here's the tea, split into numbered lore drops:

1. This is the default one, and it's equivalent to (2) with copy_options::none used as options. Zero options, zero drama 🫶
2. This one copies a single file from from to to, using the copy options indicated by options. And okay, pay attention bestie: 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 copy_file). Like, even the irrelevant groups. Do not test her. 😭

Then the actual copy logic, in order:

• If the destination file does not exist:
  • it 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:
  • If to and from are the same as determined by equivalent(from, to), report an error.
  • Otherwise, if none of the copy_file control options are set in options, report an error.
  • Otherwise, if copy_options::skip_existing is set in options, do nothing. (Iconic. Unbothered. Moisturized. 🧖)
  • 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 last_write_time().

The non-throwing overloads return false if an error occurs. No throwing, just vibes 💀

---

💖 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. That's it, that's the whole mood 🦋

---

🦋 Exceptions 🦋

The overload that does not take an error_code& parameter throws filesystem_error on underlying OS API errors, constructed with from as the first argument, to as the second argument, and the OS error code as the error code argument. Also, std::bad_alloc may be thrown if memory allocation fails.

The overload taking an error_code& parameter sets it to the OS API error code if an OS API call fails, and executes ec.clear() if no errors occur. This overload has this noexcept specification:

noexcept

---

⭐ Notes ⭐

• The functions involve at most one direct or indirect call to status(to) (used both to determine if the file exists, and, for copy_options::update_existing option, its last write time).
• Error is reported when copy_file is used to copy a directory: use copy for that.
• copy_file follows symlinks: use copy_symlink or copy with copy_options::copy_symlinks for that.

Lowkey the whole notes section is just "wrong tool for the job, bestie, here's the right one" and honestly? Respect 🙈

---

🌈 Example 🌈

// Run this code

#include <experimental/filesystem>
#include <fstream>
#include <iostream>
namespace fs = std::experimental::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"

Look at her go — copies the file, then gracefully catches the directory fail. Main character energy, no cap 🔥

---

👑 See also 👑

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

---

🍓 Categories 🍓

• Noindexed pages
• unconditionally noexcept

🧚 Hidden categories 🧚

• Pages with unreviewed unconditional noexcept template
• Pages with unreviewed noexcept template

---

Okay that's the whole page, you're so smart now, periodt 💜 She's from http://cppreference.com, last touched 2024.06.10, and the file is std::experi...::copy_file(3) in case you gotta cite your sources at the group chat 🫶✨