std::experimental::filesystem::copy_file(3)

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 );
   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 );
   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 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 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.

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"

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