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,	    (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
       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
	  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::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 op-
       tions, 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 over-
       load

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

Exceptions
	  Any overload not marked noexcept may throw std::bad_alloc if	memory
       allocation
	  fails.

	  1,3)	Throws	std::filesystem::filesystem_error on underlying	OS API
       errors,
	  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
       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.

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
       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		  2024.06.10	 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.1.quarterly>

home | help