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

NAME
     std::experimental::filesystem::rename  - std::experimental::filesystem::re-
     name

Synopsis
	Defined in header <experimental/filesystem>
	void rename( const path& old_p, const path& new_p );
	void rename( const path&  old_p,  const  path&	new_p,	std::error_code&
     (filesystem TS)
	ec );

	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, without
     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 re-
     quired to both
	    the directory that contains old_p and the  directory  that	contains
     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  re-
     quired to both
	    the  directory  that  contains old_p and the directory that contains
     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 directory.
     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  re-
     named, 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 separa-
     tor.
	  * 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 overload

Return value
	(none)

Exceptions
	The overload that does not take an error_code& parameter throws filesys-
     tem_error on
	underlying OS API errors, constructed with old_p as the first  argument,
     new_p 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

Example
     // Run this code

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

      int main()
      {
	  fs::path p = fs::current_path() / "sandbox";
	  fs::create_directories(p/"from");
	  std::ofstream(p/"from/file1.txt").put('a');
	  fs::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

	  fs::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, recursively
		   (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...stem::rename(3)
home | help