std::experi...system::copy(3)

✨ NAME ✨

okay so this is the std::experi...system::copy(3) page from the C++ Standard Libary manual, and the function’s full name is literally std::experimental::filesystem::copy — like, both sides of the dash are std::experimental::filesystem::copy, no cap. She copies files and directories, and she’s got options for days. 💅

---

🦋 Synopsis 🦋

Defined in header <experimental/filesystem>, bestie:

Defined in header <experimental/filesystem>
void copy( const path& from, const path& to );                   (1)
(filesystem TS)
void copy( const path& from, const path& to, error_code& ec );
void copy( const path& from, const path& to, copy_options options ); (2)
(filesystem TS)
void copy( const path& from, const path& to, copy_options options, error_code& ec );

She copies files and directories, with a whole variety of options:

1. The default — equivalent to (2) with copy_options::none used as options.
2. Copies the file or directory from to file or directory to, using the copy options indicated by options.

Undefined behavior alert, 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 copy_file group, which is not relevant to copy). Do not test her like that. 😭

The behavior is as follows:

• First, before doing anything else, obtains type and permissions of from by no more than single call to status (or, if copy_options::skip_symlinks or copy_options::create_symlinks are present in options, by a call to symlink_status).
• If necessary, obtains the status of to the same way, by no more than a single status or symlink_status call.
• If from does not exist, reports an error.
• If from and to are the same file as determined by equivalent(), reports an error.
• If either from or to is not a regular file, a directory, or a symlink, as determined by is_other, reports an error.
• If from is a directory, but to is a regular file, reports an error.
• If from is a symbolic link, then
  • If copy_options::skip_symlink is present in options, does nothing.
  • Otherwise, if to does not exist and copy_options::copy_symlinks is present in options, then behaves as if copy_symlink(from, to).
  • Otherwise, reports an error.
• Otherwise, if from is a regular file, then
  • If copy_options::directories_only is present in options, does nothing.
  • Otherwise, if copy_options::create_symlinks is present in options, creates a symlink to to. Note: from must be an absolute path unless to is in the current directory.
  • Otherwise, if copy_options::create_hard_links is present in options, creates a hard link to to.
  • Otherwise, if to is a directory, then behaves as if copy_file(from, to/from.filename(), options) (creates a copy of from as a file in the directory to).
  • Otherwise, behaves as if copy_file(from, to, options) (copies the file).
• Otherwise, if from is a directory and either options has copy_options::recursive or is copy_options::none.
  • If to does not exist, first executes create_directory(to, from) (creates the new directory with a copy of the old directory's attributes).
  • Then, whether to already existed or was just created, iterates over the files contained in from as if by for (const directory_entry& x : directory_iterator(from)) and for each directory entry, recursively calls copy(x.path(), to/x.path().filename(), options | unspecified), where unspecified is a special bit that has no other effect when set in options (the sole purpose of setting this bit is to prevent recursive copying subdirectories if options is copy_options::none).
• Otherwise does nothing.

---

🎀 Parameters 🎀

• from — path to the source file, directory, or symlink
• to — path to the target file, directory, or symlink
• ec — out-parameter for error reporting in the non-throwing overload

---

🌸 Return value 🌸

(none) — literally no return value, bestie. She’s doing side effects, not handing you a little return gift. 💖

---

🔥 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. 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 noexcept specification: noexcept.

---

🦋 Notes 🦋

The default behavior when copying directories is the non-recursive copy: the files are copied, but not the subdirectories:

// Given
// /dir1 contains /dir1/file1, /dir1/file2, /dir1/dir2
// and /dir1/dir2 contains /dir1/dir2/file3
// After
std::experimental::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

While with copy_options::recursive, the subdirectories are also copied, with their content, recursively.

// ...but after
std::experimental::filesystem::copy("/dir1", "/dir3", 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

---

🧚 Example 🧚

// Run this code

#include <experimental/filesystem>
#include <fstream>
#include <iostream>
namespace fs = std::experimental::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)
    // sandbox holds 2 files and 2 directories, one of which has a subdirectory
    // sandbox/file1.txt
    // sandbox/file2.txt
    // sandbox/dir2
    // sandbox/dir
    //    sandbox/dir/subdir
    fs::copy("sandbox", "sandbox/copy", fs::copy_options::recursive);
    // sandbox/copy holds copies of the above files and subdirectories
    fs::remove_all("sandbox");
}

---

🌈 See also 🌈

• copy_options — specifies semantics of copy operations (enum)
• copy_symlink — copies a symbolic link (function)
• copy_file — copies file contents (function)

---

👑 Categories 👑

• Noindexed pages
• unconditionally noexcept

---

💀 Hidden categories 💀

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

---

mwah 💋 this page came from http://cppreference.com, date/version 2024.06.10, page title std::experi...system::copy(3). bye bestie, go copy something iconic 🫶✨