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

NAME
     std::experimental::filesystem::copy_file	 -   std::experimental::filesys-
     tem::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  op-
     tions.
	2)  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
	copy_file).
	  * 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:

	  * 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 op-
     tions, 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 filesys-
     tem_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  er-
     ror_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

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