NAME
rename,
renameat —
change the name of a file
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <stdio.h>
int
rename(
const char
*from,
const char
*to);
#include <unistd.h>
int
renameat(
int
fromfd,
const char
*from,
int tofd,
const char *to);
DESCRIPTION
rename() causes the link named
from to
be renamed as
to. If
to exists, it
is first removed. Both
from and
to
must be of the same type (that is, both directories or both non-directories),
and must reside on the same file system.
rename() guarantees that an instance of
to will always exist, even if the system should crash in
the middle of the operation.
If the final component of
from is a symbolic link, the
symbolic link is renamed, not the file or directory to which it points.
If both
from and
to are pathnames of
the same existing file in the file system's name space,
rename() returns successfully and performs no other action.
renameat() works the same way as
rename()
except if
from (resp.
to) is
relative. In that case, it is looked up from a directory whose file descriptor
was passed as
fromfd (resp.
tofd).
Search permission is required on the directories named by
fromfd and
tofd.
fromfd or
tofd can be set to
AT_FDCWD
in order to specify the current directory.
RETURN VALUES
The
rename() and
renameat() functions return
the value 0 if successful; otherwise the value -1 is returned and
the global variable
errno is set to indicate the error.
ERRORS
rename() and
renameat() will fail and
neither of the argument files will be affected if:
-
-
- [
EACCES
]
- A component of either path prefix denies search permission,
or the requested link requires writing in a directory with a mode that
denies write permission.
-
-
- [
EBUSY
]
- from or to is
the mount point for a mounted file system.
-
-
- [
EDQUOT
]
- The directory in which the entry for the new name is being
placed cannot be extended because the user's quota of disk blocks on the
file system containing the directory has been exhausted.
-
-
- [
EFAULT
]
- from or to
points outside the process's allocated address space.
-
-
- [
EINVAL
]
- from is a parent directory of
to, or an attempt is made to rename
‘
.
’ or
‘..
’.
-
-
- [
EIO
]
- An I/O error occurred while making or updating a directory
entry.
-
-
- [
EISDIR
]
- to is a directory, but
from is not a directory.
-
-
- [
ELOOP
]
- Too many symbolic links were encountered in translating
either pathname.
-
-
- [
ENAMETOOLONG
]
- A component of a pathname exceeded
{
NAME_MAX
} characters, or an entire path name
exceeded {PATH_MAX
} characters.
-
-
- [
ENOENT
]
- A component of the from path does not
exist, or a path prefix of to does not exist.
-
-
- [
ENOSPC
]
- The directory in which the entry for the new name is being
placed cannot be extended because there is no space left on the file
system containing the directory.
-
-
- [
ENOTDIR
]
- A component of either path prefix is not a directory, or
from is a directory, but to is
not a directory.
-
-
- [
ENOTEMPTY
]
- to is a directory and is not
empty.
-
-
- [
EPERM
]
- The directory containing from is
marked sticky, and neither the containing directory nor
from are owned by the effective user ID. Or the
to file exists, the directory containing
to is marked sticky, and neither the containing
directory nor to are owned by the effective user
ID.
-
-
- [
EROFS
]
- The requested link requires writing in a directory on a
read-only file system.
-
-
- [
EXDEV
]
- The link named by to and the file
named by from are on different logical devices (file
systems). Note that this error code will not be returned if the
implementation permits cross-device links.
In addition,
renameat() will fail if:
-
-
- [
EBADF
]
- from or to does
not specify an absolute path and fromfd or
tofd, respectively, is neither
AT_FDCWD
nor a valid file descriptor open for
reading or searching.
-
-
- [
ENOTDIR
]
- from or to is
not an absolute path and fromfd or
tofd, respectively, is a file descriptor associated
with a non-directory file.
SEE ALSO
open(2),
symlink(7)
STANDARDS
The
rename() function deviates from the semantics defined in
IEEE Std 1003.1-1990 (“POSIX.1”), which
specifies that if both
from and
to
link to the same existing file,
rename()
shall return successfully and performs no further action, whereas this
implementation will remove the file specified by
from
unless both
from and
to are
pathnames of the same file in the file system's name space.
To retain conformance, a compatibility interface is provided by the
POSIX Compatibility Library (libposix, -lposix) which
is also be brought into scope if any of the
_POSIX_SOURCE
,
_POSIX_C_SOURCE
or
_XOPEN_SOURCE
preprocessor symbols are defined at
compile-time: the
rename() function conforms to
IEEE Std 1003.1-1990 (“POSIX.1”) and
X/Open Portability Guide Issue 4, Version 2
(“XPG4.2”).
renameat() conforms to
IEEE Std 1003.1-2008 (“POSIX.1”).
BUGS
The system can deadlock if a loop in the file system graph is present. This loop
takes the form of an entry in directory
‘
a
’, say
‘
a/foo
’, being a hard
link to directory ‘
b
’,
and an entry in directory
‘
b
’, say
‘
b/bar
’, being a hard
link to directory ‘
a
’.
When such a loop exists and two separate processes attempt to perform
‘
rename a/foo b/bar
’ and
‘
rename b/bar a/foo
’, respectively, the
system may deadlock attempting to lock both directories for modification. Hard
links to directories should be replaced by symbolic links by the system
administrator.