The rename
function is used to change a file's name.
rename
function renames the file oldname to
newname. The file formerly accessible under the name
oldname is afterwards accessible as newname instead. (If
the file had any other names aside from oldname, it continues to
have those names.)
The directory containing the name newname must be on the same file system as the directory containing the name oldname.
One special case for rename
is when oldname and
newname are two names for the same file. The consistent way to
handle this case is to delete oldname. However, in this case
POSIX requires that rename
do nothing and report success--which
is inconsistent. We don't know what your operating system will do.
If oldname is not a directory, then any existing file named
newname is removed during the renaming operation. However, if
newname is the name of a directory, rename
fails in this
case.
If oldname is a directory, then either newname must not
exist or it must name a directory that is empty. In the latter case,
the existing directory named newname is deleted first. The name
newname must not specify a subdirectory of the directory
oldname
which is being renamed.
One useful feature of rename
is that the meaning of newname
changes "atomically" from any previously existing file by that name to
its new meaning (i.e. the file that was called oldname). There is
no instant at which newname is non-existent "in between" the old
meaning and the new meaning. If there is a system crash during the
operation, it is possible for both names to still exist; but
newname will always be intact if it exists at all.
If rename
fails, it returns -1
. In addition to the usual
file name errors (see section File Name Errors), the following
errno
error conditions are defined for this function:
EACCES
EBUSY
ENOTEMPTY
EEXIST
ENOTEMPTY
for this, but some other systems return EEXIST
.
EINVAL
EISDIR
EMLINK
ENOENT
ENOSPC
EROFS
EXDEV
Go to the first, previous, next, last section, table of contents.