rename - rename or move a file
Standard C Library (libc, -lc)
#include <unistd.h>
int
rename(const char *oldname,
const char *newname);
The file (or other object) referenced by oldname is given the name newname, and the name oldname is removed. If newname already exists, it is removed as well. (The semantics for removing files and directories described under remove and rmdir must be honored.)
If newname exists, it must be a directory if and only if oldname also is.
If components of the path prefix of newname do not exist or are not directories, rename fails. Additionally, oldname and newname must refer to names on the same filesystem.
If oldname and newname are the same file, rename succeeds and the state of the filesystem is not altered. This is true even if they are not in the same directory. (POSIX says so. This is widely considered a bug in POSIX.)
Rename must be atomic; no other process on the system should be able to see the filesystem in a state where both (or neither) oldname and newname name the file. Additionally, if the system crashes, at least one name for the file must remain. (If you are implementing a file system with crash recovery, a crash during rename must, after recovery, produce a volume where the rename has either occurred or not occurred; no intermediate states may be exposed.)
If oldname is a directory, newname must not refer to a subdirectory of oldname, as this would create a (detached) cycle in the directory tree.
Renaming (or overwriting) the . or .. entries in directories is prohibited.
On success, rename returns 0. On error, -1 is returned, and errno is set according to the error encountered.
The following error codes should be returned under the conditions given. Other error codes may be returned for other errors not mentioned here.
| ENODEV | The device prefix of one of the names did not exist. | |
| ENOTDIR | A non-final component of one of the names was not a directory. | |
| ENOENT | A non-final component of newname did not exist. | |
| ENOENT | oldname does not exist. | |
| ENOTDIR | oldname is a directory, and newname is not. | |
| EISDIR | oldname is not a directory, and newname is. | |
| ENOTEMPTY | newname is a directory, and it is not empty. | |
| EXDEV | The two names are on different filesystems. | |
| EINVAL | newname is a subdirectory of oldname. | |
| EINVAL | An attempt was made to rename a . or .. entry. | |
| ENOSPC | The filesystem involved is full. | |
| EIO | A hard I/O error occurred. | |
| EFAULT | One of the arguments was an invalid pointer. |
As with rmdir, attempts to rename with newname equal to .. may generate either EINVAL or ENOTEMPTY.