Renames a directory or a file.
Standard C Library (libc.a)
int rename ( FromPath, ToPath)
const char *FromPath, *ToPath;
The rename subroutine renames a directory or a file within a file system.
To use the rename subroutine, the calling process must have write and search permission in the parent directories of both the FromPath and ToPath parameters. If the path defined in the FromPath parameter is a directory, the calling process must have write and search permission to the FromPath directory as well.
If the FromPath and ToPath parameters both refer to the same existing file, the rename subroutine returns successfully and performs no other action.
The components of both the FromPath and ToPath parameters must be of the same type (that is, both directories or both non-directories) and must reside on the same file system. If the ToPath file already exists, it is first removed. Removing it guarantees that a link named ToPath will exist throughout the operation. This link refers to the file named by either the ToPath or FromPath parameter before the operation began.
If the final component of the FromPath parameter is a symbolic link, the symbolic link (not the file or directory to which it points) is renamed. If the ToPath is a symbolic link, the link is destroyed.
If the parent directory of the FromPath parameter has the Sticky bit attribute (described in the sys/mode.h file), the calling process must have an effective user ID equal to the owner ID of the FromPath parameter, or to the owner ID of the parent directory of the FromPath parameter.
A user who is not the owner of the file or directory must have root user authority to use the rename subroutine.
If the FromPath and ToPath parameters name directories, the following must be true:
|FromPath||Identifies the file or directory to be renamed.|
|ToPath||Identifies the new path name of the file or directory to be renamed. If ToPath is an existing file or empty directory, it is replaced by FromPath. If ToPath specifies a directory that is not empty, the rename subroutine exits with an error.|
Upon successful completion, the rename subroutine returns a value of 0. Otherwise, a value of -1 is returned, and the errno global variable is set to indicate the error.
The rename subroutine
is unsuccessful and the file or directory name remains unchanged if one or
more of the following are true:
|EACCES||Creating the requested link requires writing in a directory mode that denies the process write permission.|
|EBUSY||The directory named by the FromPath or ToPath parameter is currently in use by the system, or the file named by FromPath or ToPath is a named STREAM.|
|EDQUOT||The directory that would contain the path specified by the ToPath parameter cannot be extended because the user's or group's quota of disk blocks on the file system containing the directory is exhausted.|
|EEXIST||The ToPath parameter specifies an existing directory that is not empty.|
|EINVAL||The path specified in the FromPath or ToPath parameter is not a well-formed directory (FromPath is an ancestor of ToPath), or an attempt has been made to rename . (dot) or .. (dot dot).|
|EISDIR||The ToPath parameter names a directory and the FromPath parameter names a non-directory.|
|EMLINK||The FromPath parameter names a directory that is larger than the maximum link count of the parent directory of the ToPath parameter.|
|ENOENT||A component of either path does not exist, the file named by the FromPath parameter does not exist, or a symbolic link was named, but the file to which it refers does not exist.|
|ENOSPC||The directory that would contain the path specified in the ToPath parameter cannot be extended because the file system is out of space.|
|ENOTDIR||The FromPath parameter names a directory and the ToPath parameter names a non-directory.|
|ENOTEMPTY||The ToPath parameter specifies an existing directory that is not empty.|
|EROFS||The requested operation requires writing in a directory on a read-only file system.|
|ETXTBSY||The ToPath parameter names a shared text file that is currently being used.|
|EXDEV||The link named by the ToPath parameter and the file named by the FromPath parameter are on different file systems.|
If Network File System (NFS) is
installed on the system, the rename subroutine can be unsuccessful
if the following is true:
|ETIMEDOUT||The connection timed out.|
The rename subroutine can be unsuccessful for other reasons. See "Base Operating System Error Codes For Services That Require Path-Name Resolution" for a list of additional errors.
This subroutine is part of Base Operating System (BOS) Runtime.
The chmod subroutine, link subroutine, mkdir subroutine, rmdir (rmdir Subroutine) subroutine, unlink (unlink Subroutine) subroutine.
The chmod command, mkdir command, mv command, mvdir command.
Files, Directories, and File Systems for Programmers in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.