home | help 
std::filesystem::copy_file(3)  C++ Standard Libary std::filesystem::copy_file(3)

NAME
     std::filesystem::copy_file - std::filesystem::copy_file

Synopsis
	Defined in header <filesystem>
	bool  copy_file(  const  std::filesystem::path&  from,	      (1) (since
     C++17)
			const std::filesystem::path& to );
	bool copy_file( const std::filesystem::path& from,

			const  std::filesystem::path&  to,	    (2)   (since
     C++17)

			std::error_code& ec );
	bool copy_file( const std::filesystem::path& from,

			const	std::filesystem::path&	to,	     (3)  (since
     C++17)

			std::filesystem::copy_options options );
	bool copy_file( const std::filesystem::path& from,

			const  std::filesystem::path&  to,	    (4)   (since
     C++17)
			std::filesystem::copy_options options,

			std::error_code& ec );

	1,2)  The  default,  equivalent to (3,4) with copy_options::none used as
     options.
	3,4) Copies a single file from from to to, using the copy options  indi-
     cated 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
	filesystem::copy_file).
	  *  If  !filesystem::is_regular_file(from)  (either  because the source
     file doesn't
	    exist or because it is not a regular file), report an error.
	  * Otherwise, if the destination file does not exist,

	  * copies the contents and the attributes of the file to which from re-
     solves to the
	    file to which to resolves (symlinks are followed).
	  * Otherwise, if the destination file already exists,

	  * report an error if any of the following is true:

	  * to and from  are  the  same  as  determined  by  filesystem::equiva-
     lent(from, to);
	  *  to  is  not  a  regular file as determined by !filesystem::is_regu-
     lar_file(to);
	  * none of the filesystem::copy_file control options  are  set  in  op-
     tions.
	  *  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	filesys-
     tem::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
	Any overload not marked noexcept may throw std::bad_alloc if memory  al-
     location
	fails.

	1,3)  Throws  std::filesystem::filesystem_error on underlying OS API er-
     rors,
	constructed with from as the first path argument, to as the second  path
     argument,
	and the OS error code as the error code argument.
	2,4) Sets a std::error_code& parameter to the OS API error code if an OS
     API call
	fails, and executes ec.clear() if no errors occur.

Notes
	The  functions	involve  at most one direct or indirect call to filesys-
     tem::status(to)
	(used both to determine if the file exists, and, for
	filesystem::copy_options::update_existing option, its last write time).

	Error is reported when filesystem::copy_file is used to  copy  a  direc-
     tory: use
	filesystem::copy for that.

	filesystem::copy_file follows symlinks: use filesystem::copy_symlink or
	filesystem::copy with filesystem::copy_options::copy_symlinks for that.

Example
     // Run this code

      #include <filesystem>
      #include <fstream>
      #include <iostream>
      namespace fs = std::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"

	Defect reports

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

	   DR	 Applied to		 Behavior as published		    Cor-
     rect behavior
	LWG   3014  C++17	error_code  overload  marked  noexcept	but  can
     noexcept removed
			    allocate memory

See also
	copy_options specifies semantics of copy operations
	(C++17)      (enum)
	copy_symlink copies a symbolic link
	(C++17)      (function)
	copy	     copies files or directories
	(C++17)      (function)

http://cppreference.com 	   2024.06.10	   std::filesystem::copy_file(3)
home | help