Renames a directory or a file.
Standard C Library (libc.a)
#include <stdio.h>
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:
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:
If Network File System (NFS) is installed on the system, the rename subroutine can be unsuccessful if the following is true:
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.
The rename subroutine can be unsuccessful for other reasons. See Appendix A, "Base Operating System Error Codes For Services That Require Path-Name Resolution" on page A-1 for a list of additional errors.
This subroutine is part of Base Operating System (BOS) Runtime.
The chmod subroutine, link subroutine, mkdir subroutine, rmdir subroutine, unlink subroutine.
The chmod command, mkdir command, mv command, mvdir command.
Files, Directories, and File Systems for Programmers in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.