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

FreeBSD Manual Pages

  
 
  

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

NAME
       std::filesystem::rename - std::filesystem::rename

Synopsis
	  Defined in header <filesystem>
	  void rename( const std::filesystem::path& old_p,   (1) (since	C++17)
		       const std::filesystem::path& new_p );
	  void rename( const std::filesystem::path& old_p,

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

		       std::error_code&	ec ) noexcept;

	  Moves	 or renames the	filesystem object identified by	old_p to new_p
       as if by	the
	  POSIX	rename:

	    * If old_p is a non-directory file,	then new_p must	be one of:

	    * the same file as old_p or	a hardlink to it: nothing is  done  in
       this case.
	    * existing non-directory file: new_p is first deleted, then, with-
       out allowing
	      other  processes to observe new_p	as deleted, the	pathname new_p
       is linked to the
	      file and old_p is	unlinked from the file.	Write permissions  are
       required	to both
	      the  directory  that  contains old_p and the directory that con-
       tains new_p.
	    * non-existing file	in an existing directory: The  pathname	 new_p
       is linked to the
	      file  and	old_p is unlinked from the file. Write permissions are
       required	to both
	      the directory that contains old_p	and the	 directory  that  con-
       tains new_p.
	    * If old_p is a directory, then new_p must be one of:

	    * the same directory as old_p or a hardlink	to it: nothing is done
       in this case.
	    *  existing	directory: new_p is deleted if empty on	POSIX systems,
       but this	may be
	      an error on other	systems. If not	an error, then new_p is	 first
       deleted,	then,
	      without  allowing	 other	processes to observe new_p as deleted,
       the pathname new_p
	      is linked	to the directory and old_p is unlinked from the	direc-
       tory. Write
	      permissions are required to both	the  directory	that  contains
       old_p and the
	      directory	that contains new_p.
	    *  non-existing  directory,	not ending with	a directory separator,
       and whose parent
	      directory	exists:	The pathname new_p is linked to	the  directory
       and old_p is
	      unlinked	from  the directory. Write permissions are required to
       both the
	      directory	that contains old_p and	the  directory	that  contains
       new_p.
	    *  Symlinks	 are not followed: if old_p is a symlink, it is	itself
       renamed,	not its
	      target. If new_p is an existing symlink, it  is  itself  erased,
       not its target.

	  Rename fails if

	    * new_p ends with dot or with dot-dot.
	    *  new_p  names  a	non-existing directory ending with a directory
       separator.
	    * old_p is a directory which is an ancestor	of new_p.

Parameters
	  old_p	- path to move or rename
	  new_p	- target path for the move/rename operation
	  ec	- out-parameter	for error reporting in the non-throwing	 over-
       load

Return value
	  (none)

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

	  1) Throws std::filesystem::filesystem_error on underlying OS API er-
       rors, constructed
	  with old_p as	the first path argument, new_p as the second path  ar-
       gument, and the OS
	  error	code as	the error code argument.
	  2)  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.

Example
       // Run this code

	#include <filesystem>
	#include <fstream>
	namespace fs = std::filesystem;

	int main()
	{
	    std::filesystem::path p = std::filesystem::current_path() /	"sand-
       box";
	    std::filesystem::create_directories(p / "from");
	    std::ofstream{ p / "from/file1.txt"	}.put('a');
	    std::filesystem::create_directory(p	/ "to");

	//  fs::rename(p / "from/file1.txt", p / "to/"); // error: "to"	 is  a
       directory
	    fs::rename(p / "from/file1.txt", p / "to/file2.txt"); // OK
	//  fs::rename(p / "from", p / "to"); // error:	"to" is	not empty
	    fs::rename(p / "from", p / "to/subdir"); //	OK

	    std::filesystem::remove_all(p);
	}

See also
	  rename     renames a file
		     (function)
	  remove     removes a file or empty directory
	  remove_all  removes a	file or	directory and all its contents,	recur-
       sively
	  (C++17)    (function)
	  (C++17)

http://cppreference.com		  2024.06.10	    std::filesystem::rename(3)

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

home | help