System Calls rename(2)
NAME
rename, renameat - change the name of a file
SYNOPSIS
#include
int rename(const char *old, const char *new);#include
int renameat(int fromfd, const char *old, int tofd,
const char *new); XPG3#include
int rename(const char *old, const char *new);DESCRIPTION
The rename() function changes the name of a file. The old argument points to the pathname of the file to be renamed. The new argument points to the new path name of the file.The renameat() function renames an entry in a directory,
possibly moving the entry into a different directory. See fsattr(5). If the old argument is an absolute path, the fromfd is ignored. Otherwise it is resolved relative to the fromfd argument rather than the current working directory. Similarly, if the new argument is not absolute, it is resolved relative to the tofd argument. If either fromfd ortofd have the value AT_FDCWD, defined in
their respective paths are relative, the path is resolved relative to the current working directory. Current implementation restrictions will cause the, and renameat() function to return an error if an attempt is made
to rename an extended attribute file to a regular (non-
attribute) file, or to rename a regular file to an extended attribute file. If old and new both refer to the same existing file, therename() and renameat() functions return successfully and
performs no other action.SunOS 5.11 Last change: 4 Oct 2007 1
System Calls rename(2)If old points to the pathname of a file that is not a direc-
tory, new must not point to the pathname of a directory. If the link named by new exists, it will be removed and old will be renamed to new. In this case, a link named new must remain visible to other processes throughout the renaming operation and will refer to either the file referred to by new or the file referred to as old before the operation began. If old points to the pathname of a directory, new must not point to the pathname of a file that is not a directory. If the directory named by new exists, it will be removed and old will be renamed to new. In this case, a link named new will exist throughout the renaming operation and will refer to either the file referred to by new or the file referred to as old before the operation began. Thus, if new names an existing directory, it must be an empty directory. The new pathname must not contain a path prefix that namesold. Write access permission is required for both the direc-
tory containing old and the directory containing new. If oldpoints to the pathname of a directory, write access permis-
sion is required for the directory named by old, and, if it exists, the directory named by new. If the directory containing old has the sticky bit set, at least one of the following conditions listed below must be true: o the user must own old o the user must own the directory containing old o old must be writable by the user o the user must be a privileged user If new exists, and the directory containing new is writable and has the sticky bit set, at least one of the following conditions must be true: o the user must own new o the user must own the directory containing new o new must be writable by the user o the user must be a privileged userSunOS 5.11 Last change: 4 Oct 2007 2
System Calls rename(2) If the link named by new exists, the file's link count becomes zero when it is removed, and no process has the file open, then the space occupied by the file will be freed and the file will no longer be accessible. If one or more processes have the file open when the last link is removed,the link will be removed before rename() or renameat()
returns, but the removal of the file contents will be post-
poned until all references to the file have been closed.Upon successful completion, the rename() and renameat()
functions will mark for update the st_ctime and st_mtime
fields of the parent directory of each file.RETURN VALUES
Upon successful completion, 0 is returned. Otherwise, -1 is
returned and errno is set to indicate an error.ERRORS
The rename() function will fail if: EACCES A component of either path prefix denies search permission; one of the directoriescontaining old and new denies write permis-
sions; or write permission is denied by a directory pointed to by old or new. EBUSY The new argument is a directory and the mount point for a mounted file system. EDQUOT The directory where the new name entry is being placed cannot be extended because the user's quota of disk blocks on that file system has been exhausted.EEXIST The link named by new is a directory con-
taining entries other than `.' (the direc-
tory itself) and `..' (the parent direc-
tory). EFAULT Either old or new references an invalid address.EILSEQ The path argument includes non-UTF8 charac-
ters and the file system accepts only file names where all characters are part of theUTF-8 character codeset.
SunOS 5.11 Last change: 4 Oct 2007 3
System Calls rename(2) EINVAL The new argument directory pathname contains a path prefix that names the old directory, or an attempt was made to rename a regular file to an extended attribute or from an extended attribute to a regular file.EIO An I/O error occurred while making or updat-
ing a directory entry. EISDIR The new argument points to a directory butold points to a file that is not a direc-
tory. ELOOP Too many symbolic links were encountered in translating the pathname.ENAMETOOLONG The length of old or new exceeds PATH_MAX,
or a pathname component is longer thanNAME_MAX while _POSIX_NO_TRUNC is in effect.
EMLINK The file named by old is a directory, and the link count of the parent directory ofnew would exceed LINK_MAX.
ENOENT The link named by old does not name anexisting file, a component of the path pre-
fix of new does not exist, or either old or new points to an empty string. ENOSPC The directory that would contain new cannot be extended. ENOTDIR A component of either path prefix is not a directory, or old names a directory and new names a file that is not a directory, ortofd and dirfd in renameat() do not refer-
ence a directory. EROFS The requested operation requires writing ina directory on a read-only file system.
SunOS 5.11 Last change: 4 Oct 2007 4
System Calls rename(2)EXDEV The links named by old and new are on dif-
ferent file systems.The renameat() functions will fail if:
ENOTSUP An attempt was made to rename a regular file as an attribute file or to rename an attribute file as a regular file.ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:_______________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|________________________________|
| Interface Stability | Committed ||_____________________________|________________________________|
| MT-Level | Async-Signal-Safe |
|_____________________________|________________________________|
| Standard | For rename(), see standards(5).||_____________________________|________________________________|
SEE ALSO
chmod(2), link(2), unlink(2), attributes(5), fsattr(5), standards(5) NOTESThe system can deadlock if there is a loop in the file sys-
tem graph. Such a loop can occur if there is an entry in directory a, a/name1, that is a hard link to directory b, and an entry in directory b, b/name2, that is a hard link to directory a. When such a loop exists and two separate processes attempt to rename a/name1 to b/name2 and b/name2 to a/name1, the system may deadlock attempting to lock both directories for modification. Use symbolic links instead of hard links for directories.SunOS 5.11 Last change: 4 Oct 2007 5