rename
Purpose
Renames a directory or a file within a file system.
Syntax
int rename (frompath, topath)
char *frompath, *topath;
Description
The rename system call renames a directory or a file
within a file system. The frompath and topath parameters
must both be either files or directories and must reside
on the same node. If Distributed Services is installed
on your system, this node can be remote.
For rename to execute successfully, the calling process
must have write permission to the parent directories of
both frompath and topath, to frompath, and to topath, if
it already exists.
The file or directory named by frompath cannot contain
the file or directory named by topath. If topath is an
existing file or empty directory, it is replaced by
frompath. If topath is a nonempty directory, rename
exits with an error.
Return Value
Upon successful completion, the rename system call
returns a value of 0. If the rename system call fails, a
value of -1 is returned, and errno is set to indicate the
error.
Diagnostics
The rename system call fails and the file or directory
name remains unchanged if one or more of the following
are true:
ENOTDIR A component of either path prefix is not a
directory or frompath names a directory and
topath names a nondirectory.
EISDIR The topath parameter names a directory and the
frompath parameter names a nondirectory.
ENOENT A component of either path does not exist or
the file named by frompath does not exist.
EACCES Creating the requested link requires writing
in a directory with a mode that denies write
permission.
EACCES Search permission is denied on a component of
either frompath or topath.
EXDEV The link named by topath and the file named by
frompath are on different file systems.
EROFS The named file resides on a read-only file
system.
EFAULT Either frompath or topath points outside of
the process's allocated address space.
EBUSY The frompath or topath directory is currently
in use by the system or by another process.
EINVAL The frompath or the topath is either the
current directory or the parent of the current
directory.
EINVAL frompath is a parent directory of topath.
EEXIST The topath parameter is an existing nonempty
directory.
ESTALE The process's root or current directory is
located in a virtual file system that has been
unmounted.
If Distributed Services is installed on your system,
rename can also fail if one or more of the following are
true:
EDIST The server has blocked new inbound
requests.
EDIST Outbound requests are currently blocked.
EDIST The server has a release level of Distrib-
uted Services that cannot communicate with
this node.
EAGAIN The server is too busy to accept the
request.
ESTALE The file descriptor for a remote file has
become obsolete.
EPERM The translate tables of the server did not
contain any entry for either the effective
user ID or effective group ID of the
calling process.
ENODEV The named file is a remote file located on
a device that has been unmounted at the
server.
ENOMEM Either this node or the server does not
have enough memory available to service the
request.
ENOCONNECT An attempt to establish a new network con-
nection with a remote node failed.
EBADCONNECT An attempt to use an existing network con-
nection with a remote node failed.
Related Information
In this book: "chmod" and "mkdir."
The chmod, mkdir, and mknod, and mvdir commands in AIX
Operating System Commands Reference.