NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SUMMARY OF TRUSTED SOLARIS CHANGES | SEE ALSO | WARNINGS
#include <stdio.h>int rename(const char *old, const char *new);
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 pathname of the file.
If old and new both refer to the same existing file, the rename() function returns successfully and performs no other action.
If old points to the pathname of a file that is not a directory, 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 names old. Write access permission is required for both the directory containing old and the directory containing new. If old points to the pathname of a directory, write access permission 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:
The user must own old
The user must own the directory containing old
old must be writable by the user
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:
the user must own new
the user must own the directory containing new
new must be writable by the user
the user must be a privileged user
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() returns, but the removal of the file contents will be postponed until all references to the file have been closed.
Upon successful completion, the rename() function will mark for update the st_ctime and st_mtime fields of the parent directory of each file.
A single-level directory cannot be renamed (single-level directories are always contained in multilevel directories). A multilevel directory cannot be the new containing directory. There is no privilege to bypass these restrictions.
The rename() function will fail if:
A component of either path prefix denies search permission; one of the directories containing old and new denies write permissions; or write
permission is denied by a directory pointed to by old or new. To bypass ownership restrictions, the calling process may assert one or more of these privileges: PRIV_FILE_DAC_SEARCH
, PRIV_FILE_MAC_SEARCH
, PRIV_FILE_MAC_WRITE
, PRIV_FILE_DAC_WRITE
, and PRIV_FILE_OWNER
.
The new argument is a directory and the mount point for a mounted file system.
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.
The link named by new is a directory containing entries other than `.' (the directory itself) and `..' (the parent directory).
The new argument directory pathname contains a path prefix that names the old directory.
The new argument points to a directory but old points to a file that is not a directory.
Too many symbolic links were encountered in translating the pathname.
The length of old or new exceeds PATH_MAX, or a pathname component is longer than NAME_MAX while _POSIX_NO_TRUNC is in effect.
The file named by old is a directory, and the link count of the parent directory of new would exceed LINK_MAX.
The link named by old does not exist, or either old or new points to an empty string.
The directory that would contain new cannot be extended.
A component of either path prefix is not a directory, or old names a directory and new names a nondirectory file.
The requested operation requires writing in a directory on a read-only file system.
The links named by old and new are on different file systems.
An I/O error occurred while making or updating a directory entry.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
MT-Level | Async-Signal-Safe |
Appropriate privilege is required to override access checks.
A single-level directory cannot be renamed. A multilevel directory cannot be the new containing directory. There is no privilege to bypass these restrictions.
The system can deadlock if there is a loop in the file system 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. The solution is to use symbolic links instead of hard links for directories.
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SUMMARY OF TRUSTED SOLARIS CHANGES | SEE ALSO | WARNINGS