./_Man_SunOS_4.1.3_html/html2/rename.2v.html

Manual page for RENAME(2V)

rename - change the name of a file

SYNOPSIS

int rename(path1, path2)
char *path1, *path2;

DESCRIPTION

rename() renames the link named path1 as path2. If path2 exists, then it is first removed. If path2 refers to a directory, it must be an empty directory, and must not include path1 in its path prefix. Both path1 and path2 must be of the same type (that is, both directories or both non-directories), and must reside on the same file system. Write access permission is required for both the directory containing path1 and the directory containing path2. 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.

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

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

If the file referred to by path2 exists and the file's link count becomes zero when it is removed and no process has the file open, the space occupied by the file is freed, and the file is no longer accessible. If one or more processes have the file open when the last link is removed, the link is removed before rename() returns, but the file's contents are not removed until all references to the file have been closed.

Upon successful completion, rename() marks for update the st_ctime and st_mtime fields of the parent directory of each file.

RETURN VALUES

rename() returns:

0: on success.
-1: on failure and sets errno to indicate the error.

ERRORS

rename() will fail and neither path1 nor path2 will be affected if:

EACCES: Write access is denied for either path1 or path2.
: A component of the path prefix of either path1 or path2 denies search permission.
: The requested rename requires writing in a directory with access permissions that deny write permission.
EBUSY: path2 is a directory and is the mount point for a mounted file system.
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.
EFAULT: Either or both of path1 or path2 point outside the process's allocated address space.
EINVAL: path1 is a parent directory of path2.
: An attempt was made to rename `.' or `..'.
EIO: An I/O error occurred while reading from or writing to the file system.
EISDIR: path2 points to a directory and path1 points to a file that is not a directory.
ELOOP: Too many symbolic links were encountered while translating either path1 or path2.
ENAMETOOLONG: The length of either path argument exceeds {PATH_MAX}.
: A pathname component is longer than {NAME_MAX} while {_POSIX_NO_TRUNC} is in effect (see pathconf.2v
ENOENT: A component of the path prefix of either path1 or path2 does not exist.
: The file named by path1 does not exist.
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.
ENOTDIR: A component of the path prefix of either path1 or path2 is not a directory.
: path1 names a directory and path2 names a nondirectory file.
ENOTEMPTY: path2 is a directory and is not empty.
EROFS: The requested rename requires writing in a directory on a read-only file system.
EXDEV: The link named by path2 and the file named by path1 are on different logical devices (file systems).

SYSTEM V ERRORS

In addition to the above, the following may also occur:

ENOENT: path1 or path2 points to an empty string.

WARNINGS

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 not be used. System administrators should use symbolic links instead.