Copies files and directories, with a variety of options.

The behavior is as follows:

• First, before doing anything else, obtains type and permissions offrom by no more than a single call to

• std::filesystem::symlink_status, ifcopy_options::skip_symlinks,copy_options::copy_symlinks, orcopy_options::create_symlinks is present inoptions;
• std::filesystem::status otherwise.

• If necessary, obtains the status ofto, by no more than a single call to

• std::filesystem::symlink_status, ifcopy_options::skip_symlinks orcopy_options::create_symlinks is present inoptions;
• std::filesystem::status otherwise (including the case wherecopy_options::copy_symlinks is present inoptions).

• If eitherfrom orto has an implementation-definedfile type, the effects of this function are implementation-defined.
• Iffrom does not exist, reports an error.
• Iffrom andto are the same file as determined bystd::filesystem::equivalent, reports an error.
• If eitherfrom orto is not a regular file, a directory, or a symlink, as determined bystd::filesystem::is_other, reports an error.
• Iffrom is a directory, butto is a regular file, reports an error.
• Iffrom is a symbolic link, then

• Ifcopy_options::skip_symlink is present inoptions, does nothing.
• Otherwise, ifto does not exist andcopy_options::copy_symlinks is present inoptions, then behaves as ifcopy_symlink(from, to).
• Otherwise, reports an error.

• Otherwise, iffrom is a regular file, then

• Ifcopy_options::directories_only is present inoptions, does nothing.
• Otherwise, ifcopy_options::create_symlinks is present inoptions, creates a symlink toto. Note:from must be an absolute path unlessto is in the current directory.
• Otherwise, ifcopy_options::create_hard_links is present inoptions, creates a hard link toto.
• Otherwise, ifto is a directory, then behaves as ifcopy_file(from, to/from.filename(), options) (creates a copy offrom as a file in the directoryto).
• Otherwise, behaves as ifcopy_file(from, to, options) (copies the file).

• Otherwise, iffrom is a directory andcopy_options::create_symlinks is set inoptions, reports an error with an error code equal tostd::make_error_code(std::errc::is_a_directory).
• Otherwise, iffrom is a directory and eitheroptions hascopy_options::recursive or iscopy_options::none,

• Ifto does not exist, first executescreate_directory(to, from) (creates the new directory with a copy of the old directory's attributes).
• Then, whetherto already existed or was just created, iterates over the files contained infrom as if byfor(conststd::filesystem::directory_entry& x:std::filesystem::directory_iterator(from)) and for each directory entry, recursively callscopy(x.path(), to/x.path().filename(), options| in-recursive-copy), wherein-recursive-copy is a special bit that has no other effect when set inoptions. (The sole purpose of setting this bit is to prevent recursive copying subdirectories ifoptions iscopy_options::none.)

• Otherwise does nothing.

[edit]Parameters

[edit]Return value

(none)

[edit]Exceptions

Any overload not markednoexcept may throwstd::bad_alloc if memory allocation fails.

[edit]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// Afterstd::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 withcopy_options::recursive, the subdirectories are also copied, with their content, recursively.

// ...but afterstd::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

[edit]Example

#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)constauto 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

[edit]Defect reports

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

[edit]See also

• In other languages

• Español
• 日本語
• 中文