rename

OS/161 Reference Manual

Name

rename - rename or move a file

Library

Standard C Library (libc, -lc)

Synopsis

#include <unistd.h>

int
rename(const char *oldname, const char *newname);

Description

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.

Return Values

On success, rename returns 0. On error, -1 is returned, and errno is set according to the error encountered.

Errors

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.