SysTutorials

Linux Manual Pages › Section 3

stdexperimentalfilesystemcopy_file(3)

std::experimental::filesystem::copy_file – std::experimental::filesystem::copy_file

Synopsis

Defined in header<experimental / filesystem>
    bool copy_file(const path &from, const path &to);
(1)(filesystem TS)
    bool copy_file(const path &from, const path &to, error_code &ec);
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);

1) The default, equivalent to (2) with copy_options::none used as options
2) 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 copy_file)
* 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…
      * 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
      * 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.

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.

Exceptions

The overload that does not take a 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 a 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 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.

Examples

// Run this code

#include <fstream>
#include <iostream>
#include <experimental/filesystem>
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() << '
';
    std::cout << "file2.txt holds : "
              << std::ifstream("sandbox/file2.txt").rdbuf() << '
';
    // 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() << '
';
    }
    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"

See also

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