Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
std::filesystem::copy_file(3) C++ Standard Libarystd::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,

	  const	std::filesystem::path& to );
	  bool copy_file( const	std::filesystem::path& from, (1) (since	C++17)
	  const	std::filesystem::path& to,

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

	  const	std::filesystem::path& to,
	  std::filesystem::copy_options	options	);
	  bool copy_file( const	std::filesystem::path& from, (2) (since	C++17)
	  const	std::filesystem::path& to,
	  std::filesystem::copy_options	options,

	  std::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  in-
       dicated 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
		       resolves	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::equivalent(from, to);
				  * to is not a	regular	file as	determined by
				    !filesystem::is_regular_file(to)
				  *  none of the filesystem::copy_file control
       options are set
				    in options

		     * Otherwise, if copy_options::skip_existing is set	in op-
       tions, 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
		       filesystem::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 over-
       load

Return value
	  true if the file was copied, false otherwise.

Exceptions
	  The overload that does not take a std::error_code& parameter throws
	  filesystem::filesystem_error	on  underlying	OS  API	 errors,  con-
       structed	with from as
	  the  first path argument, to as the second path argument, and	the OS
       error code as
	  the error code argument. The overload	taking a std::error_code&  pa-
       rameter sets it to
	  the  OS  API	error  code  if	 an  OS	 API  call fails, and executes
       ec.clear() if no	errors
	  occur. Any overload not marked noexcept may throw std::bad_alloc  if
       memory
	  allocation fails.

Notes
	  The  functions  involve  at  most  one  direct  or  indirect call to
       filesystem::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 di-
       rectory:	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.

Examples
       // Run this code

	#include <fstream>
	#include <iostream>
	#include <filesystem>
	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
       Correct 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		  2022.07.31	 std::filesystem::copy_file(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::filesystem::copy_file&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help