std::experimental::filesystem::copy_file (3) - Linux Manuals

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

NAME

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() << '\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"