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 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:
- 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() 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.
|