RENAME(2) | System Calls | RENAME(2) |
#include <stdio.h> int rename(const char *old, const char *new);
#include <unistd.h> int renameat(int fromfd, const char *old, int tofd, const char *new);
#include <unistd.h> int rename(const char *old, const char *new);
The renameat() function renames an entry in a directory, possibly moving the entry into a different directory. See fsattr(7). 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 or tofd have the value AT_FDCWD, defined in <fcntl.h>, and their respective paths are relative, the path is resolved relative to the current working directory.
Current implementation restrictions will cause the 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, the rename() and renameat() functions return 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:
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:
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 postponed 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.
EACCES
EBUSY
EDQUOT
EEXIST
EFAULT
EILSEQ
EINVAL
EIO
EISDIR
ELOOP
ENAMETOOLONG
EMLINK
ENOENT
ENOSPC
ENOTDIR
EROFS
EXDEV
The renameat() function will fail if:
ENOTSUP
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
Interface Stability | Committed |
MT-Level | Async-Signal-Safe |
Standard | For rename(), see standards(7). |
September 29, 2020 | OmniOS |