NAME

rename − change the name of a file

SYNOPSIS

int rename(from, to)
char ∗from, ∗to;

DESCRIPTION

rename() renames the link named from as to. If to exists, then it is first removed.  Both from and to must be of the same type (that is, both directories or both non-directories), and must reside on the same file system. 

rename() guarantees that an instance of to will always exist, even if the system should crash in the middle of the operation. 

If the final component of from is a symbolic link, the symbolic link is renamed, not the file or directory to which it points. 

RETURN VALUE

A 0 value is returned if the operation succeeds, otherwise rename() returns −1 and the global variable errno indicates the reason for the failure. 

ERRORS

rename() will fail and neither of the argument files will be affected if any of the following are true:

ENOTDIR A component of the path prefix of either from or to is not a directory. 

ENAMETOOLONG The length of a component of either from or to exceeds 255 characters, or the length of either from or to exceeds 1023 characters. 

ENOENT A component of the path prefix of either from or to does not exist. 

ENOENT The file named by from does not exist. 

EACCES A component of the path prefix of either from or to denies search permission. 

EACCES The requested rename requires writing in a directory with a mode that denies write permission.  If a rename request relocates a directory in the hierarchy, write permission in the directory to be moved is needed, since its entry for the parent directory (..) must be updated. 

ELOOP Too many symbolic links were encountered while translating either from or to.

EXDEV The link named by to and the file named by from are on different logical devices (file systems). 

ENOSPC The directory in which the entry for the new name is being placed cannot be extended because there is no space left on the file system containing the directory. 

EDQUOT The directory in which the entry for the new name is being placed cannot be extended because the user’s quota of disk blocks on the file system containing the directory has been exhausted. 

EIO An I/O error occurred while reading from or writing to the file system. 

EROFS The requested rename requires writing in a directory on a read-only file system. 

EFAULT Either or both of from or to point outside the process’s allocated address space. 

EINVAL from is a parent directory of to, or an attempt is made to rename ‘.’ or ‘..’. 

ENOTEMPTY to is a directory and is not empty. 

EBUSY to is a directory and is the mount point for a mounted file system. 

SEE ALSO

open(2V)

WARNING

The system can deadlock if a loop in the file system graph is present.  This loop takes the form of an entry in directory a, say a/file1, being a hard link to directory b, and an entry in directory b, say b/file2, being a hard link to directory a.  When such a loop exists and two separate processes attempt to perform ‘rename a/file1 b/file2’ and ‘rename b/file2 a/file1’, respectively, the system may deadlock attempting to lock both directories for modification.  Hard links to directories should be replaced by symbolic links by the system administrator. 

Sun Release 4.0  —  Last change: 22 March 1989