[ Previous | Next | Table of Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Base Operating System and Extensions , Volume 2
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:
- The directory specified by the
FromPath parameter is not an ancestor of ToPath.
For example, the FromPath path name must not contain a path prefix
that names the directory specified by the ToPath parameter.
- The directory specified in the
FromPath parameter must be well-formed. A well-formed
directory contains both . (dot) and .. (dot dot)
entries. That is, the . (dot) entry in the FromPath
directory refers to the same directory as that in the FromPath
parameter. The .. (dot dot) entry in the
FromPath directory refers to the directory that contains an entry
for FromPath.
- The directory specified by
the ToPath parameter, if it exists, must be well-formed (as defined
previously).
| 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.
[ Previous | Next | Table of Contents | Index |
Library Home |
Legal |
Search ]